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

export type ApiKeyCredentialOptions = {
    /** Header name for the key. Defaults to "Authorization". */
    header?: string;
    /** Extra static headers (e.g. { "anthropic-version": "2023-06-01" }). */
    extra?: Record<string, string>;
};

/** API-key scheme (e.g. Anthropic: header "x-api-key" + "anthropic-version"). */
export declare function apiKeyCredentials(key: string, options?: ApiKeyCredentialOptions): CredentialResolver;

export declare class BaseHttpApiClient {
    readonly surface: HttpApiTrace["surface"];
    readonly baseUrl: string;
    readonly basePath: string;
    readonly authToken: string;
    readonly clientId: string;
    readonly sendsPortalClientId: boolean;
    readonly defaultHeaders: Record<string, string>;
    readonly resolveAuthHeaders?: () => Record<string, string>;
    readonly defaultTimeoutMs: number;
    readonly cache: RequestCache;
    readonly credentials?: RequestCredentials;
    private readonly fetchImpl;
    private readonly onTrace?;
    constructor(surface: HttpApiTrace["surface"], options: HttpApiClientOptions);
    protected resolvePath(path: string): string;
    protected resolveUrl(path: string): string;
    protected buildHeaders(init?: HttpApiRequestInit): Record<string, string>;
    protected buildBody(init?: HttpApiRequestInit): BodyInit | undefined;
    protected buildFetchInit(method: HttpApiHttpMethod, headers: Record<string, string>, body: BodyInit | undefined, signal: AbortSignal, init?: HttpApiRequestInit): RequestInit;
    protected emitTrace(trace: HttpApiTrace): void;
    protected requestRaw(path: string, init?: HttpApiRequestInit): Promise<Response>;
    protected requestJson<TResponse>(path: string, init?: HttpApiRequestInit): Promise<TResponse>;
    protected requestBlob(path: string, init?: HttpApiRequestInit): Promise<Blob>;
    createTransport(): HttpApiTransport;
}

/** Standard bearer scheme. Emits nothing when the token is empty. */
export declare function bearerCredentials(token: string | null | undefined): CredentialResolver;

export declare function buildGatewayHttpError(params: {
    label: string;
    status: number;
    statusText: string;
    message?: string | null;
    code?: string | null;
}): GatewayHttpError;

export declare function cleanGatewayErrorText(value: unknown): string | null;

export declare function createJsonHttpRequest(opts: {
    surface: HttpApiTrace["surface"];
    httpBase: string;
    authToken: string | null;
    clientId?: string | null;
    defaultHeaders?: Record<string, string>;
    credentials?: RequestCredentials;
    cache?: RequestCache;
}): JsonHttpRequest;

export declare function createRawHttpApiClient(params: {
    surface: HttpApiTrace["surface"];
    baseUrl: string;
    authToken: string | null;
    clientId?: string | null;
    defaultHeaders?: Record<string, string>;
    credentials?: RequestCredentials;
    cache?: RequestCache;
    fetchImpl?: typeof fetch;
}): RawHttpApiClient;

/** Auth headers a credential resolver contributes to a request. */
export type CredentialHeaders = Record<string, string>;

/**
 * Provider-supplied auth scheme. Returns the headers to merge onto a request.
 * Closes over whatever secret the provider needs (token, api key, cookie).
 */
export type CredentialResolver = () => CredentialHeaders;

export declare const DEFAULT_PREVIEW_MAX_CHARS = 12000;

/** Human-readable HTTP contract line for envelopes and diagnostics. */
export declare function describeHttpContract(method: string, path: string, bodyHint?: string): string;

export declare function extractGatewayErrorDetails(payload: unknown): {
    message: string | null;
    code: string | null;
};

export declare class GatewayHttpError extends Error {
    readonly type = ApiClientErrorType.GatewayHttp;
    readonly status: number;
    readonly code: string | null;
    constructor(message: string, status: number, code?: string | null);
}

export type HttpApiClientAuth = {
    bearerToken?: string | null;
    clientId?: string | null;
    /**
     * Provider-supplied auth scheme. When present, its headers replace the
     * default bearer Authorization header. See core/http/credentials.ts.
     */
    resolveHeaders?: CredentialResolver;
};

export type HttpApiClientOptions = {
    baseUrl: string;
    basePath?: string;
    allowRelativeBaseUrl?: boolean;
    defaultHeaders?: Record<string, string>;
    /** Send the X-Portal-Client-Id header. Default true; set false for non-gateway backends. */
    includePortalClientIdHeader?: boolean;
    auth?: HttpApiClientAuth;
    defaultTimeoutMs?: number;
    fetchImpl?: typeof fetch;
    cache?: RequestCache;
    credentials?: RequestCredentials;
    onTrace?: (trace: HttpApiTrace) => void;
};

export type HttpApiClientSurface = string;

export declare class HttpApiError extends Error {
    readonly type = ApiClientErrorType.Http;
    readonly code = ApiClientErrorCode.HttpRequestFailed;
    readonly path: string;
    readonly url: string;
    readonly method: HttpApiHttpMethod;
    readonly status: number;
    readonly body: string;
    constructor(params: {
        message: string;
        path: string;
        url: string;
        method: HttpApiHttpMethod;
        status: number;
        body: string;
    });
}

export type HttpApiHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";

export type HttpApiRequestInit = {
    method?: HttpApiHttpMethod;
    body?: unknown;
    rawBody?: BodyInit;
    headers?: Record<string, string>;
    signal?: AbortSignal;
    timeoutMs?: number;
    idempotencyKey?: string;
    cache?: RequestCache;
    credentials?: RequestCredentials;
};

export type HttpApiTrace = {
    at: number;
    surface: HttpApiClientSurface;
    method: HttpApiHttpMethod;
    path: string;
    url: string;
    ok: boolean;
    status?: number;
    durationMs: number;
    error?: string;
};

export type HttpApiTransport = <TResponse>(path: string, init?: HttpApiRequestInit) => Promise<TResponse>;

export declare const IDEMPOTENCY_KEY_HEADER: "Idempotency-Key";

export declare function isGatewayHttpError(error: unknown): error is GatewayHttpError;

export declare function isHttpApiError(error: unknown): error is HttpApiError;

export declare function isSensitiveKey(key: string): boolean;

export declare function isValidPortalClientId(value: string | null | undefined): boolean;

export declare class JsonHttpApiClient extends BaseHttpApiClient {
    request<TData>(path: string, init?: HttpApiRequestInit): Promise<TData>;
    private requestJsonBody;
}

export type JsonHttpRequest = <TData>(path: string, init?: HttpApiRequestInit) => Promise<TData>;

export declare function normalizePortalClientId(value: string | null | undefined): string | null;

export declare function parseGatewayErrorText(text: string, contentType: string): {
    message: string | null;
    code: string | null;
};

export declare const PORTAL_CLIENT_ID_HEADER: "X-Portal-Client-Id";

export declare class RawHttpApiClient extends BaseHttpApiClient {
    raw(path: string, init?: HttpApiRequestInit): Promise<Response>;
}

/**
 * Single source of truth for scrubbing secrets out of values, text, and config
 * keys before they are logged, previewed, or rendered.
 *
 * Gateway-agnostic: the same sensitivity rule governs HTTP request/response
 * previews and config-path filtering so the two can never drift apart.
 */
export declare const REDACTION_PLACEHOLDER = "[REDACTED]";

export declare function redactPreviewText(text: string, maxChars?: number): string;

export declare function redactSensitiveText(text: string): string;

export declare function redactSensitiveValue(value: unknown): unknown;

export declare function requirePortalClientId(value: string | null | undefined): string;

/**
 * Matches a key segment that names a credential. Segments may be separated by
 * `.`, `_`, or `-` (e.g. `model.api_key`, `auth-token`, `refreshToken`).
 */
export declare const SENSITIVE_KEY_PATTERN: RegExp;

export declare function stringifyRedacted(value: unknown, maxChars?: number): string | undefined;

export declare function toHttpRequestInit(init: RequestInit | undefined, headers?: Record<string, string>): HttpApiRequestInit;

export declare function withQuery(path: string, params: Record<string, string | number | undefined>): string;