@origonai/web-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,472 @@
+export declare interface Attachment {
+    id: string;
+    name: string;
+    contentType: string;
+    url: string;
+    /**
+     * Client-only preview source (`blob:`, `file://`) the UI can render
+     * immediately. Stripped from outgoing wire bodies, preserved across
+     * event boundaries.
+     */
+    localUrl?: string;
+}
+
+export declare type AttachmentErrorCode = 'EMPTY_FILE' | 'POLICY_UNSUPPORTED_TYPE' | 'POLICY_TYPE_DISABLED' | 'POLICY_TOO_LARGE';
+
+export declare interface AttachmentPolicy {
+    images: AttachmentRule;
+    documents: AttachmentRule;
+    videos: AttachmentRule;
+    audio: AttachmentRule;
+}
+
+export declare interface AttachmentRule {
+    enabled: boolean;
+    /** Maximum allowed size in megabytes. */
+    maxSize: number;
+}
+
+/** Per-frame stats emitted by the worklet (~5 Hz default). */
+export declare interface AudioWorkletStats {
+    pipeline: unknown;
+    captureAlias: number | null;
+    outboundLevel: number;
+    inboundLevel: number;
+    /** Inbound frames dropped by the worklet's bounded queue (cumulative). */
+    droppedInbound: number;
+}
+
+export declare type Channel = 'chat' | 'voice';
+
+export declare class ClientError extends Error {
+    readonly kind: ClientErrorKind;
+    readonly status?: number;
+    readonly code?: string;
+    constructor(json: ClientErrorJSON);
+    toJSON(): ClientErrorJSON;
+    static notInitialized(): ClientError;
+    static noSession(sessionId: string): ClientError;
+    static missingField(field: string): ClientError;
+    static serverUnavailable(status: number): ClientError;
+    static http(status: number, code: string, message: string): ClientError;
+    static attachment(code: AttachmentErrorCode, message: string): ClientError;
+    static cancelled(): ClientError;
+    static other(message: string): ClientError;
+    static session(message: string): ClientError;
+}
+
+export declare interface ClientErrorJSON {
+    kind: ClientErrorKind;
+    status?: number;
+    code?: string;
+    message: string;
+}
+
+export declare type ClientErrorKind = 'notInitialized' | 'noSession' | 'session' | 'missingField' | 'serverUnavailable' | 'http' | 'attachment' | 'cancelled' | 'other';
+
+/**
+ * Cached response of `POST /config`. Shape matches the backend wire
+ * envelope — top-level booleans/objects, no nesting under `chat` /
+ * `call`. Open-ended for forward compat.
+ */
+export declare interface ConfigData {
+    startMessage?: string;
+    theme?: 'light' | 'dark' | 'system';
+    accent?: string;
+    allowAttachments?: boolean;
+    attachmentPolicy?: AttachmentPolicy;
+    multiChannel?: boolean;
+    [key: string]: unknown;
+}
+
+export declare interface Contact {
+    id: string;
+    name: string;
+}
+
+/** Credentials cached by `initialize()` and consumed by `authenticate()`. */
+export declare interface Credentials {
+    endpoint: string;
+    token?: string;
+    userId?: string;
+    attributes?: Record<string, unknown>;
+    /**
+     * Optional absolute base URL the voice assets are fetched from
+     * (`<base>/audio/audio-processor.js` and
+     * `<base>/audio/wasm-gen/origon_web_audio_bg.wasm`). By default the
+     * assets are emitted by the app's bundler next to the SDK's chunk and
+     * need no configuration; set this only when that relocation is
+     * unavailable (e.g. an esbuild-only pipeline) and the two files are
+     * copied to a known location instead. See docs/voice.md.
+     */
+    assetBaseUrl?: string;
+}
+
+/** Mirrors Rust's `DisconnectReason`. */
+export declare type DisconnectReason = {
+    kind: 'localClose';
+} | {
+    kind: 'networkLoss';
+} | {
+    kind: 'remoteHangup';
+} | {
+    kind: 'endpointNotProvisioned';
+} | {
+    kind: 'endpointAlreadyConnected';
+} | {
+    kind: 'tokenInvalid';
+} | {
+    kind: 'tokenExpired';
+} | {
+    kind: 'tokenReplayed';
+} | {
+    kind: 'protocolViolation';
+} | {
+    kind: 'capabilityMissing';
+} | {
+    kind: 'illegalState';
+} | {
+    kind: 'resourceExhausted';
+} | {
+    kind: 'replayLost';
+} | {
+    kind: 'sessionEnded';
+} | {
+    kind: 'serverClosed';
+    code: number;
+    reason: string;
+} | {
+    kind: 'transportClosed';
+    detail: string;
+};
+
+export declare function getSessionManager(): SessionManager;
+
+/**
+ * Attach to a session whose `{sessionId, url, token}` was provisioned out of
+ * band — e.g. a Connect agent answering a pushed call offer, or a supervisor
+ * joining a live call — instead of the SDK originating it via `POST
+ * /session/start`. The triple mirrors `StartSessionResponse`; `url` is the
+ * media/chat base and `token` the per-session credential. See
+ * `SessionManager.joinSession` + CONTRACT.md "Origination modes".
+ */
+export declare interface JoinSessionOptions {
+    channel: Channel;
+    sessionId: string;
+    url: string;
+    token: string;
+    /** Voice-only join behavior. Omit to retain the normal microphone join. */
+    voice?: VoiceJoinOptions;
+}
+
+export declare interface Message {
+    role: MessageRole;
+    id: string;
+    /**
+     * SDK-issued temporary id for outbound messages awaiting server
+     * confirmation. Set on the provisional `onMessageAdded` payload so the
+     * consumer can locate the row when `onMessageUpdated` arrives.
+     */
+    localId?: string;
+    text?: string;
+    html?: string;
+    timestamp?: string;
+    userId?: string;
+    userName?: string;
+    attachments: Attachment[];
+    errorText?: string;
+    status: MessageStatus;
+    state: MessageState;
+    /**
+     * Lifecycle action for a `role:'system'` message — `'queued' | 'joined' |
+     * 'ended'` (kept an open `string`: the server may add more; a distinct
+     * `'left'` was considered and dropped by the producer). Present
+     * on cx's lifecycle system rows; ABSENT on flow-bot system messages,
+     * which stay ordinary bubbles. The consumer's discriminator is
+     * action-**presence** (non-empty), not `role`. Producer: cx's
+     * `chat.v1.Message.action` (`src/orpc-gen/chat_pb.ts`; canonical
+     * side platform/cx CONTRACT §3/§6) — see "Inbound couplings".
+     */
+    action?: string;
+    /** Interactive prompt buttons; absent when the message carries none. */
+    buttons?: MessageButton[];
+    /** Gallery cards; absent when the message carries none. */
+    gallery?: MessageCard[];
+}
+
+/**
+ * Role enum re-exported so consumers can keep an idiom like
+ * `MESSAGE_ROLES.AI` instead of typing the string literal. Values are
+ * the same lowercase strings used on the wire.
+ */
+export declare const MESSAGE_ROLES: {
+    readonly AI: "ai";
+    readonly EXTERNAL: "external";
+    readonly USER: "user";
+    readonly SYSTEM: "system";
+};
+
+/**
+ * One interactive prompt button — `{label, value, type}`. Wire shape:
+ * `chat.v1.Button` (`src/orpc-gen/chat_pb.ts`; the proto field is
+ * `button_type` but the wire key stays `type`, pinned by `json_name`).
+ * Clicking one sends `SendMessagePayload.buttonReply`.
+ */
+export declare interface MessageButton {
+    label: string;
+    value: string;
+    type: string;
+}
+
+/**
+ * One gallery card — `{title, description, image?, buttons}`. Wire shape:
+ * `chat.v1.Card` (`src/orpc-gen/chat_pb.ts`); `image` is absent on a
+ * card authored without one (the wire renders it as JSON `null`).
+ */
+export declare interface MessageCard {
+    title: string;
+    description: string;
+    image?: Attachment;
+    buttons: MessageButton[];
+}
+
+export declare type MessageRole = 'ai' | 'external' | 'user' | 'system';
+
+export declare type MessageState = 'streaming' | 'completed';
+
+export declare type MessageStatus = 'sending' | 'delivered' | 'failed';
+
+/** Mirrors `media-server::MuteScope`. */
+export declare type MuteScope = 'none' | 'uplink' | 'downlink' | 'both';
+
+/**
+ * A non-OK orpc reply (an ERROR frame). `code` is the wire status — a base code
+ * (§5) or a `0x1000+` auth code; `reason` is the server's UTF-8 message.
+ */
+export declare class OrpcError extends Error {
+    readonly code: number;
+    readonly reason: string;
+    constructor(code: number, reason: string);
+}
+
+/**
+ * Optional callbacks the SDK fires through `SessionManager.setCallbacks`.
+ * All callbacks receive `sessionId` and `channel` as their first two args
+ * so a single consumer can host multiple sessions simultaneously.
+ */
+export declare interface SdkCallbacks {
+    /** New message added — fired both for inbound peer messages and the provisional row for outbound sends. */
+    onMessageAdded?: (sessionId: string, channel: Channel, message: Message) => void;
+    /** Existing message updated — server ack of outbound send, or streaming chunk for AI replies. */
+    onMessageUpdated?: (sessionId: string, channel: Channel, update: {
+        id: string;
+        message: Message;
+    }) => void;
+    /** Inbound typing indicator from the peer (debounced by SDK watchdog). */
+    onTyping?: (sessionId: string, channel: Channel, isTyping: boolean) => void;
+    /** Session id changed (e.g. server promoted a temp id, or reattach assigned a new one). */
+    onSessionUpdated?: (sessionId: string, channel: Channel) => void;
+    onConnected?: (sessionId: string, channel: Channel) => void;
+    /**
+     * The terminal signal for BOTH channels — chat ends land here too
+     * (`sessionEnded` / `serverClosed` / `replayLost` / `networkLoss` /
+     * `localClose`).
+     */
+    onDisconnected?: (sessionId: string, channel: Channel, info: {
+        reason: DisconnectReason;
+    }) => void;
+    onReconnecting?: (sessionId: string, channel: Channel, info: {
+        attempt: number;
+        reason: DisconnectReason;
+    }) => void;
+    onReconnected?: (sessionId: string, channel: Channel) => void;
+    onPeerAttached?: (sessionId: string, channel: Channel, peer: {
+        peerEndpointId: string;
+        alias: number;
+    }) => void;
+    onPeerDetached?: (sessionId: string, channel: Channel, peer: {
+        peerEndpointId: string;
+        alias: number;
+    }) => void;
+    onCallError?: (sessionId: string, channel: Channel, error: string | null) => void;
+}
+
+export declare interface SendMessagePayload {
+    text?: string;
+    html?: string;
+    attachments?: Attachment[];
+    /**
+     * Local-only hint for the provisional `onMessageAdded` role. Defaults to
+     * `'external'` when absent; staff dashboards set `'user'`. Stripped before
+     * POST.
+     */
+    role?: MessageRole;
+    /**
+     * Button/gallery reply — sent when the user clicks a quick-reply or
+     * gallery button. Maps onto the wire's top-level `value` /
+     * `gallery_label` (`MessageRequest`).
+     */
+    buttonReply?: {
+        value: string;
+        label?: string;
+    };
+}
+
+export declare type SessionControl = 'ai' | 'user';
+
+export declare interface SessionHistory {
+    history: Message[];
+    control: SessionControl;
+}
+
+/**
+ * Top-level entry point. One instance per app — see `getSessionManager()`
+ * for the singleton accessor.
+ *
+ * Lifecycle: `initialize()` → `authenticate()` → `startSession({channel})`
+ * → chat / voice APIs → `endSession()`.
+ */
+export declare class SessionManager {
+    private config;
+    private userId;
+    private http;
+    private sessionHttp;
+    private attributes;
+    private assetBaseUrl;
+    private readonly dispatcher;
+    private readonly sessions;
+    private readonly pendingUploads;
+    initialize(credentials: Credentials): void;
+    authenticate(): Promise<ConfigData>;
+    setCallbacks(callbacks: SdkCallbacks): void;
+    setAttributes(attributes: Record<string, unknown> | undefined): void;
+    getConfig(): ConfigData | null;
+    getUserId(): string | undefined;
+    activeSessionIds(): Array<{
+        sessionId: string;
+        channel: Channel;
+    }>;
+    getSessions(): Promise<SessionSummary[]>;
+    getSession(sessionId: string): Promise<SessionHistory>;
+    startSession(opts: StartSessionOptions): Promise<{
+        sessionId: string;
+    }>;
+    /**
+     * Attach to a session whose `{sessionId, url, token}` was provisioned out of
+     * band, skipping `POST /session/start`. The counterpart to `startSession`
+     * for consumers that are *handed* a session — a Connect agent answering a
+     * pushed call offer, or a supervisor joining a live call — rather than
+     * originating one. Requires `initialize()` (endpoint stays mandatory, as with
+     * `startSession`); `authenticate()`/`POST /config` is not needed on this path.
+     */
+    joinSession(opts: JoinSessionOptions): Promise<{
+        sessionId: string;
+    }>;
+    /**
+     * Shared core: construct the per-channel session from a
+     * `StartSessionResponse`, register it, fire `onSessionUpdated`, and bring
+     * its transport up. Driven by both `startSession` (after `POST
+     * /session/start`) and `joinSession` (from a caller-supplied response).
+     *
+     * Voice and chat differ in *when* `onConnected` fires: chat fires it here
+     * after `start()`; voice fires it from inside `VoiceSession.dial()` once
+     * the MoQ `ConnectOk` lands — so this method must NOT fire it for voice.
+     */
+    private attachSession;
+    endSession(sessionId: string): Promise<void>;
+    endAllSessions(): Promise<void>;
+    /**
+     * Re-key an active session from `oldId` to `newId` — for a control plane that
+     * reassigns a session's id mid-call (e.g. a Connect warm-transfer /
+     * conference completion) while the media endpoint persists. No transport is
+     * re-dialed: the live session is relabelled (its `rename()`) and its map
+     * entry moved. Fires `onSessionUpdated(newId)` so the consumer can rebind.
+     *
+     * Tolerant, mirroring the native SDK: unknown `oldId` → no-op (warn); `newId`
+     * already active → no-op (warn), so a live session is never clobbered.
+     */
+    migrateSessionId(oldId: string, newId: string): void;
+    sendMessage(sessionId: string, payload: SendMessagePayload): Promise<Message>;
+    notifyTyping(sessionId: string): void;
+    stopTyping(sessionId: string): void;
+    setMute(sessionId: string, scope: MuteScope): Promise<void>;
+    /** Enable microphone coaching on a receive-only voice join. */
+    enableCapture(sessionId: string): Promise<void>;
+    /** Return a coaching voice join to Listen and release its microphone. */
+    releaseCapture(sessionId: string): Promise<void>;
+    setMuteAll(scope: MuteScope): Promise<void>;
+    /**
+     * Subscribe to periodic audio level + pipeline stats for a voice session.
+     * Returns an unsubscribe function. Stats are computed in the worklet
+     * only while at least one subscriber is registered.
+     */
+    subscribeAudioStats(sessionId: string, cb: (stats: AudioWorkletStats) => void): () => void;
+    /**
+     * Upload an attachment. WIDGET-scoped and session-less: the URL is built
+     * from the `endpoint` given to `initialize()`, so an attachment can be the
+     * first thing a visitor sends — no session is opened, and none is required.
+     * Needs `authenticate()` only for the local policy precheck (absent config
+     * defers the whole decision to the server).
+     */
+    uploadAttachment(file: File, options: UploadOptions): Promise<Attachment>;
+    /**
+     * Dual purpose: cancel an in-flight upload (when `idOrUploadId` matches a
+     * pending `uploadId`) OR DELETE a stored attachment by id. Widget-scoped and
+     * session-less on both arms, so a visitor can remove a file they attached
+     * before sending anything.
+     */
+    deleteAttachment(idOrUploadId: string): Promise<void>;
+    private requireChatSession;
+    private requireVoiceSession;
+    private requireSessionHttp;
+    private requireHttp;
+}
+
+export declare interface SessionSummary {
+    sessionId: string;
+    subject: string;
+    channel: Channel;
+    /** True only while the session is live on the cx owner that served this directory. */
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+    lastMessage?: Message;
+    contact?: Contact;
+}
+
+export declare interface StartSessionOptions {
+    channel: Channel;
+    sessionId?: string;
+    data?: Record<string, unknown>;
+}
+
+export declare interface StartSessionResponse {
+    sessionId: string;
+    url: string;
+    token: string;
+}
+
+export declare interface UploadOptions {
+    /** Caller-issued id used to cancel the upload via `delete_attachment`. */
+    uploadId: string;
+    onProgress?: (p: UploadProgress) => void;
+    signal?: AbortSignal;
+}
+
+export declare interface UploadProgress {
+    bytesUploaded: number;
+    totalBytes?: number;
+    percent?: number;
+}
+
+/** Additive options for an out-of-band provisioned voice join. */
+export declare interface VoiceJoinOptions {
+    /**
+     * Start playout and transport without acquiring a microphone. After
+     * `ConnectOk`, the SDK sends `Mute(uplink)` and awaits `MuteOk` before
+     * reporting connected.
+     */
+    receiveOnly?: boolean;
+}
+
+export { }