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

package/dist/index.d.ts

@@ -0,0 +1,196 @@
+import { T as ToolProvider, W as WebhookHandlerOptions, C as ConversationEvent, a as WebhookError, R as ReadBody } from './provider-BqfTvF3g.js';
+export { b as ConversationEventType, c as ConversationState, K as KEEP_SECONDS, L as LeaseLostError, M as MAX_REQUEST_BYTES, d as ResultTooLargeError, e as TOOL_OPERATIONS, f as ToolBody, g as ToolCall, h as ToolContractComponents, o as ToolContractOperations, i as ToolHandlers, j as ToolOperationId, k as ToolProviderOptions, l as ToolRequest, m as ToolResponse, n as ToolResult, p as ToolSignatureError, q as ToolSignatureErrorCode, r as WEBHOOK_EVENT_TYPES, s as WebhookEnvelope, t as WebhookErrorCode, u as WebhookEvent, v as WebhookEventOf, w as WebhookEventType, x as WebhookResponse, y as createToolProvider, z as isConversationEvent, A as verifyToolCall } from './provider-BqfTvF3g.js';
+export { c as ContractComponents, w as ContractWebhooks } from './vinaverse-v1.d-BVc4uyUd.js';
+export { I as IdempotencyRecord, a as IdempotencyStore, M as MemoryIdempotencyStore, b as MemoryNonceStore, N as NONCE_KEEP_SECONDS, c as NonceStore, d as canonicalJson, f as fingerprint } from './nonces-scwljZwl.js';
+
+/**
+ * `(request) => Promise<Response>` for a Vinaverse webhook endpoint. It reads
+ * the raw body itself, so mount it where nothing has parsed the body:
+ *
+ *   export const POST = createFetchWebhookHandler({ secret, onEvent });
+ */
+declare function createFetchWebhookHandler(options: WebhookHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * `(request) => Promise<Response>` serving a tenant's tools: every tool route
+ * under the provider's `basePath`, with the contract enforced. The target is
+ * the request URL's path and query as received.
+ *
+ *   const handle = createFetchToolHandler(createToolProvider({ … }));
+ */
+declare function createFetchToolHandler(provider: ToolProvider, options?: {
+    maxBodyBytes?: number;
+}): (request: Request) => Promise<Response>;
+
+declare const CONTRACT: {
+    readonly api: "v1-draft.17";
+    readonly commit: "fe4fb7d2945e1ced2bce7d44e85a4b28005e46df";
+};
+
+type ProblemCode = 'not_found' | 'forbidden' | 'invalid_argument' | 'unavailable' | 'token_expired';
+/** The codes a refused flow submission carries (`FlowSubmissionRefusal`). */
+type FlowRefusalCode = 'REQUIRED_MISSING' | 'UNKNOWN_VALUE' | 'TOO_LONG' | 'VERSION_NOT_ACCEPTED' | 'TOO_MANY' | 'TOO_FEW' | 'BAD_DATE' | 'UPLOAD_NOT_FOUND' | 'OUT_OF_RANGE';
+interface ProblemBody {
+    readonly status: number;
+    readonly code: string;
+    readonly detail?: string;
+    readonly field?: string;
+    readonly example?: string;
+    readonly question_id?: string;
+}
+/** A refusal the toolkit sends as the contract's problem details. */
+declare class ToolRefusal extends Error {
+    #private;
+    readonly problem: ProblemBody;
+    constructor(problem: ProblemBody);
+    get status(): number;
+    /** The record does not exist, or the person may not see it (both are the same 404). */
+    static notFound(detail?: string): ToolRefusal;
+    static forbidden(detail?: string): ToolRefusal;
+    /**
+     * A value the tenant does not accept. `field` is a JSON Pointer into the
+     * body (`/changes/address/postal_code`); `example` is a valid value the
+     * agent offers when it asks again.
+     */
+    static invalidArgument(options?: {
+        field?: string;
+        example?: string;
+        detail?: string;
+    }): ToolRefusal;
+    /** A temporary failure; a read is retried. */
+    static unavailable(detail?: string): ToolRefusal;
+    /** The delegated token is not valid (expired, revoked, unknown): a 401, which ends the session's tool access. */
+    static tokenExpired(detail?: string): ToolRefusal;
+    /** `get_flow_definition` with a `version` the tenant no longer accepts: `410 VERSION_GONE`. */
+    static versionGone(detail?: string): ToolRefusal;
+    /**
+     * `submit_flow` refused: `422` with a flow code and the question to ask
+     * again (none only for `VERSION_NOT_ACCEPTED`). Stored like an acceptance,
+     * so the same submission gets the same refusal again.
+     */
+    static flowRefused(code: FlowRefusalCode, questionId?: string, detail?: string): ToolRefusal;
+}
+
+/** No Web Crypto in this runtime: the package cannot verify anything here. */
+declare class WebCryptoUnavailableError extends Error {
+    constructor();
+}
+
+/** The fields of a conversation state the rule reads. */
+interface SequencedState {
+    readonly conversation_id: string;
+    readonly sequence: number;
+    readonly answers_omitted?: boolean;
+    readonly answers?: unknown;
+    readonly remarks?: unknown;
+}
+/** What a tenant keeps per conversation: the state held, and what it knows about the deliveries. */
+interface ConversationRecord<S extends SequencedState = SequencedState> {
+    /** The newest state, with the answers and remarks merged in when a delivery left them out. */
+    readonly state: S;
+    /** Every `sequence` a delivery carried for this conversation, ascending. */
+    readonly seen: readonly number[];
+    /** The last applied state left out its answers: read the full state. */
+    readonly fullReadNeeded: boolean;
+}
+type SequenceAction = 'apply' | 'stale';
+type DeliveryAction = SequenceAction | 'duplicate' | 'skip_test';
+/** Apply a state only above the one held: an equal or lower `sequence` is stale. */
+declare function sequenceVerdict(held: Pick<SequencedState, 'conversation_id' | 'sequence'> | null | undefined, incoming: Pick<SequencedState, 'conversation_id' | 'sequence'>): SequenceAction;
+/**
+ * Applies one conversation state to the record held for its conversation (or
+ * none) and returns the record to keep and what happened. A stale state
+ * changes nothing but `seen`. An applied state with `answers_omitted: true` is
+ * kept without that flag, with the `answers` and `remarks` held (or none), and
+ * `fullReadNeeded` set.
+ */
+declare function applyConversationState<S extends SequencedState>(record: ConversationRecord<S> | null | undefined, incoming: S): {
+    record: ConversationRecord<S>;
+    action: SequenceAction;
+};
+/**
+ * The sequences still to come for a conversation: above the lowest one a
+ * delivery carried and below the one held, that no delivery has carried yet.
+ * Wait for them, or read the full state.
+ */
+declare function missingSequences(record: ConversationRecord): number[];
+type ConversationData = ConversationEvent['data'];
+/**
+ * The rule over a stream of verified deliveries, in memory: envelope ids seen,
+ * and a record per conversation. For one process and for tests; a tenant
+ * behind several instances keeps the ids and the records in its database and
+ * calls `applyConversationState` itself.
+ */
+declare class ConversationReceiver {
+    #private;
+    /**
+     * One verified delivery (an event, or a Studio test delivery's envelope):
+     * what to do with it. The record for its conversation is then `record(id)`.
+     */
+    receive(delivery: {
+        readonly id: string;
+        readonly data: unknown;
+    }): DeliveryAction;
+    record(conversationId: string): ConversationRecord<ConversationData> | undefined;
+    conversations(): string[];
+}
+
+declare const SIGNATURE_HEADER = "Vinaverse-Signature";
+declare const TOLERANCE_SECONDS = 300;
+interface ParsedSignature {
+    /** The signed timestamp, in Unix seconds. */
+    readonly timestamp: bigint;
+    /** Each `v1` signature, decoded. */
+    readonly signatures: readonly Uint8Array[];
+}
+/**
+ * Reads the header the way the API's own verifier does: comma-separated
+ * `key=value` parts (a space around a part changes nothing), exactly one `t`
+ * of digits, and the `v1` values. A `v1`
+ * that is not 64 lowercase hex digits can never match, so it is left out; a
+ * header left with no `v1` is malformed.
+ */
+declare function parseSignatureHeader(header: string): ParsedSignature | WebhookError;
+
+interface VerifyWebhookOptions {
+    /**
+     * The request body exactly as received, before any JSON parsing: a string,
+     * or bytes (`Uint8Array`, which a Node `Buffer` is, or `ArrayBuffer`). A
+     * body parsed and serialized again never verifies.
+     */
+    rawBody: string | Uint8Array | ArrayBuffer;
+    /** The `Vinaverse-Signature` header (a framework's string array is accepted). */
+    header: string | readonly string[] | null | undefined;
+    /**
+     * The endpoint's signing secret (`vv_whsec_…`), whole. Pass two while you
+     * roll a new one out: a delivery verifies if either matches.
+     */
+    secret: string | readonly string[];
+    /** The time to check the signature's timestamp against; default now. */
+    now?: Date;
+    /** How far from `now` a signature may be: whole seconds, 0 to 300 (the contract's window, the default). */
+    toleranceSeconds?: number;
+}
+type VerifyWebhookResult = ({
+    ok: true;
+} & ReadBody) | {
+    ok: false;
+    error: WebhookError;
+};
+/**
+ * Verifies a Vinaverse webhook delivery and reads it, in one call:
+ *
+ * - `{ ok: true, kind: 'event', event }`: a verified event; narrow it on `event.type`.
+ * - `{ ok: true, kind: 'test', envelope }`: a test delivery from Studio; answer 2xx, do nothing.
+ * - `{ ok: true, kind: 'unrecognized', envelope }`: verified, but a type newer than this
+ *   package; answer 2xx, and upgrade to handle it.
+ * - `{ ok: false, error }`: refused (`error.code` says why); answer 400.
+ *
+ * Deliveries are at least once: deduplicate on `event.id`, and order a
+ * conversation's states with `sequenceVerdict` or `applyConversationState`.
+ * It never throws for a bad delivery; it throws a `TypeError` for a missing
+ * secret or a tolerance that is not a whole number of seconds from 0 to 300,
+ * and `WebCryptoUnavailableError` in a runtime without Web Crypto.
+ */
+declare function verifyWebhook(options: VerifyWebhookOptions): Promise<VerifyWebhookResult>;
+
+export { CONTRACT, ConversationEvent, ConversationReceiver, type ConversationRecord, type DeliveryAction, type FlowRefusalCode, type ProblemBody, type ProblemCode, SIGNATURE_HEADER, type SequenceAction, type SequencedState, TOLERANCE_SECONDS, ToolProvider, ToolRefusal, type VerifyWebhookOptions, type VerifyWebhookResult, WebCryptoUnavailableError, WebhookError, WebhookHandlerOptions, applyConversationState, createFetchToolHandler, createFetchWebhookHandler, missingSequences, parseSignatureHeader, sequenceVerdict, verifyWebhook };