@pai/client-http

Package: @pai/client-http

createPaiHttpClient

type HttpAgentTransportOptions = {
  url: string;
  fetch?: typeof globalThis.fetch;
  headers?: HttpAgentClientHeaders;
  credentials?: RequestCredentials;
  telemetry?: HttpAgentClientTelemetry;
};

type PaiContractShape = {
  agents: Record<string, AgentContract>;
};

function createPaiHttpClient<TPai extends PaiContractShape>(
  options: HttpAgentTransportOptions,
): PaiHttpClient<TPai>;

The app URL is the route where the Hono or Express PAI receiver is mounted. Call .agent(id) to select a registered agent:

const paiClient = createPaiHttpClient<AssistantPai>({
  url: "/api/pai",
});

const assistant = paiClient.agent("main");

createHttpAgentTransport() exposes the lower-level AgentClientTransport implementation for one agent endpoint.

PaiHttpError

class PaiHttpError extends Error {
  readonly phase: "response" | "stream";
  readonly status?: number;
  readonly code?: string;
  readonly errorId?: string;
  readonly retryable?: boolean;
}

The transport throws PaiHttpError for a non-success response or established SSE stream failure that is not one of PAI's portable typed domain errors. Network and response-decoding failures use phase: "response"; SSE read, decoding, and malformed-event failures use phase: "stream". status is present when an HTTP response exists and absent when opening the request fails or an already-established stream reports an error.

message, code, retryable, and errorId are client-safe fields. The original server exception is available only through the server diagnostic hook. Known thread error DTOs are reconstructed into their existing portable classes before this fallback is used. Unexpected server metadata is trusted only when it matches PAI's versioned safe-error DTO; proxy and transport details receive a generic message. Caller abort reasons remain unchanged.

try {
  await assistant.thread("thread-1").stop();
} catch (error) {
  if (error instanceof PaiHttpError) {
    showError(error.message, { reference: error.errorId });
  }
}

See Client Errors.