@vinaverse/server 0.0.0-stage → 0.1.0-alpha.2

package/dist/api.d.ts

@@ -0,0 +1,453 @@
+import { o as operations, p as paths, c as components } from './vinaverse-v1.d-BVc4uyUd.js';
+import { Client } from 'openapi-fetch';
+
+interface RetryOptions {
+    /** Retries after the first try: a whole number, 0 or more; default 2. */
+    readonly maxRetries?: number;
+    /** The longest wait, in seconds, before a retry: 0 to 2 147 483 (a timer's limit); default 30. */
+    readonly maxRetryDelay?: number;
+    /** One try's timeout, reading the body included, in milliseconds: more than 0, at most 2 147 483 647; default 30 000. */
+    readonly timeout?: number;
+    /** Waits, in milliseconds; tests replace it. The wait ends early when the call is aborted. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly random?: () => number;
+}
+/**
+ * The API did not answer within `timeout` on the last try. `idempotencyKey` is the key the call carried: pass it as
+ * `{ idempotencyKey }` to try the same call again later without doing it twice.
+ */
+declare class VinaverseTimeoutError extends Error {
+    readonly name = "VinaverseTimeoutError";
+    readonly idempotencyKey: string | undefined;
+    constructor(ms: number, idempotencyKey?: string);
+}
+/** The call could not reach the API (`cause` holds why). `idempotencyKey` as for a timeout. */
+declare class VinaverseNetworkError extends Error {
+    readonly name = "VinaverseNetworkError";
+    readonly idempotencyKey: string | undefined;
+    constructor(cause: unknown, idempotencyKey?: string);
+}
+
+type Op = operations;
+/** An operation's JSON request body. */
+type ApiBody<K extends keyof Op> = Op[K] extends {
+    requestBody?: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? B : never;
+/** An operation's success result. */
+type ApiResult<K extends keyof Op> = Success<Op[K]['responses']>;
+type Success<R> = R extends {
+    200: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? B : R extends {
+    201: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? B : R extends {
+    202: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? B : undefined;
+type QueryOf<K extends keyof Op> = Op[K]['parameters'] extends {
+    query?: infer Q;
+} ? NonNullable<Q> : never;
+/** Per call: a signal that stops it at once, waits between tries included. */
+interface CallOptions {
+    readonly signal?: AbortSignal;
+}
+/**
+ * For the calls the contract makes idempotent: a key of your own, 1 to 255 characters (one is made otherwise).
+ * After a `VinaverseTimeoutError` or a `VinaverseNetworkError`, try again later with the error's `idempotencyKey`,
+ * so the call is done once however many times it is sent.
+ */
+interface KeyedCallOptions extends CallOptions {
+    readonly idempotencyKey?: string;
+}
+interface ApiClientOptions extends RetryOptions {
+    /** A service key, `vv_sk_<mock|dev|live>_…`: from your secrets store, never from code. */
+    readonly apiKey: string;
+    /**
+     * Default: `https://api.vinaverse.com` for a live key, `https://api-dev.vinaverse.com` for mock and dev keys. Any
+     * other URL must be `https:` (a proxy you run, say), or `http:` on this machine only (`localhost`, `127.0.0.1`,
+     * `[::1]`): a service key never travels in clear.
+     */
+    readonly baseUrl?: string;
+    readonly fetch?: (request: Request) => Promise<Response>;
+    /** Extra headers on every call, for example `Vinaverse-Mock-Scenario` in tests against the mock environment. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** The client was made where a service key must never be: a browser or an app. */
+declare class ServiceKeyExposureError extends Error {
+    readonly name = "ServiceKeyExposureError";
+}
+declare function createApiClient(options: ApiClientOptions): {
+    /** Every operation of the contract, typed, for what the helpers below do not cover (openapi-fetch). */
+    api: Client<paths, `${string}/${string}`>;
+    sessions: {
+        /** Mint a session for the person in your app; give the app its `id`, URLs and `client_secret` only. */
+        create: (body: ApiBody<"createSession">, o?: KeyedCallOptions) => Promise<{
+            id: string;
+            status: "open";
+            agent: {
+                id: string;
+                version: string;
+                display_name: string;
+            };
+            client_secret: components["schemas"]["ClientSecret"];
+            realtime_url: string;
+            turns_url: string;
+            expires_at: string;
+            disclosure: string;
+            conversation_id?: components["schemas"]["ConversationId"];
+        }>;
+        get: (sessionId: string, o?: CallOptions) => Promise<{
+            id: string;
+            status: "open" | "closed" | "revoked" | "expired";
+            subject_id: components["schemas"]["SubjectId"];
+            agent_version?: string;
+            turns: number;
+            handoff_ticket_ids?: string[];
+            end_reason?: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "user_left";
+            created_at: string;
+            closed_at?: string;
+            usage?: components["schemas"]["Usage"];
+        }>;
+        revoke: (sessionId: string, o?: CallOptions) => Promise<{
+            id: string;
+            status: "open" | "closed" | "revoked" | "expired";
+            subject_id: components["schemas"]["SubjectId"];
+            agent_version?: string;
+            turns: number;
+            handoff_ticket_ids?: string[];
+            end_reason?: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "user_left";
+            created_at: string;
+            closed_at?: string;
+            usage?: components["schemas"]["Usage"];
+        }>;
+        /** A fresh client secret for an open session: what an app's `refreshSecret(sessionId)` asks your backend for. */
+        refreshClientSecret: (sessionId: string, o?: CallOptions) => Promise<{
+            value: string;
+            expires_at: string;
+        }>;
+    };
+    conversations: {
+        get: (conversationId: string, o?: CallOptions) => Promise<{
+            conversation_id: components["schemas"]["ConversationId"];
+            subject_id: components["schemas"]["SubjectId"];
+            agent: string;
+            flow: string | null;
+            version: number | null;
+            status: "in_progress" | "completed" | "failed" | "expired";
+            sequence: number;
+            progress: {
+                answered: number;
+                total_estimate: number | null;
+            };
+            pending_question_id: components["schemas"]["QuestionId"] | null;
+            answers?: components["schemas"]["ConversationAnswer"][];
+            remarks?: {
+                [key: string]: string;
+            };
+            answers_omitted?: boolean;
+            last_activity_at: string;
+            session_id: string;
+        }>;
+    };
+    suggestions: {
+        create: (body: ApiBody<"createSuggestions">, o?: CallOptions) => Promise<{
+            decision_id: string;
+            suggestions: components["schemas"]["Suggestion"][];
+            personalized: boolean;
+            usage: components["schemas"]["SuggestionsUsage"];
+        }>;
+    };
+    moderation: {
+        createJob: (body: ApiBody<"createModerationJob">, o?: KeyedCallOptions) => Promise<{
+            id: string;
+            status: "queued" | "processing" | "completed" | "partially_failed";
+            items: components["schemas"]["ModerationItem"][];
+            estimated_completion_seconds?: {
+                [key: string]: number;
+            };
+        }>;
+        getJob: (jobId: string, o?: CallOptions) => Promise<{
+            id: string;
+            status: "queued" | "processing" | "completed" | "partially_failed";
+            items: components["schemas"]["ModerationItem"][];
+            estimated_completion_seconds?: {
+                [key: string]: number;
+            };
+        }>;
+        getItem: (itemId: string, o?: CallOptions) => Promise<{
+            id: string;
+            ref: string;
+            surface: components["schemas"]["Surface"];
+            kind: "image" | "video" | "text";
+            status: "queued" | "processing" | "completed" | "failed";
+            decision?: components["schemas"]["Decision"];
+            quality?: components["schemas"]["Quality"];
+            video?: components["schemas"]["VideoFindings"];
+            error?: components["schemas"]["Problem"];
+            completed_at?: string;
+            processing_ms?: number;
+            usage?: components["schemas"]["Usage"];
+        }>;
+    };
+    media: {
+        createJob: (body: ApiBody<"createMediaJob">, o?: KeyedCallOptions) => Promise<{
+            id: string;
+            ref: string;
+            surface: components["schemas"]["Surface"];
+            kind: "image" | "video";
+            subject: {
+                id: components["schemas"]["SubjectId"];
+                type: components["schemas"]["SubjectType"];
+            };
+            status: "queued" | "processing" | "completed" | "failed" | "cancelled";
+            stage: "waiting" | "fetching" | "analyzing" | "transcoding" | "uploading" | "done";
+            progress_percent: number;
+            priority: "high" | "normal" | "low";
+            queue_position: number | null;
+            estimated_completion_at: string | null;
+            steps: {
+                moderate?: components["schemas"]["MediaJobStep"];
+                transcode?: components["schemas"]["MediaJobStep"];
+                poster?: components["schemas"]["MediaJobStep"];
+                captions?: components["schemas"]["MediaJobStep"];
+            };
+            outputs: components["schemas"]["MediaOutput"][] | null;
+            error?: components["schemas"]["Problem"];
+            attempts: number;
+            context: {
+                [key: string]: string;
+            };
+            created_at: string;
+            completed_at?: string;
+        } & {
+            delayed?: boolean;
+            deduplicated?: boolean;
+        }>;
+        listJobs: (query?: QueryOf<"listMediaJobs">, o?: CallOptions) => Promise<{
+            data: components["schemas"]["MediaJob"][];
+            next_cursor: string | null;
+        }>;
+        getJob: (jobId: string, o?: CallOptions) => Promise<{
+            id: string;
+            ref: string;
+            surface: components["schemas"]["Surface"];
+            kind: "image" | "video";
+            subject: {
+                id: components["schemas"]["SubjectId"];
+                type: components["schemas"]["SubjectType"];
+            };
+            status: "queued" | "processing" | "completed" | "failed" | "cancelled";
+            stage: "waiting" | "fetching" | "analyzing" | "transcoding" | "uploading" | "done";
+            progress_percent: number;
+            priority: "high" | "normal" | "low";
+            queue_position: number | null;
+            estimated_completion_at: string | null;
+            steps: {
+                moderate?: components["schemas"]["MediaJobStep"];
+                transcode?: components["schemas"]["MediaJobStep"];
+                poster?: components["schemas"]["MediaJobStep"];
+                captions?: components["schemas"]["MediaJobStep"];
+            };
+            outputs: components["schemas"]["MediaOutput"][] | null;
+            error?: components["schemas"]["Problem"];
+            attempts: number;
+            context: {
+                [key: string]: string;
+            };
+            created_at: string;
+            completed_at?: string;
+        }>;
+        cancelJob: (jobId: string, o?: CallOptions) => Promise<{
+            id: string;
+            ref: string;
+            surface: components["schemas"]["Surface"];
+            kind: "image" | "video";
+            subject: {
+                id: components["schemas"]["SubjectId"];
+                type: components["schemas"]["SubjectType"];
+            };
+            status: "queued" | "processing" | "completed" | "failed" | "cancelled";
+            stage: "waiting" | "fetching" | "analyzing" | "transcoding" | "uploading" | "done";
+            progress_percent: number;
+            priority: "high" | "normal" | "low";
+            queue_position: number | null;
+            estimated_completion_at: string | null;
+            steps: {
+                moderate?: components["schemas"]["MediaJobStep"];
+                transcode?: components["schemas"]["MediaJobStep"];
+                poster?: components["schemas"]["MediaJobStep"];
+                captions?: components["schemas"]["MediaJobStep"];
+            };
+            outputs: components["schemas"]["MediaOutput"][] | null;
+            error?: components["schemas"]["Problem"];
+            attempts: number;
+            context: {
+                [key: string]: string;
+            };
+            created_at: string;
+            completed_at?: string;
+        }>;
+        listProfiles: (o?: CallOptions) => Promise<{
+            data: components["schemas"]["MediaProfile"][];
+        }>;
+    };
+    screening: {
+        text: (body: ApiBody<"screenText">, o?: CallOptions) => Promise<{
+            decision: components["schemas"]["Decision"];
+            action: "allow" | "nudge" | "hold" | "block";
+            nudge?: {
+                audience: "author" | "recipient" | "both";
+                text: string;
+            };
+        }>;
+    };
+    documentChecks: {
+        create: (body: ApiBody<"createDocumentCheck">, o?: KeyedCallOptions) => Promise<{
+            id: string;
+            status: "queued";
+            estimated_completion_seconds?: number;
+        }>;
+        get: (checkId: string, o?: CallOptions) => Promise<{
+            id: string;
+            ref: string;
+            status: "queued" | "processing" | "completed" | "failed";
+            document_type_detected?: string | null;
+            fields?: {
+                full_name?: string | null;
+                document_number?: string | null;
+                issuer?: string | null;
+                region?: string | null;
+                license_class?: string | null;
+                issued_on?: string | null;
+                expires_on?: string | null;
+                date_of_birth_present?: boolean | null;
+                business_name?: string | null;
+                insured_name?: string | null;
+                policy_number?: string | null;
+                carrier?: string | null;
+                coverage_end?: string | null;
+            } | null;
+            field_sources?: {
+                [key: string]: "barcode" | "text_recognition" | "visual";
+            } | null;
+            flags?: components["schemas"]["DocumentFlag"][];
+            decision?: components["schemas"]["Decision"];
+            model?: {
+                id?: string;
+                provider?: string;
+            };
+            error?: components["schemas"]["Problem"];
+            completed_at?: string;
+            fields_expire_at?: string;
+            processing_ms?: number;
+        }>;
+    };
+    subjects: {
+        erase: (subjectId: string, o?: KeyedCallOptions) => Promise<{
+            subject_id: components["schemas"]["SubjectId"];
+            status: "accepted" | "completed";
+            sessions_revoked: number;
+            deadline: string;
+        }>;
+    };
+    feedback: {
+        send: (body: ApiBody<"sendFeedback">, o?: CallOptions) => Promise<{
+            accepted: number;
+            rejected: {
+                index: number;
+                code: string;
+                detail?: string;
+            }[];
+        }>;
+    };
+    events: {
+        send: (body: ApiBody<"sendEvents">, o?: CallOptions) => Promise<{
+            accepted: number;
+            duplicates: number;
+            batch_id: string;
+            batch_cid: string;
+        }>;
+    };
+    knowledge: {
+        sendDocument: (body: ApiBody<"sendKnowledgeDocument">, o?: CallOptions) => Promise<{
+            doc_id: string;
+            version: string;
+            audience: string;
+            artifact_cid: string;
+            chunks: number;
+        }>;
+    };
+    catalog: {
+        put: (type: Op["putCatalogEntity"]["parameters"]["path"]["type"], id: string, body: ApiBody<"putCatalogEntity">, o?: CallOptions) => Promise<{
+            type: string;
+            id: string;
+            changed: boolean;
+            snapshot_cid: string | null;
+        }>;
+    };
+    usage: {
+        get: (query?: QueryOf<"getUsage">, o?: CallOptions) => Promise<{
+            period: string;
+            features: {
+                feature: components["schemas"]["Feature"];
+                quantity: number;
+                cost: components["schemas"]["MicroMoney"];
+                cap: components["schemas"]["MicroMoney"] | null;
+                state: "enabled" | "disabled";
+            }[];
+        }>;
+    };
+};
+type ApiClient = ReturnType<typeof createApiClient>;
+
+type ApiProblem = components['schemas']['Problem'];
+type ApiProblemCode = ApiProblem['code'];
+/** The API refused a call: its problem details, typed, with the request id to quote to support. */
+declare class VinaverseApiError extends Error {
+    readonly name = "VinaverseApiError";
+    readonly status: number;
+    /** The problem's code (`invalid_request`, `rate_limited`, …), or `http_<status>` when the body was not a problem. */
+    readonly code: ApiProblemCode | `http_${number}`;
+    /** Whether the same call may succeed later: the problem's `retryable`, else true for 429 and 5xx. */
+    readonly retryable: boolean;
+    /** `Vinaverse-Request-Id`, or the problem's `request_id`. */
+    readonly requestId: string | undefined;
+    /** `Retry-After`, in seconds, when the API sent one. */
+    readonly retryAfter: number | undefined;
+    /** For `invalid_request`: the fields refused, as JSON Pointers into the request. */
+    readonly errors: readonly {
+        pointer: string;
+        message: string;
+    }[];
+    /** The problem as sent, or undefined when the body was not one. */
+    readonly problem: ApiProblem | undefined;
+    /** The `Idempotency-Key` the call carried: send the same call again with it to have it done once. */
+    readonly idempotencyKey: string | undefined;
+    constructor(init: {
+        status: number;
+        problem?: ApiProblem | undefined;
+        requestId?: string | undefined;
+        retryAfter?: number | undefined;
+        idempotencyKey?: string | undefined;
+    });
+}
+/** The error for a refused response and its parsed body: what every call of the API client throws. */
+declare function apiError(response: Response, body: unknown, idempotencyKey?: string): VinaverseApiError;
+/** `Retry-After` in seconds: a number of seconds or an HTTP date; undefined when absent or unreadable. */
+declare function retryAfterSeconds(response: Response, now?: () => number): number | undefined;
+
+export { type ApiBody, type ApiClient, type ApiClientOptions, type ApiProblem, type ApiProblemCode, type ApiResult, type CallOptions, type KeyedCallOptions, type RetryOptions, ServiceKeyExposureError, VinaverseApiError, VinaverseNetworkError, VinaverseTimeoutError, apiError, createApiClient, retryAfterSeconds };