@cavi-ai/api-client/providers/codex

/** Build the OpenAI Batch input file (JSONL). Each line targets the Responses endpoint. */
export declare function buildBatchInputJsonl(requests: RuntimeBatchRequest[], buildBody: (body: RuntimeBatchRequest["body"]) => Record<string, unknown>): string;

/** Build the OpenAI Responses request body from the universal run-start body. */
export declare function buildCodexResponseBody(body: RuntimeRunStartBody, defaultModel: string, options?: {
    background?: boolean;
    store?: boolean;
    stream?: boolean;
}): Record<string, unknown>;

export declare const CODEX_API_BASE_URL = "https://api.openai.com";

export declare const CODEX_API_ENDPOINTS: {
    readonly responses: "/v1/responses";
    readonly files: "/v1/files";
    readonly batches: "/v1/batches";
};

export declare const CODEX_DEFAULT_MODEL = "gpt-5-codex";

export declare const CODEX_RUNTIME_SUPPORT: Readonly<{
    runs: true;
    streaming: true;
    batch: true;
}>;

export declare class CodexApiClient extends BaseHttpApiClient implements RuntimeClient {
    readonly request: HttpApiTransport;
    private readonly defaultModel;
    private readonly files;
    constructor(options: CodexApiClientOptions);
    getRuntimeCapabilities(): Promise<RuntimeCapabilities>;
    startRun(body: RuntimeRunStartBody): Promise<RuntimeRunStatus>;
    getRun(runId: string): Promise<RuntimeRunStatus>;
    cancelRun(runId: string): Promise<{
        status: string;
    }>;
    submitBatch(requests: RuntimeBatchRequest[]): Promise<RuntimeBatchStatus>;
    getBatch(batchId: string): Promise<RuntimeBatchStatus>;
    cancelBatch(batchId: string): Promise<RuntimeBatchStatus>;
    getBatchResults(batchId: string): Promise<RuntimeBatchResult[]>;
    streamRun(body: RuntimeRunStartBody, handlers: RunEventStreamHandlers, options?: {
        signal?: AbortSignal;
    }): Promise<void>;
}

export type CodexApiClientOptions = {
    /** OpenAI API key. Keep this backend-owned; do not expose it to browsers/mobile clients. */
    apiKey: string;
    /** Default model when a run does not specify one. */
    defaultModel?: string;
    baseUrl?: string;
    fetchImpl?: typeof fetch;
    onTrace?: HttpApiClientOptions["onTrace"];
    defaultTimeoutMs?: number;
};

export declare function codexBatchCancelPath(batchId: string): string;

export declare function codexBatchPath(batchId: string): string;

export declare function codexFileContentPath(fileId: string): string;

export type CodexFileObject = {
    id: string;
} & Record<string, unknown>;

export declare function codexFilePath(fileId: string): string;

/** Minimal OpenAI Files client (multipart upload + content download + retrieve/delete). */
export declare class CodexFilesClient extends BaseHttpApiClient {
    readonly request: HttpApiTransport;
    constructor(options: CodexFilesClientOptions);
    /** Upload a file (multipart). `content` is the file text (e.g. batch input JSONL). */
    uploadFile(content: string, purpose: string, filename?: string): Promise<CodexFileObject>;
    /** Download raw file content (e.g. a batch output/error file's JSONL). */
    downloadFileContent(fileId: string): Promise<string>;
    retrieveFile(fileId: string): Promise<CodexFileObject>;
    deleteFile(fileId: string): Promise<Record<string, unknown>>;
}

export type CodexFilesClientOptions = {
    /** OpenAI API key. Backend-owned. */
    apiKey: string;
    baseUrl?: string;
    fetchImpl?: typeof fetch;
    onTrace?: HttpApiClientOptions["onTrace"];
    defaultTimeoutMs?: number;
};

export declare function codexResponseCancelPath(responseId: string): string;

export declare function codexResponsePath(responseId: string): string;

export declare function createCodexProviderModule(config: CodexApiClientOptions): RuntimeProviderModule;

export declare function errorMessageOf(value: unknown): string | undefined;

/** Map an OpenAI Batch object to the canonical batch status. */
export declare function mapOpenAIBatch(raw: unknown): RuntimeBatchStatus;

export declare function mapOpenAIResponseStreamEvent(sse: SseMessage, runId: string): RunStreamEvent | null;

/** Map an OpenAI Response object to the canonical run status (incl. normalized tokens). */
export declare function mapOpenAIResponseToRunStatus(response: OpenAIResponse): RuntimeRunStatus;

export declare function mapResponseStatus(status: string | undefined): RuntimeRunStatus["status"];

export type OpenAIResponse = {
    id: string;
    status?: string;
    model?: string;
    output_text?: string;
    error?: unknown;
    incomplete_details?: unknown;
    usage?: Record<string, unknown>;
};

/** Parse an OpenAI batch output/error file (JSONL) into canonical results. */
export declare function parseOpenAIBatchOutput(jsonlText: string, mapResponse: (response: OpenAIResponse) => RuntimeRunStatus, options?: ParseOpenAIBatchOutputOptions): RuntimeBatchResult[];

export type ParseOpenAIBatchOutputOptions = {
    /**
     * `skip` preserves the historical low-level parser behavior. `throw` is used
     * by CodexApiClient for downloaded batch files so malformed JSONL cannot
     * silently hide missing request results.
     */
    malformedLine?: "skip" | "throw";
};

export declare function readOpenAIResponseRunId(sse: SseMessage): string | null;