@cavi-ai/api-client/core/transport

export declare function abortableSleep(delayMs: number, signal?: AbortSignal): Promise<void>;

export declare function computeBackoffDelay(policy: TransportRetryPolicy, attempt: number, random: number, retryAfterMs?: number): number;

export declare function contentLengthCodec<T = unknown>(options?: ContentLengthCodecOptions): TransportFrameCodec<T>;

export type ContentLengthCodecOptions = Readonly<{
    maxHeaderBytes?: number;
    maxBodyBytes?: number;
}>;

export declare function createFramedMessageChannel<T>(bytes: TransportByteChannel, codec: TransportFrameCodec<T>): TransportMessageChannel<T>;

export declare function createHttpTransport(options: HttpTransportOptions): HttpTransport;

export declare function createJsonRpcTransport(options: CreateJsonRpcTransportOptions): JsonRpcTransport;

export type CreateJsonRpcTransportOptions = Readonly<{
    channel: TransportMessageChannel<unknown>;
    id?: () => JsonRpcId;
    onProtocolError?: (error: TransportError) => void;
}>;

export declare function createSseTransport(transportOptions: SseTransportOptions): SseTransport;

export declare function createTransportLifecycle(listener?: (event: TransportLifecycleEvent) => void): TransportLifecycle;

export declare function createWebSocketTransport(transportOptions?: WebSocketTransportOptions): WebSocketTransport;

export declare function getTransportErrorMetadata(error: unknown): TransportErrorMetadata | undefined;

export interface HttpTransport {
    request<T = unknown>(request: HttpTransportRequest): Promise<T>;
}

export type HttpTransportOptions = Readonly<{
    baseUrl: string;
    defaultHeaders?: Readonly<Record<string, string>>;
    auth?: TransportAuthResolver;
    fetchImpl?: typeof fetch;
    dependencies?: Partial<TransportDependencies>;
    onLifecycleEvent?: (event: TransportLifecycleEvent) => void;
}>;

export type HttpTransportRequest = Readonly<{
    method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
    path: string;
    headers?: Readonly<Record<string, string>>;
    body?: BodyInit | null;
    response?: "response" | "json" | "text" | "bytes";
    idempotencyKey?: string;
    retry?: TransportRetryPolicy;
    signal?: AbortSignal;
}>;

export type JsonFrameCodecOptions = Readonly<{
    maxFrameBytes?: number;
}>;

export declare function jsonLinesCodec<T = unknown>(options?: JsonFrameCodecOptions): TransportFrameCodec<T>;

export interface JsonRpcTransport {
    request<T = unknown>(method: string, params?: unknown, options?: {
        signal?: AbortSignal;
    }): Promise<T>;
    notify(method: string, params?: unknown, options?: {
        signal?: AbortSignal;
    }): Promise<void>;
    onNotification(listener: (method: string, params: unknown) => void): () => void;
    close(): Promise<void>;
}

export declare function jsonTextCodec<T = unknown>(options?: JsonFrameCodecOptions): TransportFrameCodec<T>;

export declare function normalizeTransportAbort(signal?: AbortSignal, cause?: unknown): ApiClientError;

export declare function resolveTransportHeaders(defaults?: Readonly<Record<string, string>>, resolver?: TransportAuthResolver): Promise<Record<string, string>>;

export declare function runTransportAttempts<T>(options: Readonly<{
    kind: TransportKind;
    operation: string;
    safety: TransportOperationSafety;
    policy: TransportRetryPolicy;
    execute: (context: TransportAttemptContext) => Promise<T>;
    auth?: TransportAuthResolver;
    headers?: Readonly<Record<string, string>>;
    dependencies?: Partial<TransportDependencies>;
    lifecycle?: TransportLifecycle;
    signal?: AbortSignal;
}>): Promise<T>;

export type SseConnectOptions = Readonly<{
    path: string;
    headers?: Readonly<Record<string, string>>;
    cursor?: string;
    reconnect?: TransportReconnectPolicy;
    signal?: AbortSignal;
    onMessage: (message: SseMessage) => void;
}>;

export interface SseSubscription {
    readonly done: Promise<void>;
    close(): void;
}

export interface SseTransport {
    subscribe(options: SseConnectOptions): SseSubscription;
}

export type SseTransportOptions = Readonly<{
    baseUrl: string;
    defaultHeaders?: Readonly<Record<string, string>>;
    auth?: TransportAuthResolver;
    fetchImpl?: typeof fetch;
    dependencies?: Partial<TransportDependencies>;
    onLifecycleEvent?: (event: TransportLifecycleEvent) => void;
}>;

export type TransportAttemptContext = Readonly<{
    attempt: number;
    headers: Readonly<Record<string, string>>;
    signal?: AbortSignal;
}>;

export type TransportAuth = Readonly<{
    headers?: Readonly<Record<string, string>>;
}>;

export type TransportAuthResolver = () => TransportAuth | Promise<TransportAuth>;

export interface TransportByteChannel {
    write(chunk: Uint8Array, signal?: AbortSignal): Promise<void>;
    subscribe(listener: (chunk: Uint8Array) => void): () => void;
    /** Invokes once on local or remote close, immediately when already closed. */
    subscribeClose(listener: (error?: unknown) => void): () => void;
    close(): Promise<void>;
}

export type TransportDependencies = Readonly<{
    now: () => number;
    random: () => number;
    sleep: (delayMs: number, signal?: AbortSignal) => Promise<void>;
}>;

export declare class TransportError extends ApiClientError {
    readonly transport: TransportErrorMetadata;
    constructor(message: string, options: {
        metadata: TransportErrorMetadata;
        cause?: unknown;
    });
}

export type TransportErrorMetadata = Readonly<{
    kind: TransportKind;
    phase: TransportPhase;
    operation: string;
    retryable: boolean;
    attempt: number;
    status?: number;
    code?: string | number;
    retryAfterMs?: number;
}>;

export interface TransportFrameCodec<T> {
    encode(value: T): Uint8Array;
    createDecoder(): TransportFrameDecoder<T>;
}

export interface TransportFrameDecoder<T> {
    push(chunk: Uint8Array): readonly T[];
    finish(): readonly T[];
}

export type TransportKind = "http" | "sse" | "websocket" | "json-rpc" | "stdio" | "unix";

export type TransportLifecycle = Readonly<{
    emit: (event: TransportLifecycleEvent) => void;
    subscribe: (listener: (event: TransportLifecycleEvent) => void) => () => void;
}>;

export type TransportLifecycleEvent = Readonly<{
    state: "connecting" | "connected" | "retrying" | "reconnected" | "closed";
    kind: TransportKind;
    operation: string;
    attempt: number;
    delayMs?: number;
}>;

export interface TransportMessageChannel<T = unknown> {
    send(message: T, signal?: AbortSignal): Promise<void>;
    subscribe(listener: (message: T) => void): () => void;
    /** Invokes once on local or remote close, immediately when already closed. */
    subscribeClose(listener: (error?: unknown) => void): () => void;
    close(reason?: string): Promise<void>;
}

export type TransportOperationSafety = "read" | "idempotent" | "connection" | "mutation";

export type TransportPhase = "configure" | "authenticate" | "connect" | "request" | "decode" | "close";

export type TransportReconnectPolicy = TransportRetryPolicy & Readonly<{
    dedupeCapacity?: number;
}>;

export type TransportRetryPolicy = Readonly<{
    maxAttempts: number;
    baseDelayMs: number;
    maxDelayMs: number;
    jitterRatio?: number;
    deadlineMs?: number;
}>;

export declare function validateTransportRetryPolicy(policy: TransportRetryPolicy): void;

export type WebSocketConnectOptions = Readonly<{
    url: string | (() => string | Promise<string>);
    protocols?: readonly string[] | (() => readonly string[] | Promise<readonly string[]>);
    reconnect?: TransportReconnectPolicy;
    signal?: AbortSignal;
    decode?: (data: unknown) => unknown | Promise<unknown>;
    encode?: (message: unknown) => string | ArrayBufferLike | Blob | ArrayBufferView;
}>;

export interface WebSocketLike {
    readonly readyState: number;
    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
    close(code?: number, reason?: string): void;
    addEventListener(type: string, listener: EventListener): void;
    removeEventListener(type: string, listener: EventListener): void;
}

export interface WebSocketTransport {
    connect(options: WebSocketConnectOptions): TransportMessageChannel<unknown> & Readonly<{
        ready: Promise<void>;
    }>;
}

export type WebSocketTransportOptions = Readonly<{
    webSocketFactory?: (url: string, protocols?: readonly string[]) => WebSocketLike;
    dependencies?: Partial<TransportDependencies>;
    onLifecycleEvent?: (event: TransportLifecycleEvent) => void;
}>;