@aikaara/chat-sdk 0.8.1 → 0.8.3

package/dist/headless.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./MountTenant-BrBxPpjb.cjs");class r extends i.EventEmitter{registration=null;pendingEdits=[];constructor(e){super(),this.setupListeners(e)}registerForm(e){this.registration=e;const t=this.pendingEdits.filter(s=>s.entity_type===e.entityType&&String(s.entity_id)===String(e.entityId));if(t.length>0){for(const s of t)e.onFieldUpdate(s.fields),this.emit("edit:applied",{entityType:s.entity_type,entityId:s.entity_id,fields:s.fields});this.pendingEdits=this.pendingEdits.filter(s=>!(s.entity_type===e.entityType&&String(s.entity_id)===String(e.entityId)))}}unregisterForm(e,t){this.registration?.entityType===e&&String(this.registration?.entityId)===String(t)&&(this.registration=null)}get currentForm(){return this.registration}pushFieldUpdates(e,t,s){this.registration&&this.registration.entityType===e&&String(this.registration.entityId)===String(t)?(this.registration.onFieldUpdate(s),this.emit("edit:applied",{entityType:e,entityId:t,fields:s})):(this.pendingEdits.push({action:"edit_entity",entity_type:e,entity_id:t,fields:s}),this.emit("edit:pending",{entityType:e,entityId:t,fields:s}))}async requestSave(){if(!this.registration)return{success:!1,error:"No form registered"};try{return await this.registration.onSave(),this.emit("save:success",{entityType:this.registration.entityType,entityId:this.registration.entityId}),{success:!0}}catch(e){const t=e instanceof Error?e.message:"Save failed";return this.emit("save:error",{entityType:this.registration.entityType,entityId:this.registration.entityId,error:t}),{success:!1,error:t}}}async requestTest(e){if(!this.registration?.onTest)return{success:!1,error:"Current form does not support testing"};try{return await this.registration.onTest(e),{success:!0}}catch(t){return{success:!1,error:t instanceof Error?t.message:"Test failed"}}}setupListeners(e){e.on("action:edit_entity",t=>{this.pushFieldUpdates(t.entity_type,t.entity_id,t.fields)}),e.on("action:save_entity",t=>{this.requestSave()}),e.on("action:test_tool",t=>{this.emit("test:triggered",{toolId:t.tool_id,parameters:t.parameters}),this.requestTest(t.parameters)})}}exports.ActionCableClient=i.ActionCableClient;exports.AikaaraChatClient=i.AikaaraChatClient;exports.ApiClient=i.ApiClient;exports.ChannelSubscription=i.ChannelSubscription;exports.ConnectionManager=i.ConnectionManager;exports.ConversationManager=i.ConversationManager;exports.EventEmitter=i.EventEmitter;exports.MessageStore=i.MessageStore;exports.SessionAuthAdapter=i.SessionAuthAdapter;exports.SsoExchangeAdapter=i.SsoExchangeAdapter;exports.TiledeskTransport=i.TiledeskTransport;exports.clearPersistedConversationId=i.clearPersistedConversationId;exports.collectSsoCredentials=i.collectSsoCredentials;exports.createFetchUploadAdapter=i.createFetchUploadAdapter;exports.createPresigned3StepUploadAdapter=i.createPresigned3StepUploadAdapter;exports.createTiledeskHistoryAdapter=i.createTiledeskHistoryAdapter;exports.extractTiledeskFileEnvelope=i.extractTiledeskFileEnvelope;exports.inferTiledeskRole=i.inferTiledeskRole;exports.isTiledeskSelfEcho=i.isTiledeskSelfEcho;exports.mountFromSlug=i.mountFromSlug;exports.mountTenantWidget=i.mount;exports.parseTiledeskTemplate=i.parseTiledeskTemplate;exports.FormBridge=r;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./MountTenant-BCjKRkD8.cjs");class s extends e.EventEmitter{registration=null;pendingEdits=[];constructor(t){super(),this.setupListeners(t)}registerForm(t){this.registration=t;const i=this.pendingEdits.filter(r=>r.entity_type===t.entityType&&String(r.entity_id)===String(t.entityId));if(i.length>0){for(const r of i)t.onFieldUpdate(r.fields),this.emit("edit:applied",{entityType:r.entity_type,entityId:r.entity_id,fields:r.fields});this.pendingEdits=this.pendingEdits.filter(r=>!(r.entity_type===t.entityType&&String(r.entity_id)===String(t.entityId)))}}unregisterForm(t,i){this.registration?.entityType===t&&String(this.registration?.entityId)===String(i)&&(this.registration=null)}get currentForm(){return this.registration}pushFieldUpdates(t,i,r){this.registration&&this.registration.entityType===t&&String(this.registration.entityId)===String(i)?(this.registration.onFieldUpdate(r),this.emit("edit:applied",{entityType:t,entityId:i,fields:r})):(this.pendingEdits.push({action:"edit_entity",entity_type:t,entity_id:i,fields:r}),this.emit("edit:pending",{entityType:t,entityId:i,fields:r}))}async requestSave(){if(!this.registration)return{success:!1,error:"No form registered"};try{return await this.registration.onSave(),this.emit("save:success",{entityType:this.registration.entityType,entityId:this.registration.entityId}),{success:!0}}catch(t){const i=t instanceof Error?t.message:"Save failed";return this.emit("save:error",{entityType:this.registration.entityType,entityId:this.registration.entityId,error:i}),{success:!1,error:i}}}async requestTest(t){if(!this.registration?.onTest)return{success:!1,error:"Current form does not support testing"};try{return await this.registration.onTest(t),{success:!0}}catch(i){return{success:!1,error:i instanceof Error?i.message:"Test failed"}}}setupListeners(t){t.on("action:edit_entity",i=>{this.pushFieldUpdates(i.entity_type,i.entity_id,i.fields)}),t.on("action:save_entity",i=>{this.requestSave()}),t.on("action:test_tool",i=>{this.emit("test:triggered",{toolId:i.tool_id,parameters:i.parameters}),this.requestTest(i.parameters)})}}exports.ActionCableClient=e.ActionCableClient;exports.AikaaraChatClient=e.AikaaraChatClient;exports.ApiClient=e.ApiClient;exports.ChannelSubscription=e.ChannelSubscription;exports.ConnectionManager=e.ConnectionManager;exports.ConversationManager=e.ConversationManager;exports.EventEmitter=e.EventEmitter;exports.MessageStore=e.MessageStore;exports.SessionAuthAdapter=e.SessionAuthAdapter;exports.SsoExchangeAdapter=e.SsoExchangeAdapter;exports.TiledeskTransport=e.TiledeskTransport;exports.TokenDiscoveryError=e.TokenDiscoveryError;exports.TokenDiscoveryReader=e.TokenDiscoveryReader;exports.clearPersistedConversationId=e.clearPersistedConversationId;exports.collectSsoCredentials=e.collectSsoCredentials;exports.createFetchUploadAdapter=e.createFetchUploadAdapter;exports.createPresigned3StepUploadAdapter=e.createPresigned3StepUploadAdapter;exports.createTiledeskHistoryAdapter=e.createTiledeskHistoryAdapter;exports.discoverToken=e.discoverToken;exports.extractTiledeskFileEnvelope=e.extractTiledeskFileEnvelope;exports.inferTiledeskRole=e.inferTiledeskRole;exports.isTiledeskSelfEcho=e.isTiledeskSelfEcho;exports.mountFromSlug=e.mountFromSlug;exports.mountTenantWidget=e.mount;exports.parseTiledeskTemplate=e.parseTiledeskTemplate;exports.FormBridge=s;

package/dist/headless.d.ts

@@ -222,8 +222,18 @@ export declare class ApiClient {
     private baseUrl;
     private apiKey?;
     private authToken?;
-    private userToken;
+    protected userToken: string;
+    private refreshHook;
     constructor(baseUrl: string, userToken: string, apiKey?: string, authToken?: string);
+    /**
+     * Install a refresh hook. When a request returns 401 the client invokes
+     * the hook, replaces its in-memory `authToken`, and retries exactly once.
+     */
+    setAuthRefreshHook(hook: AuthRefreshHook | null): void;
+    /** Surface the current bearer (e.g. for upload adapters that share it). */
+    getAuthToken(): string | undefined;
+    /** Replace the bearer used by subsequent requests. */
+    setAuthToken(next: string | undefined): void;
     createConversation(params: {
         systemPromptId?: number;
         channel?: string;
@@ -234,8 +244,17 @@ export declare class ApiClient {
     getMessages(conversationId: string): Promise<Message[]>;
     private mapMessage;
     private request;
+    private fetchWithHeaders;
 }
 
+export declare type ApiPanelFieldFormat = 'text' | 'currency' | 'date' | 'number';
+
+export declare type ApiPanelRefresh = 'load' | 'assistant' | 'interval' | '30s' | '5m' | 'manual';
+
+export declare type ApiPanelRender = 'fields' | 'steps';
+
+export declare type ApiPanelSource = 'api' | 'paste';
+
 export declare interface AppContext {
     /** Current page/route path in the host app (e.g., '/products/42') */
     currentPage: string;
@@ -266,6 +285,30 @@ declare interface AppContext_2 {
     custom?: Record<string, unknown>;
 }
 
+/**
+ * Static page metadata written by the dashboard's App Layout tab.
+ * The hosted-shell renders top/bottom nav from this list; SDK code
+ * doesn't consume it.
+ */
+export declare interface AppPageDef {
+    id: string;
+    name: string;
+    /** Icon name from the shell's icon set (Chat, Sparkle, Book, …). */
+    icon?: string;
+    /** `"chat"` (default surface) or `"static"` (placeholder). */
+    kind?: 'chat' | 'static';
+    hint?: string;
+}
+
+/**
+ * Hook the API client uses to recover from a 401. Wired up by the higher
+ * level mount when `descriptor.sso.autoRefresh === true`: the discovered
+ * partner token is re-read, exchanged for a fresh chat JWT, and the
+ * `authToken` field below is updated in place so the retry sends the new
+ * bearer. Returning `null` (or throwing) lets the original 401 propagate.
+ */
+declare type AuthRefreshHook = () => Promise<string | null>;
+
 export declare class ChannelSubscription {
     readonly identifier: string;
     private callbacks;
@@ -523,6 +566,16 @@ export declare class ConversationManager {
     private saveToStorage;
 }
 
+export declare interface CookieSourceConfig {
+    /** Cookie name. */
+    name?: string;
+    /**
+     * Informational only. The browser enforces the actual domain scope; we
+     * surface this so dashboards can document intent.
+     */
+    domain?: string;
+}
+
 declare interface CreateConversationResponse {
     id: string;
     status: string;
@@ -536,6 +589,23 @@ export declare function createTiledeskHistoryAdapter(config: TiledeskHistoryAdap
 
 export declare type CredentialProviders = Record<string, () => string | Promise<string>>;
 
+export declare interface DiscoveredToken {
+    /** The raw partner token. */
+    token: string;
+    /** Echoed so callers can log + alert when the source changes mid-flow. */
+    source: TokenSourceKind;
+}
+
+/**
+ * Dispatcher. Resolves the partner token according to
+ * `descriptor.tokenSource`. Returns a Promise so async-only sources
+ * (`postmsg`, `global`) share the same surface as synchronous ones.
+ *
+ * Throws when the token can't be found — callers decide whether to
+ * fall back to a login screen (per `descriptor.fallback`).
+ */
+export declare function discoverToken(opts: TokenDiscoveryOptions): Promise<DiscoveredToken>;
+
 export declare interface EditEntityAction {
     action: 'edit_entity';
     entity_type: string;
@@ -734,8 +804,25 @@ export declare interface FormRegistration {
     getCurrentValues: () => Record<string, unknown>;
 }
 
+export declare interface GlobalSourceConfig {
+    /** Dot-path into `window` (e.g. `"PartnerSDK.session.token"`). */
+    path?: string;
+    /** Max poll time in ms (default 2000). */
+    timeoutMs?: number;
+    /** Poll interval in ms (default 100). */
+    intervalMs?: number;
+}
+
+export declare interface HashSourceConfig {
+    /** Hash key (after `#…&key=value&…`). Default `"token"`. */
+    key?: string;
+}
+
 export declare function inferTiledeskRole(message: TiledeskMessage, cfg: TiledeskRoleConfig): TiledeskRole;
 
+export declare interface InitSourceConfig {
+}
+
 /**
  * Self-echo detector — Tiledesk fans the user's outgoing publish back
  * as a `clientadded` event on the same connection. UI must dedupe against
@@ -899,6 +986,21 @@ declare interface NavigateAction_2 {
 
 export declare function parseTiledeskTemplate(message: TiledeskMessage): TiledeskParsedTemplate;
 
+export declare interface PostMsgSourceConfig {
+    /** Message envelope `type` field that gates which postMessage we accept. */
+    type?: string;
+    /** Property inside `event.data` carrying the token. Default `"token"`. */
+    key?: string;
+    /**
+     * Allowed origins (comma-separated or single string). When set, messages
+     * from any other origin are ignored. When unset every origin is accepted
+     * — partners are encouraged to set this in production.
+     */
+    origins?: string;
+    /** Milliseconds to wait before rejecting. Default 30_000. */
+    timeoutMs?: number;
+}
+
 /**
  * One HTTP call run by the SDK before auth. Failure of `soft: true` steps
  * is logged and ignored; failure of strict steps aborts the mount.
@@ -948,6 +1050,66 @@ export declare interface Presigned3StepAdapterConfig {
     extraHeaders?: Record<string, string>;
 }
 
+export declare interface QuerySourceConfig {
+    /** Query-string parameter name. Default `"token"`. */
+    key?: string;
+}
+
+/**
+ * One slot's component pointer. The `kind` discriminator picks which
+ * loader runs. Both kinds resolve to a `Promise<HTMLElement>` after load,
+ * which the runtime appends into the slot anchor.
+ */
+export declare type RemoteComponent = {
+    kind: 'iife-element';
+    /** URL of an IIFE bundle that calls `customElements.define(tag, …)`. */
+    scriptUrl: string;
+    /** Custom-element tag the bundle registers. */
+    tag: string;
+    /** Optional method-call map: `{ setLayout: "stacked" }` becomes
+     *  `el.setLayout("stacked")` after mount. */
+    props?: Record<string, unknown>;
+} | {
+    kind: 'remote-dom';
+    /** URL of an IIFE bundle that, when executed, leaves a global at
+     *  `globalName` exposing `mount({ target, ctx, complete, props })`.
+     *  Authored via `@aikaara/chat-sdk/remote-author`. */
+    scriptUrl: string;
+    /** Optional global name; defaults to the slot id with non-alphanumeric
+     *  chars replaced by underscores (e.g. "screen:login" → "screen_login"). */
+    globalName?: string;
+    /** Sandbox kind. Today only `iframe`; `worker` reserved for later. */
+    sandbox?: 'iframe' | 'worker';
+    /** Forwarded to the bundle's `mount({ props })` call. */
+    props?: Record<string, unknown>;
+};
+
+/**
+ * One route in `descriptor.app.routes`.
+ *
+ * `path` is matched against the URL pathname AFTER the tenant's slug
+ * prefix is stripped (in subpath mode). Supports trailing wildcards (`/*`)
+ * and named params (`/:id`) — the parser is intentionally tiny.
+ *
+ * `component` references a slot in `descriptor.components`.
+ *
+ * `guards` are simple predicate names the shell evaluates against runtime
+ * session state. Today: `'sso'` (SSO exchange done), `'authed'` (user
+ * has any session), `'panVerified'` (PAN flow finished). Tenants can
+ * extend by exposing flags via `complete(payload)` from preceding screens.
+ *
+ * `redirectIfFails` lets a guard send the user to another route id
+ * instead of erroring. Useful for `'authed'` failing → redirect to login.
+ */
+export declare interface RouteDef {
+    path: string;
+    component: string;
+    guards?: string[];
+    redirectIfFails?: string;
+    /** Optional layout slot wrapping this route's component. */
+    layout?: string;
+}
+
 export declare interface SaveEntityAction {
     action: 'save_entity';
 }
@@ -1014,6 +1176,41 @@ export declare interface SessionAuthDescriptor {
 
 export declare type SessionTokenProvider = string | (() => string | Promise<string>);
 
+export declare interface SidePanelDef {
+    enabled?: boolean;
+    type: SidePanelType;
+    title?: string;
+    mobile?: SidePanelMobile;
+    steps?: Array<{
+        name: string;
+        hint?: string;
+    }>;
+    emptyText?: string;
+    allowUpload?: boolean;
+    summaryFields?: string[];
+    supportPhone?: string;
+    supportHours?: string;
+    showHumanHandoff?: boolean;
+    source?: ApiPanelSource;
+    endpoint?: string;
+    sampleJson?: string;
+    refresh?: ApiPanelRefresh;
+    intervalSec?: number;
+    render?: ApiPanelRender;
+    fields?: Array<{
+        label: string;
+        path: string;
+        format?: ApiPanelFieldFormat;
+    }>;
+    stepsPath?: string;
+    stepStatusKey?: string;
+    customUrl?: string;
+}
+
+export declare type SidePanelMobile = 'drawer' | 'hidden';
+
+export declare type SidePanelType = 'steps' | 'files' | 'summary' | 'support' | 'api' | 'custom';
+
 export declare interface SlugMountedWidget extends MountedTenantWidget {
     fullName: string;
     /** Resolved descriptor (fallback ⊕ fetched ⊕ overrides). Host reads
@@ -1021,6 +1218,13 @@ export declare interface SlugMountedWidget extends MountedTenantWidget {
     descriptor: WidgetConfigDescriptor;
     /** Force a fresh /chatbuddy/auth-style refetch (clears cached requestId). */
     refreshAuth(): Promise<void>;
+    /**
+     * Re-discover the partner token (per `descriptor.sso.tokenSource`) and
+     * re-exchange for a fresh chat JWT. Returns the new bearer or null when
+     * discovery fails. Only available when `descriptor.sso.autoRefresh` is
+     * `true`; returns `null` immediately otherwise.
+     */
+    refreshPartnerAuth(): Promise<string | null>;
 }
 
 export declare interface SlugMountOptions {
@@ -1064,6 +1268,13 @@ export declare interface SlugMountOptions {
          * without host code per call.
          */
         identity?: Record<string, string | undefined>;
+        /**
+         * Partner token supplied directly by the embedding host. Used by
+         * `descriptor.sso.tokenSource === "init"` (v2 sign-in flow) — every
+         * other source kind discovers the token from the page itself
+         * (query / hash / cookie / storage / postMessage / global).
+         */
+        partnerToken?: string;
     };
     /** Optional escape hatches; merge over descriptor-driven defaults. */
     hooks?: {
@@ -1124,8 +1335,37 @@ export declare interface SsoDescriptor {
     apiKey?: string;
     /** Extra static headers attached to the exchange POST. */
     headers?: Record<string, string>;
-    /** Browser credential collection spec. */
-    collect: SsoCollectSpec[];
+    /**
+     * Legacy v1 shape — explicit list of credential sources the browser
+     * reads + posts to the exchange endpoint. Still supported for the
+     * bandhan-itr / myfinancials cohort that shipped before the v2
+     * sign-in tab. Mutually exclusive with `tokenSource` (v2).
+     */
+    collect?: SsoCollectSpec[];
+    /** Provider family. `"partner"` is the only value today. */
+    provider?: string;
+    /** Recipe id paired with this descriptor (e.g. `partner_token_to_backend_jwt`). */
+    flow?: string;
+    /** Skip the login screen entirely — read token, exchange, mount chat. */
+    skipLogin?: boolean;
+    /** Re-read the token source on any request that 401s. */
+    autoRefresh?: boolean;
+    /** Selects which token reader runs at boot. */
+    tokenSource?: TokenSourceKind;
+    /** Per-source config (only the matching block is emitted by the dashboard). */
+    tokenSourceConfig?: TokenSourceConfig;
+    /** What to do when token-discovery fails — show a fallback screen. */
+    fallback?: {
+        enabled?: boolean;
+        method?: 'phone' | 'email';
+    };
+    /** Dot-paths into the partner identity payload returned by `auth`. */
+    map?: {
+        id?: string;
+        email?: string;
+        name?: string;
+        phone?: string;
+    };
 }
 
 export declare class SsoExchangeAdapter {
@@ -1185,6 +1425,15 @@ export declare interface SsoIdentity {
  */
 export declare type SsoSourceKind = 'cookie' | 'localStorage' | 'sessionStorage' | 'url_param' | 'header_meta' | 'callback';
 
+export declare interface StorageSourceConfig {
+    /** `"local"` (default) or `"session"`. */
+    store?: 'local' | 'session';
+    /** Storage key. */
+    key?: string;
+    /** Optional dot-path. When set the value is JSON.parsed and walked. */
+    path?: string;
+}
+
 declare type SubscriptionCallback = (data: unknown) => void;
 
 declare interface TemplateMessageEvent {
@@ -1573,6 +1822,102 @@ declare interface TiledeskTransportConfig_2 {
     debug?: boolean;
 }
 
+export declare interface TokenDiscoveryDescriptor {
+    /** `"partner"` today; reserved for future SSO families. */
+    provider?: string;
+    /** Recipe id the backend pairs with this descriptor. */
+    flow?: string;
+    /** When true the embedded SDK skips the login UI entirely. */
+    skipLogin?: boolean;
+    /** When true the SDK re-reads the source on 401 retries. */
+    autoRefresh?: boolean;
+    /** One of the seven supported source kinds. */
+    tokenSource: TokenSourceKind;
+    /** Source-specific config; only the matching block is read. */
+    tokenSourceConfig?: TokenSourceConfig;
+    /** Fallback (e.g. show a phone OTP screen) when discovery fails. */
+    fallback?: {
+        enabled?: boolean;
+        method?: 'phone' | 'email';
+    };
+    /** Dot-paths into the partner identity payload returned by the auth call. */
+    map?: {
+        id?: string;
+        email?: string;
+        name?: string;
+        phone?: string;
+    };
+}
+
+export declare class TokenDiscoveryError extends Error {
+    readonly source: string;
+    constructor(source: string, msg: string);
+}
+
+export declare interface TokenDiscoveryOptions {
+    /** Descriptor from `widget_configs/:slug` (`configurations.sso`). */
+    descriptor: TokenDiscoveryDescriptor;
+    /**
+     * Initial token explicitly passed to the SDK by the parent caller. Used
+     * by the `init` source kind; ignored by every other.
+     */
+    initToken?: string;
+}
+
+/**
+ * Thin wrapper that re-runs `discoverToken` on demand. Used by
+ * `ApiClient` when a request 401s and `descriptor.sso.autoRefresh` is set.
+ *
+ * The first call caches the token; `.refresh()` forces a re-read of the
+ * source. `init` mode can't be refreshed (the partner already gave us the
+ * single token) — callers should fall through to fallback there.
+ */
+export declare class TokenDiscoveryReader {
+    private readonly opts;
+    private cached;
+    constructor(opts: TokenDiscoveryOptions);
+    get descriptor(): TokenDiscoveryDescriptor;
+    /** Resolve the token. Returns cache if present. */
+    get(): Promise<DiscoveredToken>;
+    /**
+     * Re-evaluate the source. For `init` mode (where the SDK has no way to
+     * re-read) this returns the cached token unchanged — callers should
+     * treat repeated 401s after a refresh attempt as terminal.
+     */
+    refresh(): Promise<DiscoveredToken>;
+}
+
+export declare type TokenSourceConfig = InitSourceConfig | QuerySourceConfig | HashSourceConfig | PostMsgSourceConfig | CookieSourceConfig | StorageSourceConfig | GlobalSourceConfig;
+
+/**
+ * Partner-token discovery dispatcher (v2 sign-in flow).
+ *
+ * The dashboard's Sign-in tab writes a `descriptor.sso` block that names
+ * one of seven token-source modes plus a per-mode config block. At runtime
+ * the SDK reads the descriptor, dispatches to the matching reader, and
+ * returns the raw partner token. When `descriptor.sso.skipLogin === true`
+ * the host shell uses the token directly to do the auth exchange; when
+ * `descriptor.sso.autoRefresh === true` the reader is re-evaluated on any
+ * request that returned 401 (see {@link ApiClient}).
+ *
+ * Reading flows:
+ *   - `init`     — supplied at construction (e.g. `Aikaara.init({token})`).
+ *   - `query`    — `URLSearchParams(location.search).get(cfg.key)`.
+ *   - `hash`     — `location.hash` parsed as URLSearchParams; cfg.key wins.
+ *   - `postmsg`  — `window.addEventListener('message')` filtered by
+ *                  `cfg.type` + `cfg.key`; origins allowlist optional.
+ *   - `cookie`   — `document.cookie` parsed; domain scope is informational
+ *                  (browser already enforces it for the running page).
+ *   - `storage`  — `(localStorage|sessionStorage).getItem(cfg.key)`; when
+ *                  `cfg.path` is set, parsed as JSON + dot-path resolved.
+ *   - `global`   — `window[cfg.path]` resolved via dot-path; polled for
+ *                  up to 2 seconds for late-loading partner SDKs.
+ *
+ * The dispatcher is intentionally side-effect-free apart from
+ * `postmsg` (which has to attach a listener). Callers control caching.
+ */
+export declare type TokenSourceKind = 'init' | 'query' | 'hash' | 'postmsg' | 'cookie' | 'storage' | 'global';
+
 export declare interface ToolCall {
     id: string;
     type: 'function';
@@ -1892,6 +2237,65 @@ export declare interface WidgetConfigDescriptor {
         scriptUrl?: string;
         props?: Record<string, unknown>;
     }>;
+    /**
+     * Multi-screen app definition. When present, the hosted-shell renders a
+     * History-API router rooted at the tenant's mount path. Each route
+     * names a slot key that resolves to a `components[slot]` entry.
+     *
+     * When absent, behaviour is the today's single-screen mount (chat
+     * widget at root). No breaking change for existing tenants.
+     */
+    app?: {
+        /** Route id rendered when path matches `/` (or `/<slug>/` in subpath). */
+        defaultRoute: string;
+        /** Map of route id → definition. */
+        routes: Record<string, RouteDef>;
+        /**
+         * Static page list rendered by the hosted-shell's top/bottom nav. The
+         * dashboard's App Layout tab writes this; the SDK doesn't read it.
+         * Surfaced here so descriptor consumers get a typed view.
+         */
+        pages?: AppPageDef[];
+        /** Side panels wrapping the chat — see {@link SidePanelDef}. */
+        panels?: {
+            left?: SidePanelDef;
+            right?: SidePanelDef;
+        };
+    };
+    /**
+     * Tenant-side API config consumed by the side-panel runtime. Right now
+     * only the `api`-type panel uses this — it prefixes `panel.endpoint`
+     * with `api.baseUrl` and sends the chat JWT as `Authorization`. Other
+     * descriptor blocks (`upload`, `historyApiBase`, etc.) keep their own
+     * fields for backwards compatibility.
+     */
+    api?: {
+        /** Absolute base URL for tenant API calls. No trailing slash. */
+        baseUrl?: string;
+    };
+    /**
+     * Unified slot map. Supersedes `templates` and the bespoke
+     * `linkHandlers[].render` mechanism. Each key is a slot id that some
+     * piece of the runtime knows to look up:
+     *
+     *   "template:<contentTypeOrTemplateId>"  — Tiledesk contentType=300 templates
+     *   "screen:login" | "screen:prechat" | "screen:chat" | …  — full screens
+     *   "panel:header" | "panel:left-rail" | …                — chat-shell side panels
+     *   "viewer:file" | "viewer:compare-plans" | …            — link-modal renderers
+     *
+     * Two component kinds today:
+     *   - `iife-element`  : tenant ships an IIFE that calls customElements.define;
+     *                       SDK loads the script + creates `<tag>` and dispatches.
+     *   - `remote-dom`    : tenant ships a remote-dom bundle (React/Preact/Svelte
+     *                       JSX); SDK lazy-loads `@aikaara/chat-sdk/remote-host`,
+     *                       creates a hidden iframe with DOMRemoteReceiver, and
+     *                       mirrors the tenant's tree into the host slot.
+     *
+     * Backwards compat: at mount time, every entry in `templates` is mirrored
+     * into `components['template:'+id]` as kind:'iife-element' if a matching
+     * key isn't already present. Tenants on the old shape see no change.
+     */
+    components?: Record<string, RemoteComponent>;
 }
 
 /**

package/dist/headless.mjs

@@ -1,5 +1,5 @@
-import { E as s } from "./MountTenant-BVimPLfY.mjs";
-import { A as p, b as l, k as g, C as h, l as c, m as y, M as u, S as m, n as f, T as S, o as T, p as _, q as E, s as v, t as C, u as F, v as A, w as k, x as I, y as x, z as U } from "./MountTenant-BVimPLfY.mjs";
+import { E as s } from "./MountTenant-CxO7hJgs.mjs";
+import { A as p, b as l, k as g, C as c, l as h, m as y, M as u, S as m, n as f, T, o as S, p as _, q as v, s as E, t as C, u as F, v as k, w as A, x as I, y as x, z as U, B as q, D as M, F as b } from "./MountTenant-CxO7hJgs.mjs";
 class a extends s {
   registration = null;
   pendingEdits = [];
@@ -96,24 +96,27 @@ export {
   p as ActionCableClient,
   l as AikaaraChatClient,
   g as ApiClient,
-  h as ChannelSubscription,
-  c as ConnectionManager,
+  c as ChannelSubscription,
+  h as ConnectionManager,
   y as ConversationManager,
   s as EventEmitter,
   a as FormBridge,
   u as MessageStore,
   m as SessionAuthAdapter,
   f as SsoExchangeAdapter,
-  S as TiledeskTransport,
-  T as clearPersistedConversationId,
-  _ as collectSsoCredentials,
-  E as createFetchUploadAdapter,
-  v as createPresigned3StepUploadAdapter,
-  C as createTiledeskHistoryAdapter,
-  F as extractTiledeskFileEnvelope,
-  A as inferTiledeskRole,
-  k as isTiledeskSelfEcho,
-  I as mountFromSlug,
-  x as mountTenantWidget,
-  U as parseTiledeskTemplate
+  T as TiledeskTransport,
+  S as TokenDiscoveryError,
+  _ as TokenDiscoveryReader,
+  v as clearPersistedConversationId,
+  E as collectSsoCredentials,
+  C as createFetchUploadAdapter,
+  F as createPresigned3StepUploadAdapter,
+  k as createTiledeskHistoryAdapter,
+  A as discoverToken,
+  I as extractTiledeskFileEnvelope,
+  x as inferTiledeskRole,
+  U as isTiledeskSelfEcho,
+  q as mountFromSlug,
+  M as mountTenantWidget,
+  b as parseTiledeskTemplate
 };

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./MountTenant-BrBxPpjb.cjs"),s=require("./headless.cjs");function l(a){e.registerComponents();const t=document.createElement("aikaara-chat-widget"),i={baseUrl:"base-url",userToken:"user-token",apiKey:"api-key",title:"title",subtitle:"subtitle",theme:"theme",primaryColor:"primary-color",position:"position",width:"width",height:"height",placeholder:"placeholder",welcomeMessage:"welcome-message",avatarUrl:"avatar-url"};for(const[n,o]of Object.entries(i)){const r=a[n];r!=null&&t.setAttribute(o,String(r))}return t.configure(a),document.body.appendChild(t),t}function d(){const a=document.querySelector("aikaara-chat-widget");a&&a.remove()}exports.ActionCableClient=e.ActionCableClient;exports.AikaaraChatBubble=e.AikaaraChatBubble;exports.AikaaraChatClient=e.AikaaraChatClient;exports.AikaaraChatHeader=e.AikaaraChatHeader;exports.AikaaraChatInput=e.AikaaraChatInput;exports.AikaaraChatWidget=e.AikaaraChatWidget;exports.AikaaraErrorBanner=e.AikaaraErrorBanner;exports.AikaaraMessageBubble=e.AikaaraMessageBubble;exports.AikaaraMessageList=e.AikaaraMessageList;exports.AikaaraStreamingMessage=e.AikaaraStreamingMessage;exports.AikaaraTypingIndicator=e.AikaaraTypingIndicator;exports.ApiClient=e.ApiClient;exports.ChannelSubscription=e.ChannelSubscription;exports.ConnectionManager=e.ConnectionManager;exports.ConversationManager=e.ConversationManager;exports.EventEmitter=e.EventEmitter;exports.MessageStore=e.MessageStore;exports.SessionAuthAdapter=e.SessionAuthAdapter;exports.SsoExchangeAdapter=e.SsoExchangeAdapter;exports.TiledeskTransport=e.TiledeskTransport;exports.clearPersistedConversationId=e.clearPersistedConversationId;exports.collectSsoCredentials=e.collectSsoCredentials;exports.createFetchUploadAdapter=e.createFetchUploadAdapter;exports.createPresigned3StepUploadAdapter=e.createPresigned3StepUploadAdapter;exports.createTiledeskHistoryAdapter=e.createTiledeskHistoryAdapter;exports.extractTiledeskFileEnvelope=e.extractTiledeskFileEnvelope;exports.inferTiledeskRole=e.inferTiledeskRole;exports.isTiledeskSelfEcho=e.isTiledeskSelfEcho;exports.mountFromSlug=e.mountFromSlug;exports.mountTenantWidget=e.mount;exports.parseTiledeskTemplate=e.parseTiledeskTemplate;exports.registerComponents=e.registerComponents;exports.FormBridge=s.FormBridge;exports.mount=l;exports.unmount=d;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./MountTenant-BCjKRkD8.cjs"),s=require("./headless.cjs");function l(a){e.registerComponents();const t=document.createElement("aikaara-chat-widget"),i={baseUrl:"base-url",userToken:"user-token",apiKey:"api-key",title:"title",subtitle:"subtitle",theme:"theme",primaryColor:"primary-color",position:"position",width:"width",height:"height",placeholder:"placeholder",welcomeMessage:"welcome-message",avatarUrl:"avatar-url"};for(const[o,n]of Object.entries(i)){const r=a[o];r!=null&&t.setAttribute(n,String(r))}return t.configure(a),document.body.appendChild(t),t}function d(){const a=document.querySelector("aikaara-chat-widget");a&&a.remove()}exports.ActionCableClient=e.ActionCableClient;exports.AikaaraChatBubble=e.AikaaraChatBubble;exports.AikaaraChatClient=e.AikaaraChatClient;exports.AikaaraChatHeader=e.AikaaraChatHeader;exports.AikaaraChatInput=e.AikaaraChatInput;exports.AikaaraChatWidget=e.AikaaraChatWidget;exports.AikaaraErrorBanner=e.AikaaraErrorBanner;exports.AikaaraMessageBubble=e.AikaaraMessageBubble;exports.AikaaraMessageList=e.AikaaraMessageList;exports.AikaaraStreamingMessage=e.AikaaraStreamingMessage;exports.AikaaraTypingIndicator=e.AikaaraTypingIndicator;exports.ApiClient=e.ApiClient;exports.ChannelSubscription=e.ChannelSubscription;exports.ConnectionManager=e.ConnectionManager;exports.ConversationManager=e.ConversationManager;exports.EventEmitter=e.EventEmitter;exports.MessageStore=e.MessageStore;exports.SessionAuthAdapter=e.SessionAuthAdapter;exports.SsoExchangeAdapter=e.SsoExchangeAdapter;exports.TiledeskTransport=e.TiledeskTransport;exports.TokenDiscoveryError=e.TokenDiscoveryError;exports.TokenDiscoveryReader=e.TokenDiscoveryReader;exports.clearPersistedConversationId=e.clearPersistedConversationId;exports.collectSsoCredentials=e.collectSsoCredentials;exports.createFetchUploadAdapter=e.createFetchUploadAdapter;exports.createPresigned3StepUploadAdapter=e.createPresigned3StepUploadAdapter;exports.createTiledeskHistoryAdapter=e.createTiledeskHistoryAdapter;exports.discoverToken=e.discoverToken;exports.extractTiledeskFileEnvelope=e.extractTiledeskFileEnvelope;exports.inferTiledeskRole=e.inferTiledeskRole;exports.isTiledeskSelfEcho=e.isTiledeskSelfEcho;exports.mountFromSlug=e.mountFromSlug;exports.mountTenantWidget=e.mount;exports.parseTiledeskTemplate=e.parseTiledeskTemplate;exports.registerComponents=e.registerComponents;exports.FormBridge=s.FormBridge;exports.mount=l;exports.unmount=d;