@cadraos/sdk 0.3.14-p46.4 → 0.3.15

package/dist/index.d.cts

@@ -62,6 +62,13 @@ interface RequestOptions {
     skipRetry?: boolean;
     /** Idempotency key */
     idempotencyKey?: string;
+    /**
+     * Per-request timeout in milliseconds. Overrides the client-wide
+     * `config.timeout` for this call only (p93 AIF-010: a paid AI-function run
+     * waits for the server's route ceiling while every other call keeps the
+     * 30 s default).
+     */
+    timeoutMs?: number;
 }
 /**
  * HTTP Client class
@@ -71,6 +78,8 @@ declare class HttpClient {
     private tokenRefreshAttempts;
     private readonly maxTokenRefreshAttempts;
     constructor(config: HttpClientConfig);
+    /** The client-wide request timeout (ms) this client was configured with. */
+    get timeoutMs(): number;
     /**
      * Get authorization header value
      */
@@ -93,6 +102,7 @@ declare class HttpClient {
     post<T>(path: string, body?: unknown, options?: {
         idempotencyKey?: string;
         skipRetry?: boolean;
+        timeoutMs?: number;
     }): Promise<T>;
     /**
      * PATCH request
@@ -1146,6 +1156,16 @@ interface ToolResultEvent {
     result: unknown;
     /** Duration in milliseconds */
     durationMs: number;
+    /**
+     * CAD-243: true when the tool call FAILED (the producer stamps
+     * `isError: true` + `status: 'failed'` on a thrown tool call). Absent on
+     * older producers — consumers then fall back to the result shape.
+     */
+    isError?: boolean;
+    /** CAD-243: producer verdict, `'failed'` for a failed call. */
+    status?: string;
+    /** CAD-243: error text for a failed call. */
+    error?: string;
     /** See {@link ToolCallEvent.forwardedFrom} */
     forwardedFrom?: string;
     /** See {@link ToolCallEvent.sourceExecutionId} (CAD-87 S1-001). */
@@ -1529,6 +1549,140 @@ interface StreamingConfig {
     sseRetryIntervalMs?: number;
 }
 
+/**
+ * AI function types (p93 — specs §4 run contract, D27 discovery, §6.5 run reads).
+ *
+ * An AI function is a published prompt in the Cadra Prompts library that makes
+ * ONE direct AI-provider call (never an agent). Callers reference it by its
+ * `functionKey` (unique per org), by prompt uuid, or — for platform features —
+ * by slot key.
+ */
+/** Output kind of an AI function. */
+type AiFunctionOutputKind = 'text' | 'json' | 'image';
+/** Parameter (prompt variable) types — specs D10 + D26d. */
+type AiFunctionParameterType = 'string' | 'text' | 'number' | 'boolean' | 'enum' | 'image';
+/** A value passed for one parameter. `image` parameters take an artifact uuid (string). */
+type AiFunctionVariableValue = string | number | boolean;
+/** Parameters (variables) for one run, keyed by parameter name. */
+type AiFunctionVariables = Record<string, AiFunctionVariableValue>;
+/** How a run names its function (§4). */
+type AiFunctionRef = {
+    slot: string;
+} | {
+    functionKey: string;
+} | {
+    promptUuid: string;
+};
+/** One declared parameter of a function's live (golden) version — D27a. */
+interface AiFunctionParameter {
+    name: string;
+    type: AiFunctionParameterType;
+    required: boolean;
+    defaultValue?: AiFunctionVariableValue;
+    maxLength?: number;
+    options?: string[];
+    description?: string;
+}
+/**
+ * The discovery "index" entry for one callable function — D27a. Built from the
+ * golden version snapshot; never carries prompt or system text.
+ */
+interface AiFunctionDescriptor {
+    functionKey: string;
+    title: string;
+    description?: string | null;
+    outputKind: AiFunctionOutputKind;
+    /** The live (golden) version number. */
+    liveVersion: number;
+    parameters: AiFunctionParameter[];
+    /** JSON schema of the output, for `json` functions. */
+    outputSchema?: Record<string, unknown> | null;
+}
+/** Who paid for a run (D4). */
+type AiFunctionBilledTo = 'own_key' | 'credits' | 'platform_funded';
+/** Runtime params a slot may accept per run (D26d3). */
+interface AiFunctionRuntimeParams {
+    aspect_ratio?: string;
+    image_size?: string;
+}
+/** Options for the object form `run(ref, { variables, … })`. */
+interface AiFunctionRunOptions {
+    /** Parameters for this run (sent as `variables`). */
+    variables: AiFunctionVariables;
+    /** Pin a published version number (D3d). Skips the client-side check. */
+    version?: number;
+    /** Idempotency key (uuid). Generated when omitted (D15). */
+    idempotencyKey?: string;
+    /** Slot runtime params (D26d3). */
+    params?: AiFunctionRuntimeParams;
+    /** `false` skips the client-side parameter check (D27c). Default true. */
+    validate?: boolean;
+}
+/** Options for the shorthand `run('function_key', parameters, opts)`. */
+type AiFunctionRunShorthandOptions = Omit<AiFunctionRunOptions, 'variables'>;
+/** Image produced by an `image` function. Over HTTP only `url` (presigned, 1 h) is set. */
+interface AiFunctionImage {
+    mimeType: string;
+    url?: string;
+    bytes?: Uint8Array;
+}
+/** Output of a run, by kind (§4). `TOutput` types `json`. */
+type AiFunctionOutput<TOutput = unknown> = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'json';
+    json: TOutput;
+} | {
+    type: 'image';
+    images: AiFunctionImage[];
+};
+/** Token and billing usage of a run (§4). */
+interface AiFunctionUsage {
+    promptTokens: number;
+    completionTokens: number;
+    imageCount: number;
+    billedTo: AiFunctionBilledTo;
+}
+/** Result of a successful run (§4). */
+interface AiFunctionRunResult<TOutput = unknown> {
+    /** = the run's execution uuid (usage-ledger executionUuid). */
+    executionId: string;
+    functionUuid: string;
+    version: number;
+    output: AiFunctionOutput<TOutput>;
+    usage: AiFunctionUsage;
+    latencyMs: number;
+}
+/** Run status as reported by run reads (D12; `abandoned` is computed on read). */
+type AiFunctionRunStatus = 'running' | 'succeeded' | 'failed_provider' | 'failed_timeout' | 'refused_billing' | 'failed_output' | 'failed_delivery' | 'abandoned';
+/** Safe projection of one of the caller org's own runs (§6.5). */
+interface AiFunctionRun {
+    executionId: string;
+    ref: {
+        slot?: string;
+        functionKey?: string;
+        promptUuid?: string;
+    };
+    version: number | null;
+    status: AiFunctionRunStatus;
+    errorCode: string | null;
+    promptTokens: number | null;
+    completionTokens: number | null;
+    imageCount: number | null;
+    latencyMs: number | null;
+    billedTo: AiFunctionBilledTo | null;
+    createdAt: string;
+    finishedAt: string | null;
+}
+/** Why a parameter failed the client-side check (D27c). */
+type AiFunctionParameterIssueCode = 'missing' | 'type' | 'option' | 'too_long' | 'unknown';
+/** One client-side parameter problem (D27c). */
+interface AiFunctionParameterIssue {
+    name: string;
+    code: AiFunctionParameterIssueCode;
+}
+
 /**
  * Base Resource API
  *
@@ -1557,6 +1711,7 @@ declare abstract class BaseResourceAPI {
     protected httpPost<T>(path: string, body?: unknown, options?: {
         idempotencyKey?: string;
         skipRetry?: boolean;
+        timeoutMs?: number;
     }): Promise<T>;
     /**
      * HTTP PATCH request helper
@@ -3254,6 +3409,81 @@ declare class RemoteRunnersAPI extends BaseResourceAPI {
     list(options?: RemoteRunnerListOptions): Promise<PaginatedResponse<RemoteRunner>>;
 }
 
+/**
+ * AI Functions API (p93 AIF-010 — specs §9, D27).
+ *
+ * @example
+ * ```typescript
+ * // Discover what the org can call, and with which parameters
+ * const functions = await client.aiFunctions.list();
+ * const fn = await client.aiFunctions.get('summarise_ticket');
+ *
+ * // Call it — parameters are checked against the live version before sending
+ * const result = await client.aiFunctions.run('summarise_ticket', { ticket_text: '…' });
+ * if (result.output.type === 'text') console.log(result.output.text);
+ * ```
+ */
+
+/**
+ * How long the client waits for a paid run. It tracks cadra-web
+ * `AI_FUNCTION_ROUTE_MAX_MS` (300 s, the Vercel `maxDuration` of the run
+ * routes) plus 10 s, so the server always answers first — with the result or
+ * with its own `failed_timeout` — and the client never abandons a run the
+ * server is still finishing. A larger client-wide `timeout` wins.
+ * (Was 60 s, from the old p93 D6 route budget.)
+ */
+declare const AI_FUNCTION_RUN_TIMEOUT_MS = 310000;
+/** Descriptors used by the client-side check are cached per client for 60 s (D27c). */
+declare const AI_FUNCTION_DESCRIPTOR_TTL_MS = 60000;
+/**
+ * Check `variables` against a descriptor's parameters (D27c). Returns the issues,
+ * in parameter order, then unknown names. Empty array = OK.
+ */
+declare function checkAiFunctionParameters(parameters: AiFunctionParameter[], variables: AiFunctionVariables): AiFunctionParameterIssue[];
+/**
+ * AI Functions API
+ */
+declare class AiFunctionsAPI extends BaseResourceAPI {
+    private readonly descriptorCache;
+    constructor(http: HttpClient);
+    /**
+     * List the functions this org can call — the index (D27a). Each entry carries
+     * the live version's typed parameters; never prompt text.
+     */
+    list(): Promise<AiFunctionDescriptor[]>;
+    /**
+     * Get one function's descriptor by key (D27a).
+     * `NotFoundError` (`FUNCTION_NOT_FOUND`) / `ConflictError` (`FUNCTION_NOT_PUBLISHED`).
+     */
+    get(functionKey: string): Promise<AiFunctionDescriptor>;
+    /**
+     * Read one of this org's own runs (safe projection, §6.5).
+     */
+    getRun(executionId: string): Promise<AiFunctionRun>;
+    /** Forget cached descriptors (one key, or all). */
+    clearDescriptorCache(functionKey?: string): void;
+    /**
+     * Run an AI function — one paid provider call.
+     *
+     * - `run('function_key', parameters, opts?)` — shorthand for `{ functionKey }`.
+     * - `run({ functionKey | promptUuid | slot }, { variables, version?, idempotencyKey?, params?, validate? })`.
+     *
+     * For a `functionKey` ref without a pinned `version`, parameters are checked
+     * against the live version first (D27c); a problem throws
+     * `AiFunctionParameterError` and NO run request is sent. Paid runs are never
+     * auto-retried; an idempotency key is generated when omitted.
+     *
+     * @throws AiFunctionParameterError — client-side check failed (nothing sent)
+     * @throws AiFunctionDuplicateError — 409 `DUPLICATE_REQUEST`
+     * @throws AiFunctionChargedError — the run was metered but its output failed (`details.charged`)
+     */
+    run<TOutput = unknown>(functionKey: string, parameters: AiFunctionVariables, opts?: AiFunctionRunShorthandOptions): Promise<AiFunctionRunResult<TOutput>>;
+    run<TOutput = unknown>(ref: AiFunctionRef, options: AiFunctionRunOptions): Promise<AiFunctionRunResult<TOutput>>;
+    private cacheDescriptor;
+    private getCachedDescriptor;
+    private mapRunError;
+}
+
 /**
  * Cadra Client
  *
@@ -3398,6 +3628,10 @@ declare class CadraClient {
      * Remote runner operations (list)
      */
     readonly remoteRunners: RemoteRunnersAPI;
+    /**
+     * AI function operations (list, get, run, getRun) — p93
+     */
+    readonly aiFunctions: AiFunctionsAPI;
     /**
      * Create a new AI SaaS client
      *
@@ -3449,6 +3683,14 @@ declare class CadraError extends Error {
     readonly details?: Record<string, unknown>;
     /** Request ID from server (for debugging) */
     readonly requestId?: string;
+    /**
+     * The server's own `error.code` exactly as sent on the wire (e.g.
+     * `FUNCTION_NOT_PUBLISHED`, `DUPLICATE_REQUEST`, `VARIABLE_TYPE`).
+     * Populated by `parseApiError` for EVERY status. `code` keeps its historic
+     * per-class values (`conflict`, `server_error`, `validation_error`, …) for
+     * compatibility; branch on `serverCode` when you need the precise reason.
+     */
+    serverCode?: string;
     constructor(message: string, code: string, status: number, details?: Record<string, unknown>, requestId?: string);
 }
 /**
@@ -3525,4 +3767,40 @@ declare class NetworkError extends CadraError {
     constructor(message?: string, details?: Record<string, unknown>);
 }
 
-export { CadraClient as AISaaSClient, type CadraClientOptions as AISaaSClientOptions, CadraError as AISaaSError, type Agent, type AgentConfig, type AgentConfigUpdateInput, type AgentExecution, type AgentListOptions, type AgentStatus, type AgentType, type AgentUpdateInput, type Artifact, type ArtifactDownloadOptions, type ArtifactListOptions, type ArtifactType, type ArtifactUploadInput, type AttachmentUploadUrlInput, type AttachmentUploadUrlResponse, AuthenticationError, AuthorizationError, CadraClient, type CadraClientOptions, CadraError, type CollectImagesOptions, type CompleteEvent, ConflictError, type ConnectionChangeEvent, type DelegationCompletedEvent, type DelegationStartedEvent, type ErrorEvent, type ExecuteInput, type ExecuteOptions, type ExecuteResponse, type ExecuteToolDirectRequest, type ExecuteToolDirectResponse, type ExecutionLog, type ExecutionStatus, type ExecutionStreamController, type ExecutionStreamControllerOptions, type ExtractContext, type ImageData, type ImageEvent, type JSONSchema, type ListOptions, NetworkError, NotFoundError, type PaginatedResponse, type PaginationInfo, type PausedEvent, type PlanEvent, type ProgressEvent, RateLimitError, type RemoteAgent, type RemoteAgentCreateInput, type RemoteAgentExecuteResponse, type RemoteAgentExecutionTargetKind, type RemoteAgentListOptions, type RemoteAgentStatus, type RemoteAgentUpdateInput, type RemoteAgentVisibility, type RemoteRunner, type RemoteRunnerListOptions, type SendMessageInput, ServerError, type Session, type SessionArtifact, type SessionArtifactListOptions, type SessionArtifactType, type SessionArtifactVariantType, type SessionCreateInput, type SessionHistory, type SessionListOptions, type SessionMessage, type SignedUrlResponse, type Skill, type SkillDetails, type SkillExecuteInput, type SkillExecution, type SkillListOptions, type SkillTool, type SkillUpdateInput, type SkillVariable, type StartedEvent, type StreamController, type StreamEventMap, type StreamImagesResult, type TeamMemberRef, type TextDeltaEvent, TimeoutError, type TokenUsage, type Tool, type ToolCallEvent, type ToolConfigUpdateInput, type ToolExecution, type ToolListOptions, type ToolResultEvent, type ToolUpdateInput, type ToolValidationResult, ValidationError, collectImagesFromStream, deriveImagesFromToolCalls, extractImagesFromExecutionOutput, extractImagesFromResult };
+/**
+ * AI function errors (p93 AIF-010, specs §9 + D27c).
+ *
+ * All extend the existing hierarchy so `instanceof CadraError` (and, where it
+ * applies, `ConflictError` / `ValidationError`) keeps working.
+ */
+
+/**
+ * 409 `DUPLICATE_REQUEST`: a run with the same idempotency key already exists.
+ * No provider call was made. A retry after `abandoned` or a failure needs a NEW key.
+ */
+declare class AiFunctionDuplicateError extends ConflictError {
+    /** The existing run's execution id. */
+    readonly executionId?: string;
+    /** The existing run's status (`running`, a terminal status, or `abandoned`). */
+    readonly runStatus?: string;
+    constructor(message: string, details?: Record<string, unknown>, requestId?: string);
+}
+/**
+ * The provider answered 2xx and the run WAS metered, but the output then failed
+ * (`OUTPUT_INVALID`, `DELIVERY_FAILED` — `details.charged: true`). Never retry
+ * automatically: a retry is a second paid call.
+ */
+declare class AiFunctionChargedError extends CadraError {
+    constructor(source: CadraError);
+}
+/**
+ * The client-side parameter check failed (D27c). No run request was sent.
+ * Also a `ValidationError`, with one `errors[]` entry per issue.
+ */
+declare class AiFunctionParameterError extends ValidationError {
+    readonly functionKey: string;
+    readonly issues: AiFunctionParameterIssue[];
+    constructor(functionKey: string, issues: AiFunctionParameterIssue[]);
+}
+
+export { CadraClient as AISaaSClient, type CadraClientOptions as AISaaSClientOptions, CadraError as AISaaSError, AI_FUNCTION_DESCRIPTOR_TTL_MS, AI_FUNCTION_RUN_TIMEOUT_MS, type Agent, type AgentConfig, type AgentConfigUpdateInput, type AgentExecution, type AgentListOptions, type AgentStatus, type AgentType, type AgentUpdateInput, type AiFunctionBilledTo, AiFunctionChargedError, type AiFunctionDescriptor, AiFunctionDuplicateError, type AiFunctionImage, type AiFunctionOutput, type AiFunctionOutputKind, type AiFunctionParameter, AiFunctionParameterError, type AiFunctionParameterIssue, type AiFunctionParameterIssueCode, type AiFunctionParameterType, type AiFunctionRef, type AiFunctionRun, type AiFunctionRunOptions, type AiFunctionRunResult, type AiFunctionRunShorthandOptions, type AiFunctionRunStatus, type AiFunctionRuntimeParams, type AiFunctionUsage, type AiFunctionVariableValue, type AiFunctionVariables, AiFunctionsAPI, type Artifact, type ArtifactDownloadOptions, type ArtifactListOptions, type ArtifactType, type ArtifactUploadInput, type AttachmentUploadUrlInput, type AttachmentUploadUrlResponse, AuthenticationError, AuthorizationError, CadraClient, type CadraClientOptions, CadraError, type CollectImagesOptions, type CompleteEvent, ConflictError, type ConnectionChangeEvent, type DelegationCompletedEvent, type DelegationStartedEvent, type ErrorEvent, type ExecuteInput, type ExecuteOptions, type ExecuteResponse, type ExecuteToolDirectRequest, type ExecuteToolDirectResponse, type ExecutionLog, type ExecutionStatus, type ExecutionStreamController, type ExecutionStreamControllerOptions, type ExtractContext, type ImageData, type ImageEvent, type JSONSchema, type ListOptions, NetworkError, NotFoundError, type PaginatedResponse, type PaginationInfo, type PausedEvent, type PlanEvent, type ProgressEvent, RateLimitError, type RemoteAgent, type RemoteAgentCreateInput, type RemoteAgentExecuteResponse, type RemoteAgentExecutionTargetKind, type RemoteAgentListOptions, type RemoteAgentStatus, type RemoteAgentUpdateInput, type RemoteAgentVisibility, type RemoteRunner, type RemoteRunnerListOptions, type SendMessageInput, ServerError, type Session, type SessionArtifact, type SessionArtifactListOptions, type SessionArtifactType, type SessionArtifactVariantType, type SessionCreateInput, type SessionHistory, type SessionListOptions, type SessionMessage, type SignedUrlResponse, type Skill, type SkillDetails, type SkillExecuteInput, type SkillExecution, type SkillListOptions, type SkillTool, type SkillUpdateInput, type SkillVariable, type StartedEvent, type StreamController, type StreamEventMap, type StreamImagesResult, type TeamMemberRef, type TextDeltaEvent, TimeoutError, type TokenUsage, type Tool, type ToolCallEvent, type ToolConfigUpdateInput, type ToolExecution, type ToolListOptions, type ToolResultEvent, type ToolUpdateInput, type ToolValidationResult, ValidationError, checkAiFunctionParameters, collectImagesFromStream, deriveImagesFromToolCalls, extractImagesFromExecutionOutput, extractImagesFromResult };