@vinaverse/client 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/conversation/index.d.ts

@@ -1,5 +1,8 @@
-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.js';
-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.js';
+export { C as CONTRACT } from '../contract-_NMdPjgN.js';
+import { Q as Question, A as AnswerInput } from '../session-8W3fRNeb.js';
+export { a as Card, b as CardGroup, c as CardImage, d as CardKind, C as CardLink, e as ClientErrorCode, H as HeldCard, f as HeldQuestion, P as Proposal, g as ProposalOutcome, T as ToolLine, V as VinaverseClientError, W as Welcome, i as isKnownCard } from '../session-8W3fRNeb.js';
+import { C as ConversationStore, a as ConversationOptions, S as SessionRequest, b as ConversationSession } from '../store-DFk0ayh8.js';
+export { c as CardItem, d as ConversationBanner, e as ConversationPersistence, f as ConversationStatus, g as ConversationView, F as FrameScheduler, M as MAX_TEXT, h as MessageItem, i as MessageState, j as SessionReason, k as StreamingText, l as SystemEvent, m as SystemItem, T as TimelineItem, n as createConversation } from '../store-DFk0ayh8.js';
 
 type AnswerProblem = 
 /** Nothing chosen or typed, and the question is required (or skipped while required). */
@@ -34,352 +37,29 @@ declare function isValidLinkPrefix(prefix: string): boolean;
  */
 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;
-    };
+/** A session request, with the mode it is for. */
+interface ModeSessionRequest extends SessionRequest {
+    readonly mode: 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;
+interface ConversationsByModeOptions extends Omit<ConversationOptions, 'getSession'> {
+    /** Your backend creates the session for the mode's agent (its `subject.type`, its agent), with its service key. */
+    readonly getSession: (request: ModeSessionRequest) => Promise<ConversationSession>;
+    /** Every mode the app has, so `clear()` forgets each one's kept history, even one not opened since launch. */
+    readonly modes?: readonly string[];
 }
-type SystemEvent = 'takeover_started' | 'takeover_ended' | 'handoff_created' | 'flow_completed' | 'turn_failed';
-interface SystemItem {
-    readonly type: 'system';
-    readonly key: string;
-    readonly event: SystemEvent;
+interface ConversationsByMode {
+    /** The mode's store, made the first time it is asked for; the same store after that. */
+    get(mode: string): ConversationStore;
     /**
-     * `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`, `turn` (its `turn_id`), and `retry`:
-     * the server allows a retry and the person's text that started the turn is known, so `retryTurn(key)` sends it
-     * again (false once it did).
+     * The mode the person switched to: its store, with every other mode's sent to the background (no pings; closed
+     * with `closeInBackground`). The kit then drives the selected one with the app's foreground and background.
      */
-    readonly data: Readonly<Record<string, string | boolean | null>>;
-}
-type TimelineItem = MessageItem | CardItem | SystemItem;
-interface ConversationView {
-    readonly status: ConversationStatus;
-    /** The conversation the sessions belong to, once a session named it; for the tenant's own records and support. */
-    readonly conversationId: string | null;
-    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;
-    /** The person's text that started each recent turn, by `turn_id` (`turn.started` echoes its `client_event_id`). */
-    private readonly turnInputs;
-    /** 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. */
+    select(mode: string): ConversationStore;
+    /** Close every mode's store. */
     dispose(): void;
-    /** Close for good and forget the conversation kept on the device (sign-out). Never throws for the storage. */
+    /** Close every mode's store and forget what each kept on the device (sign-out). */
     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;
-    /**
-     * Send again the person's text whose turn failed before any reply (a `turn_failed` row with `data.retry`), as a new
-     * message (the person's action). Once per row: its `retry` turns false. Returns the new id, or null when the row
-     * allows no retry.
-     */
-    retryTurn(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;
-    /** The person's text that started a turn, while its message is on screen. */
-    private turnText;
-    /**
-     * 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;
+declare function createConversationsByMode(options: ConversationsByModeOptions): ConversationsByMode;
 
-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 };
+export { AnswerInput, type AnswerProblem, ConversationOptions, ConversationSession, ConversationStore, type ConversationsByMode, type ConversationsByModeOptions, type ModeSessionRequest, Question, SessionRequest, answerProblem, codePoints, createConversationsByMode, isAllowedLink, isValidLinkPrefix };