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

package/dist/conversation/index.d.cts

@@ -0,0 +1,371 @@
+import { Q as Question, A as AnswerInput, H as HeldCard, T as ToolLine, S as SessionInfo, C as ClientSecret, a as SessionOptions, P as ProposalOutcome } from '../session--W6JXfwo.cjs';
+export { b as CONTRACT, c as Card, d as CardKind, e as ClientErrorCode, f as HeldQuestion, g as Proposal, V as VinaverseClientError, i as isKnownCard } from '../session--W6JXfwo.cjs';
+
+type AnswerProblem = 
+/** Nothing chosen or typed, and the question is required (or skipped while required). */
+'required'
+/** Fewer choices than `min`. */
+ | 'too_few'
+/** More choices than `max`, or more than one where one is asked. */
+ | 'too_many'
+/** A value that is not on the card, `none_of_the_above` with another choice, or a form the kind does not take. */
+ | 'not_allowed'
+/** The text, or the "Other" text, is longer than the card allows (in code points). */
+ | 'too_long'
+/** A number outside `min`…`max`, or off its `step`. */
+ | 'out_of_range'
+/** Not a calendar date, or outside the card's bounds. */
+ | 'bad_date';
+/** Unicode code points, as the contract counts every text limit (an emoji outside the BMP is one). */
+declare function codePoints(text: string): number;
+/**
+ * The first rule an answer breaks, or null when it can be sent. For `rate_each`, check each row's answer against
+ * the question: one column from `options`, or `skipped` when not required. A kind this client does not know is the
+ * server's to judge (null).
+ */
+declare function answerProblem(question: Question, input: AnswerInput): AnswerProblem | null;
+
+/** Whether a prefix may be registered: the contract's prefix pattern, no refused scheme, no control character. */
+declare function isValidLinkPrefix(prefix: string): boolean;
+/**
+ * Whether a card's link may be opened: it starts with one of the registered prefixes (invalid ones are ignored) and
+ * what follows is a path and an optional query of the allowed characters. Route by the page it names; never open a
+ * query value.
+ */
+declare function isAllowedLink(link: string, prefixes: readonly string[]): boolean;
+
+type ConversationStatus = 
+/** Asking the tenant's backend for a session. */
+'starting'
+/** The backend gave no session (`getSession` failed): `start()` tries again. */
+ | 'unavailable' | 'connecting' | 'ready' | 'reconnecting'
+/** Disconnected after a normal close: the next action connects again. */
+ | 'idle'
+/** The reconnect attempts are spent, or the app reported no network: the next action, or `setOnline(true)`, connects. */
+ | 'offline'
+/** Turns run over SSE: answers to question cards need the WebSocket (`answersNeedWebSocket`). */
+ | 'sse'
+/** The session ended; `next` says how the conversation goes on. */
+ | 'ended'
+/** The client secret was refused and no fresh one could be had. */
+ | 'unauthorized'
+/** `dispose()` or `clear()` closed it. */
+ | 'closed';
+/** What the UI shows above the conversation, if anything. Copy is the UI's. */
+type ConversationBanner = 'connecting' | 'reconnecting' | 'offline' | 'continued_elsewhere' | 'unavailable' | null;
+type MessageState = 
+/** On the server (a turn started with it, or the agent's or staff's reply). */
+'sent'
+/** Recorded for the business during a takeover (`input.received`). */
+ | 'delivered'
+/** Sent, not acknowledged yet. */
+ | 'sending'
+/** Held for the next session: "sends when you continue", never a failure. */
+ | 'held'
+/** Refused for good, or its retries spent: shown with `rejection`; `retry(key)` sends it again. */
+ | 'not_sent'
+/** The agent's reply still streaming: its text comes from `getStreaming()`. */
+ | 'streaming';
+interface MessageItem {
+    readonly type: 'message';
+    readonly key: string;
+    /** `agent` for the protocol's `assistant`; `staff` is a person from the business. */
+    readonly role: 'agent' | 'person' | 'staff' | (string & {});
+    readonly text: string;
+    readonly state: MessageState;
+    /** A reply cut off after part of it streamed: `blocked`, `interrupted` or `failed`. */
+    readonly partial?: 'blocked' | 'interrupted' | 'failed';
+    /** The agent's reply is a guardrail refusal of the person's message. */
+    readonly refusal?: true;
+    /** Why a `not_sent` message was refused (`input.rejected`, or the client's own reason). */
+    readonly rejection?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+interface CardItem {
+    readonly type: 'card';
+    /** The card's `id`. */
+    readonly key: string;
+    readonly card: HeldCard;
+    /** A proposal being decided by the tenant's handler (`decideProposal`): draw its buttons busy. */
+    readonly busy: boolean;
+    /** Restored from `persistence` after a restart: drawn as it was, taking no answer or action. */
+    readonly restored?: true;
+    /** The tenant's decision on this proposal failed (`decideProposal` threw): nothing was reported; it may be tried again. */
+    readonly decisionError?: true;
+}
+type SystemEvent = 'takeover_started' | 'takeover_ended' | 'handoff_created' | 'flow_completed' | 'turn_failed';
+interface SystemItem {
+    readonly type: 'system';
+    readonly key: string;
+    readonly event: SystemEvent;
+    /**
+     * `takeover_started`: `by`; `handoff_created`: `expected_response`; `flow_completed`: `result`, `code`;
+     * `turn_failed` (a turn that failed before any of its reply streamed): `code`, `message`, `retryable`.
+     */
+    readonly data: Readonly<Record<string, string | boolean | null>>;
+}
+type TimelineItem = MessageItem | CardItem | SystemItem;
+interface ConversationView {
+    readonly status: ConversationStatus;
+    readonly banner: ConversationBanner;
+    /**
+     * How the conversation goes on after the session ended: `continue` on the person's next action (it resumes on its
+     * own), `continue_here` only when the person asks (`continueHere()`: it continued on another device).
+     */
+    readonly next: 'continue' | 'continue_here' | null;
+    readonly agent: {
+        readonly name: string | null;
+        readonly avatarUrl: string | null;
+    };
+    /** The server's AI disclosure; null until the first one, when the UI shows its own line. Never hidden. */
+    readonly disclosure: string | null;
+    /** While a person from the business replies: their role (`by`, never a name). */
+    readonly takeover: {
+        readonly by: string | null;
+        readonly at: string;
+    } | null;
+    /** Oldest first: history restored from `persistence`, then the conversation. */
+    readonly items: readonly TimelineItem[];
+    /** The turn's tool lines while it runs ("Searching professionals…"); empty otherwise. */
+    readonly activity: readonly ToolLine[];
+    /** A turn is in progress: the agent is working or replying (`cancel()` stops it). */
+    readonly responding: boolean;
+    /** The newest open question card's `id`. */
+    readonly openQuestion: string | null;
+    /** Over SSE: question cards cannot be answered, so the UI points to the composer. */
+    readonly answersNeedWebSocket: boolean;
+    readonly turnsLeft: number | null;
+    /**
+     * The conversation kept on the device (`persistence`): `none` without it, `restoring` while async storage is read
+     * (draw a skeleton, not an empty conversation), `restored` once read, whatever it held.
+     */
+    readonly history: 'none' | 'restoring' | 'restored';
+}
+/** The reply streaming now, flushed at most once per frame. */
+interface StreamingText {
+    /** The streaming message item's `key`. */
+    readonly key: string;
+    readonly turnId: string;
+    readonly text: string;
+}
+
+/** Why the store asks the tenant's backend for a session. */
+type SessionReason = 
+/** The conversation opens (`start()`). */
+'open'
+/** The session ended (idle, expired, its turn limit) and the person acted again. */
+ | 'resume'
+/** The conversation continued on another device, and the person chose to continue here. */
+ | 'continue_here';
+interface SessionRequest {
+    readonly reason: SessionReason;
+    /** The conversation so far, when known: the backend names it (with its `conversation_key`) to resume it. */
+    readonly conversationId: string | null;
+    /** For `subject.locale` and `subject.timezone`, which the backend sets. */
+    readonly locale?: string;
+    readonly timeZone?: string;
+    /**
+     * Aborted when the answer is no longer wanted (the conversation was disposed or cleared, or a newer request took
+     * its place): pass it to `fetch`, so a late answer never opens a socket after the person left.
+     */
+    readonly signal?: AbortSignal;
+}
+/** What `createSession` gave the tenant's backend, as it passes it on: the session, its agent and disclosure. */
+type ConversationSession = SessionInfo & {
+    readonly agent?: {
+        readonly display_name?: string;
+        readonly avatar_url?: string;
+    };
+    readonly disclosure?: string;
+};
+/**
+ * Runs a callback before the next frame; `requestAnimationFrame` where there is one. Every listener, of the view and
+ * of the streaming text, is called from it, at most once per frame: a zone.js app re-enters its zone here once. A
+ * test passes one that runs the callback at once.
+ */
+interface FrameScheduler {
+    request(callback: () => void): unknown;
+    cancel(handle: unknown): void;
+}
+/** Where the drawn conversation is kept across app restarts (opt-in; prefer encrypted storage). */
+interface ConversationPersistence {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+interface ConversationOptions {
+    /**
+     * A session from the tenant's backend, which creates it with its service key (the app never holds one). Asked once
+     * per need: when the conversation opens, and on the person's action after a session ended.
+     */
+    readonly getSession: (request: SessionRequest) => Promise<ConversationSession>;
+    /** A fresh client secret for a session (on 4401), from the tenant's backend. */
+    readonly refreshSecret?: (sessionId: string) => Promise<ClientSecret | string>;
+    readonly locale?: string;
+    readonly timeZone?: string;
+    /** The prefixes the tenant registered for card links (`checkLink`). */
+    readonly deepLinkPrefixes?: readonly string[];
+    /** Keep the drawn conversation across restarts (off unless given). */
+    readonly persistence?: ConversationPersistence;
+    /** Its key; one per signed-in person. Default `vinaverse.conversation`. */
+    readonly persistenceKey?: string;
+    /** Default: `requestAnimationFrame`, else a 16 ms timer, resolved when first used (never at import or creation). */
+    readonly scheduler?: FrameScheduler;
+    /** The transport's own options (`auth`, `webSocket`, `fetch`, delays…). */
+    readonly transport?: Omit<SessionOptions, 'session' | 'refreshSecret' | 'engine' | 'createId'>;
+    /** New `client_event_id`s. Default: random, `ce_` and 22 characters. */
+    readonly createId?: () => string;
+    /** Something failed that no call returned: getting a session, an input that could not be delivered. */
+    readonly onError?: (error: unknown) => void;
+    /**
+     * Close the connection while the app is in the background, and open it again in the foreground (a backend that
+     * mints a client secret per connection: with `refreshSecret`, a fresh one is asked for first). Default false: the
+     * connection stays, with no pings, until the session idles out. Nothing typed or answered is lost either way.
+     */
+    readonly closeInBackground?: boolean;
+}
+/** A text is at most 2000 code points (`TurnInput`). */
+declare const MAX_TEXT = 2000;
+declare class ConversationStore {
+    private readonly options;
+    private readonly engine;
+    private session;
+    private info;
+    private getting;
+    private failed;
+    private disposed;
+    private online;
+    private foreground;
+    private lastStatus;
+    private offlineAfterRetries;
+    /** The id the next send gets, so a text typed before the session keeps its key. */
+    private nextId;
+    private readonly sent;
+    private readonly early;
+    private readonly retried;
+    private readonly busy;
+    /** Proposals whose tenant decision threw: shown as recoverable, the person may decide again. */
+    private readonly decisionErrors;
+    private system;
+    /** Numbers system rows that carry no id of their own. */
+    private systemSeq;
+    private history;
+    private historyState;
+    /** A resumed session.ready carried a transcript: the server's history replaced what the device kept. */
+    private transcriptSeen;
+    /** The session of the last session.ready: a card of another one takes no tap (§6). */
+    private readySession;
+    private cardOrder;
+    private kept;
+    private locale;
+    /** The request for a session in flight, to abort when it is no longer wanted. */
+    private fetching;
+    private view;
+    private readonly listeners;
+    private streaming;
+    private readonly streamListeners;
+    /** The frame that will notify, and what it will notify about. */
+    private frame;
+    private framePending;
+    private viewDirty;
+    private streamDirty;
+    private persistTimer;
+    private unsubscribe;
+    constructor(options: ConversationOptions);
+    getSnapshot: () => ConversationView;
+    subscribe: (listener: () => void) => (() => void);
+    getStreaming: () => StreamingText | null;
+    subscribeStreaming: (listener: () => void) => (() => void);
+    /** Whether a card's link may be opened (the deep-link rule, against `deepLinkPrefixes`). */
+    checkLink(link: string): boolean;
+    /** Ask for a session and connect, early: a client secret must open its first connection within two minutes. */
+    start(): void;
+    /** Close for good. */
+    dispose(): void;
+    /** Close for good and forget the conversation kept on the device (sign-out). Never throws for the storage. */
+    clear(): void;
+    /**
+     * The person switched the app's language: the UI's words change at once (the kit's own locale); the next session
+     * asks for this locale (`subject.locale`). The open session keeps its language: the agent answers in the new one
+     * from the next session, and the store never starts a session for it.
+     */
+    setLocale(locale: string | undefined): void;
+    /** The app came to the foreground or went to the background (AppState, `visibilitychange`). */
+    setForeground(foreground: boolean): void;
+    /** In the background (`closeInBackground`): the connection is closed; the engine keeps what was sent, to resend. */
+    private suspended;
+    private suspend;
+    /** Back in the foreground: a new connection to the same session, with a fresh secret when the backend gives one. */
+    private wake;
+    /** The network as the app sees it; null when unknown. Back online reconnects a connection that gave up. */
+    setOnline(online: boolean | null): void;
+    /** Send a typed message; returns its `client_event_id`. Typed before a session exists, it is sent once one does. */
+    send(text: string): string;
+    /** Answer a question card (a `rate_each` row by its `question_id`); returns the `client_event_id`. */
+    answer(cardId: string, questionId: string, answer: AnswerInput): string;
+    /** A card action (`ui.action`) other than a proposal's outcome. */
+    cardAction(cardId: string, action: string): string;
+    /**
+     * Decide a proposal: `decide` is the tenant's own call (its backend, the person's token), which confirms or
+     * declines it and says the outcome; the store then reports it. One decision per card; the card is busy meanwhile.
+     * Resolves to the outcome reported, or null when the card was busy or already decided.
+     *
+     * Only an outcome `decide` resolves with is reported (§6: the first is final). When `decide` throws, or resolves
+     * with anything but `confirmed`, `declined`, `failed` or `expired`, nothing is reported: the backend may have
+     * applied the change, so the outcome stays unknown; the card shows `decisionError` and the person may decide
+     * again. When the conversation is disposed meanwhile (sign-out), the outcome is not reported either: the tenant's
+     * backend holds it, and the session takes it as unknown.
+     */
+    decideProposal(cardId: string, decide: () => Promise<ProposalOutcome>): Promise<ProposalOutcome | null>;
+    /** Send a "not sent" message again, as a new message (the person's action). Returns the new id. */
+    retry(key: string): string | null;
+    /** After the conversation continued on another device: continue it here (the person's choice). */
+    continueHere(): Promise<void>;
+    /** Stop the turn in progress. */
+    cancel(): void;
+    private ensureSession;
+    private fetchSession;
+    private open;
+    /** What was typed before there was a session to take it. */
+    private flushEarly;
+    /** A new session for the conversation, then `resume()`: once per person action, never in a loop. */
+    private resuming;
+    private resumeWith;
+    /** The person acted after the session ended idle, expired or at its limit: the next session takes what they sent. */
+    private continueIfEnded;
+    private reconnectIfDown;
+    private statusChanged;
+    private event;
+    /**
+     * A resumed session's transcript replaced the messages, and a chat transcript carries text only: the engine drops
+     * the cards it drew, and draws the pending ones again at the end. Each card on screen is anchored just after the
+     * message it followed (by key; the transcript keeps the live keys), so a pending proposal stays where it was, and a
+     * card the transcript dropped stays drawn there; taking no tap when it belongs to an earlier session.
+     */
+    private anchorCards;
+    /**
+     * Recomputes now (getSnapshot and getStreaming are always current) and notifies from the scheduler, at most once
+     * per frame, both channels in the same flush: a streamed reply that completes becomes its message in one frame.
+     */
+    private update;
+    private scheduleNotify;
+    /** Calls the listeners of what changed since the last flush. */
+    private flush;
+    private compute;
+    private status;
+    private nextFrom;
+    /** The streamed text, current at once; its listeners hear of it with the next flush. */
+    private stream;
+    private scheduler;
+    private key;
+    private restore;
+    private schedulePersist;
+    private live;
+    private required;
+}
+/** One conversation with an agent, for any UI: see `ConversationStore`. */
+declare function createConversation(options: ConversationOptions): ConversationStore;
+
+export { AnswerInput, type AnswerProblem, type CardItem, type ConversationBanner, type ConversationOptions, type ConversationPersistence, type ConversationSession, type ConversationStatus, ConversationStore, type ConversationView, type FrameScheduler, HeldCard, MAX_TEXT, type MessageItem, type MessageState, ProposalOutcome, Question, type SessionReason, type SessionRequest, type StreamingText, type SystemEvent, type SystemItem, type TimelineItem, ToolLine, answerProblem, codePoints, createConversation, isAllowedLink, isValidLinkPrefix };