@aikaara/chat-sdk 0.7.2 → 0.7.6

package/dist/index.d.ts

@@ -407,6 +407,9 @@ export declare interface ChatEvents {
 
 export declare function clearPersistedConversationId(userId: string, projectId: string): void;
 
+/** Read every credential listed in `spec`. Throws on missing required. */
+export declare function collectSsoCredentials(opts: SsoCollectorOptions): Promise<Record<string, string>>;
+
 export declare interface ConnectionConfig {
     baseUrl: string;
     wsUrl?: string;
@@ -473,6 +476,8 @@ export declare function createPresigned3StepUploadAdapter(config: Presigned3Step
 
 export declare function createTiledeskHistoryAdapter(config: TiledeskHistoryAdapterConfig): ConversationHistoryAdapter;
 
+export declare type CredentialProviders = Record<string, () => string | Promise<string>>;
+
 export declare interface EditEntityAction {
     action: 'edit_entity';
     entity_type: string;
@@ -506,6 +511,34 @@ export declare interface FieldUpdate {
     previousValue?: unknown;
 }
 
+export declare interface FlowDescriptor {
+    /** Heading rendered above the step list (e.g. "ITR filing process"). */
+    title?: string;
+    steps: FlowStep[];
+}
+
+/**
+ * Static side-rail process taxonomy (e.g. bandhan's "ITR filing process").
+ * Fully descriptor-driven — dashboard owns the steps. The runtime state
+ * (which step is `done` / `active`) is calculated host-side from chat
+ * events (or overlaid from a backend status endpoint like
+ * `/itr/life-cycle-status`).
+ */
+export declare interface FlowStep {
+    /** Stable id used by the host's reducer to address this step. */
+    id: string;
+    /** Display title. */
+    title: string;
+    /** Initial status. The host's `onMessage` reducer flips these as the
+     *  conversation progresses. */
+    state?: 'done' | 'active' | 'pending';
+    /** Optional nested sub-steps (one level deep — bandhan style). */
+    sub?: FlowStep[];
+    /** Free-form metadata the host can use in its reducer (templateId
+     *  patterns the bot uses to advance the step, copy text, hint, etc.). */
+    meta?: Record<string, unknown>;
+}
+
 export declare class FormBridge extends EventEmitter<FormBridgeEvents> {
     private registration;
     private pendingEdits;
@@ -635,7 +668,7 @@ export declare function isTiledeskSelfEcho(message: TiledeskMessage, userId: str
  * Descriptor entry for intercepting link clicks. `match` is a glob pattern
  * (`*` = any, `?` = single char) tested against the full clicked URL.
  */
-declare interface LinkHandler {
+export declare interface LinkHandler {
     /** Glob pattern matched against the clicked URL. */
     match: string;
     /** What to do on match. `tab` opens in new tab, `iframe` uses default modal,
@@ -763,7 +796,7 @@ export declare function parseTiledeskTemplate(message: TiledeskMessage): Tiledes
  * 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.
  */
-declare interface PreflightStep {
+export declare interface PreflightStep {
     url: string;
     method?: 'GET' | 'POST' | 'PUT';
     body?: Record<string, unknown>;
@@ -823,6 +856,16 @@ export declare class SessionAuthAdapter {
     /** Force-refresh by clearing cache. Next `get()` call refetches. */
     reset(): void;
     get(): Promise<SessionAuthData>;
+    /**
+     * Backend often races on first signup — `/chatbuddy/auth?serviceType=ITR`
+     * returns 500 with `customerNew is null` for 5–30 seconds after the
+     * partner-user-onboard call resolves. The data does land eventually;
+     * retry with exponential backoff before bubbling the error up so the
+     * SDK doesn't need to wait by hand. Each retry burns through the
+     * preflight chain too (via the host's `runPreflight` re-invocation),
+     * but the cache makes that cheap.
+     */
+    private static readonly RETRY_DELAYS_MS;
     private fetchOnce;
 }
 
@@ -874,6 +917,9 @@ export declare type SessionTokenProvider = string | (() => string | Promise<stri
 
 export declare interface SlugMountedWidget extends MountedTenantWidget {
     fullName: string;
+    /** Resolved descriptor (fallback ⊕ fetched ⊕ overrides). Host reads
+     *  `descriptor.itrFlow`, `descriptor.theme`, etc. */
+    descriptor: WidgetConfigDescriptor;
     /** Force a fresh /chatbuddy/auth-style refetch (clears cached requestId). */
     refreshAuth(): Promise<void>;
 }
@@ -888,6 +934,12 @@ export declare interface SlugMountOptions {
     /** Additional headers for the descriptor fetch. */
     configHeaders?: Record<string, string>;
     user: {
+        /**
+         * Initial identifier. When `descriptor.sso` is configured, the
+         * server-issued `ext_uid` from the SSO exchange overrides this
+         * value. For SSO-only flows you can pass an empty string and rely
+         * on the exchange to populate the identity.
+         */
         id: string;
         /** Display name fallback when descriptor.auth doesn't return one. */
         name?: string;
@@ -898,12 +950,31 @@ export declare interface SlugMountOptions {
          * or a getter that re-resolves on each refresh.
          */
         token: SessionTokenProvider;
+        /**
+         * Async getters for SSO credentials with `source: "callback"`. Each
+         * key matches a `descriptor.sso.collect[].name` entry. Lets the host
+         * app supply tokens that don't live in cookies / localStorage (e.g.
+         * an in-memory auth context, a parent-frame postMessage).
+         */
+        credentialProviders?: CredentialProviders;
+        /**
+         * Free-form identity bag forwarded to descriptor.preflight URL and
+         * body templates. Keys become `{name}` placeholders. Useful for
+         * tenant-specific fields the SDK doesn't know about (`pan`, `mobile`,
+         * `dob`, etc.) so the descriptor can drive the full warm-up chain
+         * without host code per call.
+         */
+        identity?: Record<string, string | undefined>;
     };
     /** Optional escape hatches; merge over descriptor-driven defaults. */
     hooks?: {
         upload?: UploadAdapter;
         history?: ConversationHistoryAdapter;
         onError?: (err: Error) => void;
+        /** Fired for every chat message (incoming + outgoing). Host apps can
+         *  use this to advance UI state outside the widget — e.g. update an
+         *  ITR-filing-process side rail when the bot moves the flow forward. */
+        onMessage?: (message: Message) => void;
     };
     /** Per-mount visual overrides. */
     overrides?: Partial<WidgetConfigDescriptor>;
@@ -916,6 +987,105 @@ export declare interface SlugMountOptions {
     fallbackConfig?: WidgetConfigDescriptor;
 }
 
+export declare interface SsoCollectorOptions {
+    /** Spec from `descriptor.sso.collect`. */
+    spec: SsoCollectSpec[];
+    /** Async getters for `source: "callback"` entries (host-supplied). */
+    providers?: CredentialProviders;
+}
+
+export declare interface SsoCollectSpec {
+    /** Field name sent to aikaara-ai as `credentials[name]`. */
+    name: string;
+    /** Where to read it from. */
+    source: SsoSourceKind;
+    /** Source-specific key (cookie name, storage key, query param, etc). */
+    key?: string;
+    /** When true, throw if the credential is absent / empty. */
+    required?: boolean;
+    /** Default value if the source doesn't provide one (and not required). */
+    default?: string;
+}
+
+export declare interface SsoDescriptor {
+    /**
+     * Aikaara-ai endpoint that runs the server-side SSO + provisioning chain.
+     * Optional — when omitted the SDK derives it from the same `configBase`
+     * it used to fetch `widget_configs/:slug`:
+     *   `${configBase}/api/v1/projects/by-slug/${slug}/sso_exchange`
+     * Set this only when self-hosted aikaara-ai sits at a different host
+     * than the widget-config endpoint.
+     */
+    exchangeEndpoint?: string;
+    /** localStorage key for the cached identity. Null/empty → no cache. */
+    cacheKey?: string;
+    /** Cache TTL in seconds. Default 1800 (30 min). */
+    cacheTtlSec?: number;
+    /** Per-widget API key sent as `X-Api-Key` to aikaara-ai. */
+    apiKey?: string;
+    /** Extra static headers attached to the exchange POST. */
+    headers?: Record<string, string>;
+    /** Browser credential collection spec. */
+    collect: SsoCollectSpec[];
+}
+
+export declare class SsoExchangeAdapter {
+    private readonly opts;
+    private cache;
+    private inflight;
+    constructor(opts: SsoExchangeOptions);
+    /** Drop any cached identity. Forces a fresh exchange on next `get()`. */
+    reset(): void;
+    /**
+     * Resolve the SSO identity. Returns cached when fresh; otherwise runs the
+     * collect → POST → response flow once and caches the result.
+     */
+    get(force?: boolean): Promise<SsoIdentity>;
+    private exchange;
+    private computeExpiry;
+    private loadCache;
+    private persistCache;
+    private clearCache;
+}
+
+export declare interface SsoExchangeOptions {
+    descriptor: SsoDescriptor;
+    /** Host-supplied async getters for `source: "callback"` entries. */
+    providers?: CredentialProviders;
+    /**
+     * Resolved exchange URL. When `descriptor.exchangeEndpoint` is set it
+     * wins; otherwise `mountFromSlug` builds this from
+     * `${configBase}/api/v1/projects/by-slug/${slug}/sso_exchange`.
+     */
+    exchangeUrl?: string;
+}
+
+export declare interface SsoIdentity {
+    /** Aikaara `User.id` (UUID/int). Useful for support / audit. */
+    id?: string | number;
+    /** Partner system user id, mirrored as Aikaara `User.ext_uid`. */
+    extUid: string;
+    /** Aikaara user token (ActionCable / Aikaara REST bearer). */
+    userToken: string;
+    email?: string;
+    displayName?: string;
+    /** Free-form properties the provisioner wrote on the user row. */
+    properties?: Record<string, unknown>;
+    /** Unix-ms expiry for the cache row (not the token itself). */
+    expiresAt?: number;
+}
+
+/**
+ * Browser-side credential collector for `descriptor.sso.collect`.
+ *
+ * Each entry tells the SDK where to read one credential from. The collected
+ * map gets POSTed to aikaara-ai's `sso_exchange` endpoint, where the
+ * server-side resolver swaps it for a partner identity + provisions an
+ * Aikaara user. No secrets ever live in the public descriptor — this just
+ * tells us "go look at cookie X" or "ask the host app for token Y".
+ */
+export declare type SsoSourceKind = 'cookie' | 'localStorage' | 'sessionStorage' | 'url_param' | 'header_meta' | 'callback';
+
 declare type SubscriptionCallback = (data: unknown) => void;
 
 declare interface TemplateMessageEvent {
@@ -964,8 +1134,17 @@ export declare interface TenantMountOptions {
     overrides?: Partial<WidgetConfigDescriptor>;
     /** Surfaced from the SDK. */
     onError?: (err: Error) => void;
+    /** Forwarded to `WidgetConfig.onMessage` — fires for every message. */
+    onMessage?: (message: Message) => void;
     /** Bearer source for descriptor.linkHandlers fetches. */
     getLinkBearer?: (source: 'session' | 'chat' | 'none') => Promise<string | null>;
+    /**
+     * Aikaara user token used by the ActionCable transport
+     * (`?token=<userToken>` on the cable URL). Comes from the SSO exchange
+     * when present. Tiledesk-only widgets ignore it; defaults to `userId`
+     * for backwards compatibility.
+     */
+    userToken?: string;
 }
 
 export declare interface TestToolAction {
@@ -1329,6 +1508,12 @@ export declare interface WidgetConfigDescriptor {
     };
     /** Defaults merged into every form-action postback */
     templateActionAttributes?: Record<string, unknown>;
+    /**
+     * Static side-rail flow (e.g. bandhan's "ITR filing process"). The
+     * dashboard owns this — host renders it next to the chat. Live state
+     * is overlaid by host code from chat events / status endpoints.
+     */
+    itrFlow?: FlowDescriptor;
     /** Adapter endpoints — SDK builds the actual fetch calls */
     uploadEndpoint?: string;
     uploadFieldName?: string;
@@ -1347,6 +1532,17 @@ export declare interface WidgetConfigDescriptor {
      * itself — the host app no longer needs a `tokenProvider` callback.
      */
     auth?: SessionAuthDescriptor;
+    /**
+     * Aikaara-ai-side SSO + provisioning. When present, the SDK collects the
+     * partner credentials listed in `sso.collect`, POSTs them to
+     * `sso.exchangeEndpoint`, and aikaara-ai resolves a partner identity +
+     * provisions an Aikaara user. The returned `ext_uid` overrides
+     * `opts.user.id` and the returned `userToken` populates
+     * `widgetConfig.userToken` (used by the ActionCable transport). This
+     * runs **before** `auth` — so partner SSO seeds the identity, then
+     * `auth` mints chat-platform JWTs against that identity.
+     */
+    sso?: SsoDescriptor;
     /**
      * HTTP calls fired in order before `auth`. Use for backend warmups whose
      * side effects the auth call depends on (e.g. bandhan's bootstrap
@@ -1416,7 +1612,7 @@ export declare interface WidgetConfigDescriptor {
  * (`--aikaara-<kebab-cased-key>`), so renderers (built-in or
  * tenant-supplied) can style themselves consistently.
  */
-declare interface WidgetTheme {
+export declare interface WidgetTheme {
     primary?: string;
     primaryHover?: string;
     primaryContrast?: string;

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { r as o } from "./MountTenant-Bdm9wkBa.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 T, j as v, k as S, C as w, l as y, m as M, E, M as x, S as B, T as F, n as U, o as I, p as j, q, s as H, t as P, u as W, v as K, w as L, x as O } from "./MountTenant-Bdm9wkBa.mjs";
-import { FormBridge as z } from "./headless.mjs";
+import { r as o } from "./MountTenant-DK039M0S.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-DK039M0S.mjs";
+import { FormBridge as G } from "./headless.mjs";
 function l(e) {
   o();
   const a = document.createElement("aikaara-chat-widget"), r = {
@@ -38,28 +38,30 @@ export {
   C as AikaaraErrorBanner,
   b as AikaaraMessageBubble,
   f as AikaaraMessageList,
-  T as AikaaraStreamingMessage,
-  v as AikaaraTypingIndicator,
-  S as ApiClient,
-  w as ChannelSubscription,
-  y as ConnectionManager,
+  S as AikaaraStreamingMessage,
+  T as AikaaraTypingIndicator,
+  v as ApiClient,
+  y as ChannelSubscription,
+  w as ConnectionManager,
   M as ConversationManager,
   E as EventEmitter,
-  z as FormBridge,
+  G as FormBridge,
   x as MessageStore,
   B as SessionAuthAdapter,
-  F as TiledeskTransport,
-  U as clearPersistedConversationId,
-  I as createFetchUploadAdapter,
-  j as createPresigned3StepUploadAdapter,
-  q as createTiledeskHistoryAdapter,
-  H as extractTiledeskFileEnvelope,
-  P as inferTiledeskRole,
-  W as isTiledeskSelfEcho,
+  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,
   l as mount,
-  K as mountFromSlug,
-  L as mountTenantWidget,
-  O as parseTiledeskTemplate,
+  L as mountFromSlug,
+  O as mountTenantWidget,
+  R 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-BNpG6T7E.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-CTSUKHmw.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.d.ts

@@ -22,6 +22,19 @@ export declare class AikaaraChat extends HTMLElement {
     static get observedAttributes(): string[];
     /** Set programmatically when the session token must be refreshed dynamically. */
     tokenGetter?: () => string | Promise<string>;
+    /** Per-widget API key sent as `X-Api-Key` to aikaara-ai. Either set this
+     *  property OR pass the `api-key` attribute. Required by hosted aikaara
+     *  backends that gate `widget_configs/:slug`. */
+    apiKey?: string;
+    /** Extra headers attached to the descriptor fetch. Set via JS property
+     *  for callers (Flutter / Vue / etc.) that prefer property-style config.
+     *  Merged on top of the auto-added `X-Api-Key` from `apiKey` / `api-key`. */
+    configHeaders?: Record<string, string>;
+    /** Free-form identity bag forwarded to descriptor.preflight URL + body
+     *  templates as `{name}` placeholders. */
+    identity?: Record<string, string | undefined>;
+    /** Async credential providers for `descriptor.sso.collect[].source = "callback"`. */
+    credentialProviders?: Record<string, () => string | Promise<string>>;
     private mounted;
     private mountInflight;
     connectedCallback(): void;

package/dist/ui.mjs

@@ -1,4 +1,4 @@
-import { y as i, a as s, c as e, d as t, e as A, z as k, f as n, B as o, g, h as l, D as d, F as m, i as p, G as C, H as h, I as b, j as M, r as c } from "./MountTenant-Bdm9wkBa.mjs";
+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-DK039M0S.mjs";
 export {
   i as AikaaraChat,
   s as AikaaraChatBubble,

package/package.json

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