@hainiva/agent-sdk 0.0.0-stage → 0.3.0

package/dist/cjs/contract.d.cts

@@ -0,0 +1,225 @@
+/**
+ * GENERATED from the HAINIVA monorepo (@aicc/types agentApi.ts and
+ * agentEvents.ts) — do not edit by hand. The Agent API's response shapes and
+ * event names: additive changes only within a major version.
+ */
+export type AgentPresenceStatus = "online" | "busy" | "away" | "offline";
+export type AgentRole = "agent" | "supervisor";
+export interface AgentMeDto {
+    id: string;
+    externalId: string | null;
+    displayName: string | null;
+    role: AgentRole;
+    /** Team ids this member works in; null = the whole organisation. */
+    teams: string[] | null;
+    status: AgentPresenceStatus | null;
+    session: {
+        id: string;
+        agentAppId: string;
+        mode: "live" | "test";
+        expiresAt: string;
+    };
+}
+export interface AgentRingDto {
+    callId: string;
+    conversationId: string;
+    kind: "voice" | "video" | "chat";
+    channel: string;
+    contactName: string | null;
+    callerNumber: string | null;
+    /** direct = routed to you; queue = offered to your queue; escalation = a live call handed to you. */
+    path: "direct" | "queue" | "escalation";
+    startedAt: string;
+}
+export interface AgentCallDto {
+    callId: string;
+    conversationId: string;
+    kind: "voice" | "video" | "chat";
+    channel: string;
+    direction: "inbound" | "outbound" | "internal";
+    status: string;
+    assignedToMe: boolean;
+    startedAt: string;
+    endedAt: string | null;
+    contactName: string | null;
+    callerNumber: string | null;
+}
+export interface AgentMediaTokenDto {
+    token: string;
+    roomName: string;
+    livekitUrl: string;
+    expiresAt: string;
+}
+export interface AgentConversationDto {
+    id: string;
+    status: string;
+    subject: string | null;
+    channel: string | null;
+    chatType: string | null;
+    contact: {
+        id: string;
+        name: string | null;
+        phone: string | null;
+    };
+    assignedAgentId: string | null;
+    assignedToMe: boolean;
+    queueId: string | null;
+    /** The open interaction a message or file goes to (null when none is open). */
+    activeInteractionId: string | null;
+    lastMessageAt: string | null;
+    createdAt: string;
+    closedAt: string | null;
+}
+export interface AgentMessageDto {
+    id: string;
+    conversationId: string;
+    interactionId: string;
+    direction: string;
+    senderType: string;
+    /** agents.id of the sender when an agent wrote it. */
+    senderAgentId: string | null;
+    senderName: string | null;
+    type: string;
+    text: string | null;
+    attachment: {
+        name: string | null;
+        mimeType: string | null;
+        size: number | null;
+    } | null;
+    createdAt: string;
+}
+export interface AgentDispositionDto {
+    code: string;
+    label: string;
+    channel: string | null;
+    required: boolean;
+}
+export interface SupervisorLiveCallDto {
+    callId: string;
+    conversationId: string;
+    agentId: string | null;
+    agentName: string | null;
+    channel: string;
+    status: string;
+    startedAt: string;
+    contactName: string | null;
+    callerNumber: string | null;
+    queueId: string | null;
+}
+export interface SupervisorAgentDto {
+    id: string;
+    displayName: string;
+    externalId: string | null;
+    role: AgentRole;
+    teamId: string | null;
+    status: AgentPresenceStatus;
+    activeCalls: number;
+    openConversations: number;
+}
+export interface AgentPage<T> {
+    data: T[];
+    nextCursor: string | null;
+}
+/** POST /agent/v1/sessions (201) and POST /agent/v1/sessions/refresh (200). */
+export interface AgentSessionDto {
+    accessToken: string;
+    accessExpiresAt: string;
+    /** hnv_rt_…, rotating: each refresh answers a new one and the old one stops working. */
+    refreshToken: string;
+    refreshExpiresAt: string;
+    sessionId: string;
+    member: {
+        id: string;
+        externalId: string | null;
+        displayName: string;
+        role: AgentRole;
+    };
+    app: {
+        id: string;
+        name: string;
+        mode: "live" | "test";
+    };
+    /** The event socket on the host the app reached; SDKs derive their own from their base URL. */
+    wsUrl: string;
+}
+/**
+ * POST /agent/v1/desk-session (201) — partner platform S4, the embeddable desk.
+ * A 15-minute token for the HAINIVA desk shown inside the partner's product,
+ * handed to the desk over postMessage only (never in a URL, never stored).
+ * Bound to the agent session it came from: ends when that session ends.
+ */
+export interface AgentDeskSessionDto {
+    token: string;
+    expiresAt: string;
+}
+/** POST /agent/v1/calls/:id/accept. `media` is null for a call without a room (chat). */
+export interface AgentAcceptDto {
+    callId: string;
+    accepted: true;
+    media: AgentMediaTokenDto | null;
+}
+/** POST /agent/v1/supervisor/calls/:id/supervise. */
+export interface SupervisorSuperviseDto {
+    callId: string;
+    mode: "monitor" | "whisper" | "barge";
+    media: AgentMediaTokenDto;
+}
+/** POST /agent/v1/push/subscriptions body. */
+export interface AgentPushSubscriptionInput {
+    platform: "ios" | "android";
+    /** FCM registration token (Android) or APNs device token, hex (iPhone). */
+    token: string;
+    /** voip = rings (PushKit on iPhone, high-priority data on Android); alert = ordinary notices. */
+    kind: "voip" | "alert";
+    /** Must be one of the agent app's allowedBundleIds. */
+    bundleId: string;
+    /** A stable id for this install: a new token from the same install replaces the old one. */
+    deviceId?: string;
+}
+/** POST /agent/v1/push/subscriptions (201). The token is never echoed. */
+export interface AgentPushSubscriptionDto {
+    id: string;
+    platform: "ios" | "android";
+    kind: "voip" | "alert";
+    bundleId: string;
+    /** Whether the agent app has working push credentials for this platform right now. */
+    deliverable: boolean;
+    createdAt: string;
+}
+/** Event data of the stream's call.ringing. */
+export interface AgentCallRingingData {
+    callId: string;
+    conversationId: string;
+    path: "direct" | "queue" | "transfer";
+    channel?: string | null;
+    line?: string | null;
+    contactName: string | null;
+    callerNumber?: string | null;
+    fromAgentId?: string | null;
+    fromAgentName?: string | null;
+    transferMode?: "warm" | "blind";
+    /** ISO time the ring ends, when the server knows it. */
+    expiresAt: string | null;
+}
+/** Event data of the stream's call.ended. callId is null when only the conversation is known. */
+export interface AgentCallEndedData {
+    callId: string | null;
+    conversationId: string | null;
+    reason: "ended" | "failed" | "answered_elsewhere" | "declined" | "expired" | "transfer_ended";
+    answeredBy?: string | null;
+    failure?: {
+        reason: string;
+    };
+}
+export declare const AGENT_EVENT_NAMES: readonly ["call.ringing", "call.ended", "conversation.assigned", "message.created", "wrapup.required", "presence.changed", "supervisor.alert"];
+export type AgentEventName = (typeof AGENT_EVENT_NAMES)[number];
+export interface AgentEvent {
+    event: AgentEventName;
+    data: Record<string, unknown>;
+}
+/** What the stream delivers: the event plus its position (resume from it). */
+export interface AgentStreamFrame extends AgentEvent {
+    type: "event";
+    seq: number;
+    at: string;
+}

package/dist/cjs/embed.cjs

@@ -0,0 +1,253 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESK_ALLOW = exports.DESK_SANDBOX = exports.DeskHost = void 0;
+exports.parseDeskMessage = parseDeskMessage;
+exports.deskUrl = deskUrl;
+exports.mountDesk = mountDesk;
+const errors_js_1 = require("./errors.cjs");
+const url_js_1 = require("./url.cjs");
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const END_REASONS = new Set(["not_embedded", "no_host", "expired", "revoked", "host_ended", "misconfigured"]);
+const PHONE = /^[0-9+*#() .-]{1,40}$/;
+function keysAre(o, required, optional = []) {
+    const k = Object.keys(o);
+    return required.every((r) => k.includes(r)) && k.every((x) => required.includes(x) || optional.includes(x));
+}
+const optId = (v) => v === undefined || (typeof v === "string" && UUID.test(v));
+/** Exactly one of the desk's messages, or null. */
+function parseDeskMessage(data) {
+    let d = data;
+    if (typeof d === "string") {
+        if (d.length > 8192)
+            return null;
+        try {
+            d = JSON.parse(d);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!d || typeof d !== "object" || Array.isArray(d))
+        return null;
+    const o = d;
+    if (o["v"] !== 1)
+        return null;
+    switch (o["type"]) {
+        case "hainiva:ready":
+            return keysAre(o, ["v", "type", "appId"]) && typeof o["appId"] === "string" && UUID.test(o["appId"]) ? { v: 1, type: "hainiva:ready", appId: o["appId"] } : null;
+        case "hainiva:token-request":
+            return keysAre(o, ["v", "type", "reason"]) && (o["reason"] === "expiring" || o["reason"] === "unauthorized") ? { v: 1, type: "hainiva:token-request", reason: o["reason"] } : null;
+        case "hainiva:ended":
+            return keysAre(o, ["v", "type", "reason"]) && typeof o["reason"] === "string" && END_REASONS.has(o["reason"])
+                ? { v: 1, type: "hainiva:ended", reason: o["reason"] } : null;
+        case "hainiva:dial":
+            if (!keysAre(o, ["v", "type", "number"], ["contactId"]) || typeof o["number"] !== "string" || !PHONE.test(o["number"]) || !optId(o["contactId"]))
+                return null;
+            return { v: 1, type: "hainiva:dial", number: o["number"], ...(o["contactId"] ? { contactId: o["contactId"] } : {}) };
+        case "hainiva:dialer":
+            if (!keysAre(o, ["v", "type"], ["number", "contactId"]) || !optId(o["contactId"]))
+                return null;
+            if (o["number"] !== undefined && (typeof o["number"] !== "string" || !PHONE.test(o["number"])))
+                return null;
+            return { v: 1, type: "hainiva:dialer", ...(o["number"] ? { number: o["number"] } : {}), ...(o["contactId"] ? { contactId: o["contactId"] } : {}) };
+        case "hainiva:open-url": {
+            if (!keysAre(o, ["v", "type", "url"]) || typeof o["url"] !== "string" || o["url"].length > 2048)
+                return null;
+            let u;
+            try {
+                u = new URL(o["url"]);
+            }
+            catch {
+                return null;
+            }
+            return ["https:", "http:", "mailto:", "tel:"].includes(u.protocol) ? { v: 1, type: "hainiva:open-url", url: u.href } : null;
+        }
+        case "hainiva:media-error":
+            return keysAre(o, ["v", "type", "name"]) && typeof o["name"] === "string" && o["name"].length <= 60 ? { v: 1, type: "hainiva:media-error", name: o["name"] } : null;
+        default:
+            return null;
+    }
+}
+/**
+ * The host side of the desk protocol, transport-agnostic: `mountDesk` (iframe)
+ * and `<HainivaDesk/>` (React Native WebView) both drive one.
+ * @internal exported for the React Native entry and tests.
+ */
+class DeskHost {
+    constructor(appId, source, send, cb) {
+        this.appId = appId;
+        this.source = source;
+        this.send = send;
+        this.cb = cb;
+        this.ended = false;
+        this.ready = false;
+        this.inflight = null;
+    }
+    get isReady() { return this.ready; }
+    get isEnded() { return this.ended; }
+    /** A raw message from the desk (already origin/source-checked by the transport). */
+    receive(raw) {
+        if (this.ended)
+            return;
+        const m = parseDeskMessage(raw);
+        if (!m)
+            return;
+        switch (m.type) {
+            case "hainiva:ready":
+                if (m.appId.toLowerCase() !== this.appId.toLowerCase())
+                    return;
+                this.ready = true;
+                void this.supplyToken();
+                return;
+            case "hainiva:token-request":
+                void this.supplyToken();
+                return;
+            case "hainiva:ended":
+                this.finish(m.reason, false);
+                return;
+            case "hainiva:dial":
+                this.cb.onDial?.(m.number, m.contactId);
+                return;
+            case "hainiva:dialer":
+                this.cb.onDialer?.({ ...(m.number ? { number: m.number } : {}), ...(m.contactId ? { contactId: m.contactId } : {}) });
+                return;
+            case "hainiva:open-url":
+                this.cb.onOpenUrl?.(m.url);
+                return;
+            case "hainiva:media-error":
+                this.cb.onMediaError?.(m.name);
+                return;
+        }
+    }
+    /** One desk-session request at a time; the token goes to the desk only. */
+    supplyToken() {
+        if (this.ended)
+            return Promise.resolve();
+        this.inflight ?? (this.inflight = (async () => {
+            try {
+                const d = await this.source.desk.session();
+                if (!this.ended)
+                    this.send({ v: 1, type: "hainiva:token", token: d.token, expiresAt: d.expiresAt });
+            }
+            catch (e) {
+                // A final refusal of the agent session: the desk ends with it. A
+                // transient failure: the desk asks again (or ends on its own timeout).
+                const final = e instanceof errors_js_1.HainivaAgentError && (e.status === 401 || e.status === 403);
+                if (final)
+                    this.finish("session_ended", true);
+            }
+            finally {
+                this.inflight = null;
+            }
+        })());
+        return this.inflight;
+    }
+    setTheme(mode) { if (mode === "light" || mode === "dark")
+        this.send({ v: 1, type: "hainiva:theme", mode }); }
+    setLocale(locale) { if (locale === "vi" || locale === "en")
+        this.send({ v: 1, type: "hainiva:locale", locale }); }
+    finish(reason, tellDesk) {
+        if (this.ended)
+            return;
+        if (tellDesk) {
+            try {
+                this.send({ v: 1, type: "hainiva:end" });
+            }
+            catch { /* gone */ }
+        }
+        this.ended = true;
+        this.cb.onEnded?.(reason);
+    }
+}
+exports.DeskHost = DeskHost;
+/** The desk page for an app. The URL carries the app id ONLY. */
+function deskUrl(baseUrl, appId, opts = {}) {
+    if (!UUID.test(appId))
+        throw new errors_js_1.HainivaAgentError(0, "invalid_id", { field: "appId" });
+    const base = (0, url_js_1.assertSafeUrl)(baseUrl, { kind: "http", ...(opts.allowInsecureLocalhost ? { allowInsecureLocalhost: true } : {}) });
+    const u = new URL("/embed", base.origin);
+    u.searchParams.set("app", appId.toLowerCase());
+    return u;
+}
+// ── Web: the iframe ──────────────────────────────────────────────────────────
+/**
+ * The iframe's sandbox — every flag the desk needs and nothing more:
+ *   allow-scripts                 the desk is an application;
+ *   allow-same-origin             the desk keeps ITS OWN origin (app.hainiva.com):
+ *                                 its same-origin API calls, its session storage
+ *                                 and the gateway's Origin check depend on it. It
+ *                                 gives the desk no access to your page — that is
+ *                                 a different origin;
+ *   allow-forms                   the composer and every dialog submit forms;
+ *   allow-popups                  links, recordings and help open in a new tab…
+ *   allow-popups-to-escape-sandbox …as normal pages, not sandboxed copies;
+ *   allow-downloads               call recordings, attachments, exports;
+ *   allow-modals                  the desk confirms destructive actions (confirm()).
+ * Deliberately NOT: allow-top-navigation(-by-user-activation) — the desk can
+ * never navigate your page; allow-pointer-lock, allow-presentation,
+ * allow-orientation-lock, allow-storage-access-by-user-activation.
+ */
+exports.DESK_SANDBOX = "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals";
+/** Calls in the iframe are WebRTC: the microphone (and camera for video) must be delegated. */
+exports.DESK_ALLOW = "microphone; camera; autoplay; clipboard-write";
+/** Show the HAINIVA desk in `container`, signed in as your agent session's staff member. */
+function mountDesk(container, o) {
+    if (!container || typeof container.appendChild !== "function")
+        throw new errors_js_1.HainivaAgentError(0, "invalid_container", {});
+    if (!o?.agent?.desk || typeof o.agent.desk.session !== "function")
+        throw new errors_js_1.HainivaAgentError(0, "invalid_agent", {});
+    const url = deskUrl(o.baseUrl, o.appId, o.allowInsecureLocalhost ? { allowInsecureLocalhost: true } : {});
+    const deskOrigin = url.origin;
+    const doc = container.ownerDocument ?? globalThis.document;
+    const win = (doc?.defaultView ?? globalThis);
+    if (!doc)
+        throw new errors_js_1.HainivaAgentError(0, "no_document", {});
+    if (win.location?.origin === deskOrigin)
+        throw new errors_js_1.HainivaAgentError(0, "same_origin_host", { origin: deskOrigin });
+    const iframe = doc.createElement("iframe");
+    iframe.setAttribute("sandbox", exports.DESK_SANDBOX);
+    iframe.setAttribute("allow", exports.DESK_ALLOW);
+    iframe.setAttribute("title", o.title ?? "HAINIVA");
+    iframe.setAttribute("referrerpolicy", "origin");
+    iframe.style.border = "0";
+    iframe.style.width = "100%";
+    iframe.style.height = "100%";
+    const host = new DeskHost(o.appId, o.agent, (m) => { iframe.contentWindow?.postMessage(m, deskOrigin); }, {
+        ...o,
+        onEnded: (r) => { clearTimeout(loadTimer); o.onEnded?.(r); },
+    });
+    const onMessage = (e) => {
+        if (e.source !== iframe.contentWindow || e.origin !== deskOrigin)
+            return;
+        const wasReady = host.isReady;
+        host.receive(e.data);
+        if (!wasReady && host.isReady) {
+            clearTimeout(loadTimer);
+            if (o.theme)
+                host.setTheme(o.theme);
+            if (o.locale)
+                host.setLocale(o.locale);
+        }
+    };
+    win.addEventListener("message", onMessage);
+    const loadTimer = setTimeout(() => { if (!host.isReady)
+        host.finish("load_failed", false); }, o.loadTimeoutMs ?? 20000);
+    iframe.setAttribute("src", url.href);
+    container.appendChild(iframe);
+    return {
+        iframe,
+        setTheme: (m) => host.setTheme(m),
+        setLocale: (l) => host.setLocale(l),
+        destroy: () => {
+            clearTimeout(loadTimer);
+            if (!host.isEnded) {
+                try {
+                    iframe.contentWindow?.postMessage({ v: 1, type: "hainiva:end" }, deskOrigin);
+                }
+                catch { /* gone */ }
+            }
+            win.removeEventListener("message", onMessage);
+            iframe.remove();
+        },
+    };
+}

package/dist/cjs/embed.d.cts

@@ -0,0 +1,187 @@
+/**
+ * @hainiva/agent-sdk/embed — the HAINIVA desk inside your web product.
+ *
+ *   import { HainivaAgent } from "@hainiva/agent-sdk";
+ *   import { mountDesk } from "@hainiva/agent-sdk/embed";
+ *
+ *   const agent = new HainivaAgent({ baseUrl: "https://api.hainiva.com", tenantId, getAssertion });
+ *   await agent.connect();
+ *   const desk = mountDesk(document.getElementById("desk")!, {
+ *     agent, appId: "<your agent app id>", baseUrl: "https://app.hainiva.com",
+ *     onEnded: (reason) => showSignedOut(reason),
+ *   });
+ *   // later: desk.setTheme("dark"); desk.destroy();
+ *
+ * Your staff member is signed in with YOUR agent session: the SDK exchanges it
+ * for a 15-minute desk token (POST /agent/v1/desk-session) and hands that to
+ * the desk over postMessage — never in the URL, never stored. The desk asks
+ * for a fresh one before it expires; when the session ends (signed out,
+ * suspended, app paused) the desk shows "ended" and `onEnded` fires.
+ *
+ * Your page's origin must be in the agent app's `allowedOrigins`: that list is
+ * also the desk's CSP frame-ancestors, so any other site gets a blank frame.
+ *
+ * Security, both directions:
+ *   - only messages whose `event.source` is THIS iframe's window and whose
+ *     `event.origin` is the HAINIVA desk origin are read, and only in the exact
+ *     message shapes below;
+ *   - everything we send goes to the desk origin only (never "*").
+ */
+import type { AgentDeskSessionDto } from "./contract.cjs";
+export type DeskEndReason = "not_embedded" | "no_host" | "expired" | "revoked" | "host_ended" | "misconfigured"
+/** The desk never answered (wrong origin: the CSP blocked the frame; network). */
+ | "load_failed"
+/** Your agent session could not provide a desk token. */
+ | "session_ended";
+/** From the desk. */
+export type DeskToHost = {
+    v: 1;
+    type: "hainiva:ready";
+    appId: string;
+} | {
+    v: 1;
+    type: "hainiva:token-request";
+    reason: "expiring" | "unauthorized";
+} | {
+    v: 1;
+    type: "hainiva:ended";
+    reason: Exclude<DeskEndReason, "load_failed" | "session_ended">;
+} | {
+    v: 1;
+    type: "hainiva:dial";
+    number: string;
+    contactId?: string;
+} | {
+    v: 1;
+    type: "hainiva:dialer";
+    number?: string;
+    contactId?: string;
+} | {
+    v: 1;
+    type: "hainiva:open-url";
+    url: string;
+} | {
+    v: 1;
+    type: "hainiva:media-error";
+    name: string;
+};
+/** To the desk. */
+export type HostToDesk = {
+    v: 1;
+    type: "hainiva:token";
+    token: string;
+    expiresAt: string;
+} | {
+    v: 1;
+    type: "hainiva:theme";
+    mode: "light" | "dark";
+} | {
+    v: 1;
+    type: "hainiva:locale";
+    locale: "vi" | "en";
+} | {
+    v: 1;
+    type: "hainiva:end";
+};
+/** Exactly one of the desk's messages, or null. */
+export declare function parseDeskMessage(data: unknown): DeskToHost | null;
+/** Where the desk token comes from: `HainivaAgent` (its `desk.session()`), or anything shaped like it. */
+export interface DeskTokenSource {
+    desk: {
+        session(): Promise<AgentDeskSessionDto>;
+    };
+}
+export interface DeskCallbacks {
+    /** The desk wants to place a call (React Native: your native call; web: the desk calls itself and never sends this). */
+    onDial?: (number: string, contactId?: string) => void;
+    /** Open your dialer, optionally pre-filled. */
+    onDialer?: (prefill: {
+        number?: string;
+        contactId?: string;
+    }) => void;
+    /** The desk's session is over. Show your own signed-out state; mount again after a new sign-in. */
+    onEnded?: (reason: DeskEndReason) => void;
+    /** A link the desk cannot open itself (React Native). Default: ignored. */
+    onOpenUrl?: (url: string) => void;
+    /** The microphone/camera was refused (web): check your iframe's `allow` and the browser's permission. */
+    onMediaError?: (name: string) => void;
+}
+/**
+ * The host side of the desk protocol, transport-agnostic: `mountDesk` (iframe)
+ * and `<HainivaDesk/>` (React Native WebView) both drive one.
+ * @internal exported for the React Native entry and tests.
+ */
+export declare class DeskHost {
+    private readonly appId;
+    private readonly source;
+    private readonly send;
+    private readonly cb;
+    private ended;
+    private ready;
+    private inflight;
+    constructor(appId: string, source: DeskTokenSource, send: (m: HostToDesk) => void, cb: DeskCallbacks);
+    get isReady(): boolean;
+    get isEnded(): boolean;
+    /** A raw message from the desk (already origin/source-checked by the transport). */
+    receive(raw: unknown): void;
+    /** One desk-session request at a time; the token goes to the desk only. */
+    supplyToken(): Promise<void>;
+    setTheme(mode: "light" | "dark"): void;
+    setLocale(locale: "vi" | "en"): void;
+    finish(reason: DeskEndReason, tellDesk: boolean): void;
+}
+/** The desk page for an app. The URL carries the app id ONLY. */
+export declare function deskUrl(baseUrl: string, appId: string, opts?: {
+    allowInsecureLocalhost?: boolean;
+}): URL;
+/**
+ * The iframe's sandbox — every flag the desk needs and nothing more:
+ *   allow-scripts                 the desk is an application;
+ *   allow-same-origin             the desk keeps ITS OWN origin (app.hainiva.com):
+ *                                 its same-origin API calls, its session storage
+ *                                 and the gateway's Origin check depend on it. It
+ *                                 gives the desk no access to your page — that is
+ *                                 a different origin;
+ *   allow-forms                   the composer and every dialog submit forms;
+ *   allow-popups                  links, recordings and help open in a new tab…
+ *   allow-popups-to-escape-sandbox …as normal pages, not sandboxed copies;
+ *   allow-downloads               call recordings, attachments, exports;
+ *   allow-modals                  the desk confirms destructive actions (confirm()).
+ * Deliberately NOT: allow-top-navigation(-by-user-activation) — the desk can
+ * never navigate your page; allow-pointer-lock, allow-presentation,
+ * allow-orientation-lock, allow-storage-access-by-user-activation.
+ */
+export declare const DESK_SANDBOX = "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals";
+/** Calls in the iframe are WebRTC: the microphone (and camera for video) must be delegated. */
+export declare const DESK_ALLOW = "microphone; camera; autoplay; clipboard-write";
+export interface MountDeskOptions extends DeskCallbacks {
+    /** A connected HainivaAgent (or anything with `desk.session()`). */
+    agent: DeskTokenSource;
+    /** Your agent app id (its allowedOrigins must list this page's origin). */
+    appId: string;
+    /** The HAINIVA desk, e.g. https://app.hainiva.com. */
+    baseUrl: string;
+    theme?: "light" | "dark";
+    locale?: "vi" | "en";
+    /** The iframe's accessible title. Default "HAINIVA". */
+    title?: string;
+    /** No `hainiva:ready` within this long = onEnded("load_failed"). Default 20 s. */
+    loadTimeoutMs?: number;
+    /** Local development only (http://localhost desk). */
+    allowInsecureLocalhost?: boolean;
+}
+export interface MountedDesk {
+    /** Remove the desk (it is told to drop its token first). */
+    destroy(): void;
+    setTheme(mode: "light" | "dark"): void;
+    setLocale(locale: "vi" | "en"): void;
+    /** The iframe, for sizing. */
+    readonly iframe: HTMLIFrameElement;
+}
+interface ContainerLike {
+    appendChild(n: unknown): unknown;
+    ownerDocument?: Document | null;
+}
+/** Show the HAINIVA desk in `container`, signed in as your agent session's staff member. */
+export declare function mountDesk(container: ContainerLike, o: MountDeskOptions): MountedDesk;
+export {};