@aikaara/chat-sdk 0.8.2 → 0.8.3

package/dist/index.d.ts

@@ -293,7 +293,17 @@ export declare class ApiClient {
     private apiKey?;
     private authToken?;
     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;
@@ -304,8 +314,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;
@@ -321,6 +340,30 @@ export declare interface AppContext {
     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;
@@ -475,6 +518,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;
@@ -488,6 +541,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;
@@ -665,8 +735,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
@@ -802,6 +889,21 @@ export declare interface NavigateAction {
 
 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.
@@ -851,6 +953,11 @@ export declare interface Presigned3StepAdapterConfig {
     extraHeaders?: Record<string, string>;
 }
 
+export declare interface QuerySourceConfig {
+    /** Query-string parameter name. Default `"token"`. */
+    key?: string;
+}
+
 export declare function registerComponents(): void;
 
 /**
@@ -858,7 +965,7 @@ export declare function registerComponents(): void;
  * loader runs. Both kinds resolve to a `Promise<HTMLElement>` after load,
  * which the runtime appends into the slot anchor.
  */
-declare type RemoteComponent = {
+export declare type RemoteComponent = {
     kind: 'iife-element';
     /** URL of an IIFE bundle that calls `customElements.define(tag, …)`. */
     scriptUrl: string;
@@ -899,7 +1006,7 @@ declare type RemoteComponent = {
  * `redirectIfFails` lets a guard send the user to another route id
  * instead of erroring. Useful for `'authed'` failing → redirect to login.
  */
-declare interface RouteDef {
+export declare interface RouteDef {
     path: string;
     component: string;
     guards?: string[];
@@ -970,6 +1077,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
@@ -977,6 +1119,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 {
@@ -1020,6 +1169,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?: {
@@ -1080,8 +1236,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 {
@@ -1141,6 +1326,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 {
@@ -1425,6 +1619,102 @@ export declare interface TiledeskTransportConfig {
     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';
@@ -1722,6 +2012,28 @@ export declare interface WidgetConfigDescriptor {
         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

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { r as o } from "./MountTenant-DzNgBTiU.mjs";
-import { A as u, a as m, b as g, c as h, d as k, e as A, f as C, g as b, h as f, i as S, j as T, k as v, C as y, l as w, m as M, E, M as x, S as B, n as F, T as U, o as I, p as j, q, s as H, t as P, u as W, v as z, w as K, x as L, y as O, z as R } from "./MountTenant-DzNgBTiU.mjs";
-import { FormBridge as G } from "./headless.mjs";
+import { r as o } from "./MountTenant-CxO7hJgs.mjs";
+import { A as u, a as m, b as k, c as g, d as h, e as A, f as C, g as T, h as b, i as v, j as f, k as y, C as S, l as w, m as E, E as M, M as x, S as B, n as F, T as U, o as D, p as I, q as j, s as q, t as H, u as P, v as R, w as W, x as z, y as K, z as L, B as O, D as G, F as J } from "./MountTenant-CxO7hJgs.mjs";
+import { FormBridge as Q } from "./headless.mjs";
 function l(e) {
   o();
   const a = document.createElement("aikaara-chat-widget"), r = {
@@ -31,37 +31,40 @@ function d() {
 export {
   u as ActionCableClient,
   m as AikaaraChatBubble,
-  g as AikaaraChatClient,
-  h as AikaaraChatHeader,
-  k as AikaaraChatInput,
+  k as AikaaraChatClient,
+  g as AikaaraChatHeader,
+  h as AikaaraChatInput,
   A as AikaaraChatWidget,
   C as AikaaraErrorBanner,
-  b as AikaaraMessageBubble,
-  f as AikaaraMessageList,
-  S as AikaaraStreamingMessage,
-  T as AikaaraTypingIndicator,
-  v as ApiClient,
-  y as ChannelSubscription,
+  T as AikaaraMessageBubble,
+  b as AikaaraMessageList,
+  v as AikaaraStreamingMessage,
+  f as AikaaraTypingIndicator,
+  y as ApiClient,
+  S as ChannelSubscription,
   w as ConnectionManager,
-  M as ConversationManager,
-  E as EventEmitter,
-  G as FormBridge,
+  E as ConversationManager,
+  M as EventEmitter,
+  Q as FormBridge,
   x as MessageStore,
   B as SessionAuthAdapter,
   F as SsoExchangeAdapter,
   U as TiledeskTransport,
-  I as clearPersistedConversationId,
-  j as collectSsoCredentials,
-  q as createFetchUploadAdapter,
-  H as createPresigned3StepUploadAdapter,
-  P as createTiledeskHistoryAdapter,
-  W as extractTiledeskFileEnvelope,
-  z as inferTiledeskRole,
-  K as isTiledeskSelfEcho,
+  D as TokenDiscoveryError,
+  I as TokenDiscoveryReader,
+  j as clearPersistedConversationId,
+  q as collectSsoCredentials,
+  H as createFetchUploadAdapter,
+  P as createPresigned3StepUploadAdapter,
+  R as createTiledeskHistoryAdapter,
+  W as discoverToken,
+  z as extractTiledeskFileEnvelope,
+  K as inferTiledeskRole,
+  L as isTiledeskSelfEcho,
   l as mount,
-  L as mountFromSlug,
-  O as mountTenantWidget,
-  R as parseTiledeskTemplate,
+  O as mountFromSlug,
+  G as mountTenantWidget,
+  J as parseTiledeskTemplate,
   o as registerComponents,
   d as unmount
 };

package/dist/ui.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("./MountTenant-DvmiAoZ_.cjs");exports.AikaaraChat=a.AikaaraChat;exports.AikaaraChatBubble=a.AikaaraChatBubble;exports.AikaaraChatHeader=a.AikaaraChatHeader;exports.AikaaraChatInput=a.AikaaraChatInput;exports.AikaaraChatWidget=a.AikaaraChatWidget;exports.AikaaraComparePlans=a.AikaaraComparePlans;exports.AikaaraErrorBanner=a.AikaaraErrorBanner;exports.AikaaraLinkModal=a.AikaaraLinkModal;exports.AikaaraMessageBubble=a.AikaaraMessageBubble;exports.AikaaraMessageList=a.AikaaraMessageList;exports.AikaaraModalAction=a.AikaaraModalAction;exports.AikaaraOptionList=a.AikaaraOptionList;exports.AikaaraStreamingMessage=a.AikaaraStreamingMessage;exports.AikaaraSubmitAction=a.AikaaraSubmitAction;exports.AikaaraSystemPill=a.AikaaraSystemPill;exports.AikaaraTemplateRenderer=a.AikaaraTemplateRenderer;exports.AikaaraTypingIndicator=a.AikaaraTypingIndicator;exports.registerComponents=a.registerComponents;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("./MountTenant-BCjKRkD8.cjs");exports.AikaaraChat=a.AikaaraChat;exports.AikaaraChatBubble=a.AikaaraChatBubble;exports.AikaaraChatHeader=a.AikaaraChatHeader;exports.AikaaraChatInput=a.AikaaraChatInput;exports.AikaaraChatWidget=a.AikaaraChatWidget;exports.AikaaraComparePlans=a.AikaaraComparePlans;exports.AikaaraErrorBanner=a.AikaaraErrorBanner;exports.AikaaraLinkModal=a.AikaaraLinkModal;exports.AikaaraMessageBubble=a.AikaaraMessageBubble;exports.AikaaraMessageList=a.AikaaraMessageList;exports.AikaaraModalAction=a.AikaaraModalAction;exports.AikaaraOptionList=a.AikaaraOptionList;exports.AikaaraStreamingMessage=a.AikaaraStreamingMessage;exports.AikaaraSubmitAction=a.AikaaraSubmitAction;exports.AikaaraSystemPill=a.AikaaraSystemPill;exports.AikaaraTemplateRenderer=a.AikaaraTemplateRenderer;exports.AikaaraTypingIndicator=a.AikaaraTypingIndicator;exports.registerComponents=a.registerComponents;

package/dist/ui.mjs

@@ -1,4 +1,4 @@
-import { B as i, a as s, c as e, d as t, e as A, D as k, f as n, F as o, g, h as l, G as d, H as m, i as p, I as C, J as h, K as b, j as M, r as c } from "./MountTenant-DzNgBTiU.mjs";
+import { G as i, a as s, c as e, d as t, e as A, H as k, f as n, I as o, g, h as l, J as d, K as m, i as p, L as C, N as h, O as b, j as M, r as c } from "./MountTenant-CxO7hJgs.mjs";
 export {
   i as AikaaraChat,
   s as AikaaraChatBubble,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikaara/chat-sdk",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "type": "module",
   "description": "Aikaara Chat SDK — embeddable chat widget and headless client",
   "license": "MIT",