@returningai/widget-sdk 1.7.2 → 1.8.0

package/dist/types/BaseWidget.d.ts

@@ -1,5 +1,4 @@
-import type { ReturningAIStoreCallbackFieldOptionsCallback, ReturningAIStorePurchaseSuccessCallback, ReturningAIWidgetCallback, WidgetConfig } from "./types";
-import { STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME, STORE_PURCHASE_SUCCESS_CALLBACK_NAME } from "./types";
+import type { ReturningAIWidgetCallback, ReturningAIWidgetCallbackMap, WidgetConfig } from "./types";
 export declare function readConfig(el: Element, existingId?: string): WidgetConfig;
 export declare abstract class BaseWidget extends HTMLElement {
     static get observedAttributes(): string[];
@@ -17,12 +16,12 @@ export declare abstract class BaseWidget extends HTMLElement {
     private hasAttemptedInit;
     private initGeneration;
     private lottieInstances;
+    private renderedLoaderAnimationKey;
     private callbackRegistry;
     private bannerNode;
     private releaseAutoThemeDisableLease?;
     constructor();
-    registerCallback(callbackName: typeof STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME, callback: ReturningAIStoreCallbackFieldOptionsCallback): void;
-    registerCallback(callbackName: typeof STORE_PURCHASE_SUCCESS_CALLBACK_NAME, callback: ReturningAIStorePurchaseSuccessCallback): void;
+    registerCallback<K extends keyof ReturningAIWidgetCallbackMap>(callbackName: K, callback: ReturningAIWidgetCallbackMap[K]): void;
     registerCallback(callbackName: string, callback: ReturningAIWidgetCallback): void;
     lockCallbacks(): void;
     protected abstract buildWidgetUrl(config: WidgetConfig): string;
@@ -53,6 +52,8 @@ export declare abstract class BaseWidget extends HTMLElement {
     private applyFirstPaintColors;
     private applyFont;
     private applyPalette;
+    private applyLoadingSettings;
+    private getLoadingAnimationRenderKey;
     private renderShell;
     /**
      * Loads the community loading animation + theme palette from cache or API
@@ -98,6 +99,7 @@ export declare abstract class BaseWidget extends HTMLElement {
     private isCurrentInit;
     private teardownMountedWidget;
     private createIframe;
+    private prepareBundleRuntimeEnvironment;
     private mountWidget;
     private scheduleRefresh;
     private schedulePeriodicSync;

package/dist/types/core/bundle-runtime-cache.d.ts

@@ -6,6 +6,11 @@ interface BundleRuntimeLoaderOptions {
     readGlobal: (globalName: string) => unknown;
     baseUrl: () => string;
 }
+interface BundleRuntimeWarmerOptions {
+    preloadScript: (url: string) => Promise<void>;
+    baseUrl: () => string;
+}
+export declare function createBundleRuntimeWarmer({ preloadScript, baseUrl, }: BundleRuntimeWarmerOptions): (globalName: string, bundleUrl: string) => void;
 export declare function normalizeBundleUrl(url: string, baseUrl: string): string;
 /**
  * Cache widget runtimes by both their window global and normalized bundle URL.
@@ -16,5 +21,6 @@ export declare function normalizeBundleUrl(url: string, baseUrl: string): string
  * reuse A without re-evaluating its IIFE.
  */
 export declare function createBundleRuntimeLoader({ loadScript, readGlobal, baseUrl, }: BundleRuntimeLoaderOptions): (globalName: string, bundleUrl: string) => Promise<WidgetBundleRuntime>;
+export declare function warmBundleRuntime(globalName: string, bundleUrl: string): void;
 export declare function getOrLoadBundleRuntime(globalName: string, bundleUrl: string): Promise<WidgetBundleRuntime>;
 export {};

package/dist/types/core/host-callback.d.ts

@@ -0,0 +1,49 @@
+import type { ReturningAIWidgetCallbacks, ReturningAIWidgetType, WidgetConfig, WidgetHostCallbackPayload } from '../types';
+export type HostCallbackCompletionMode = 'result' | 'acknowledged' | 'detached';
+export type HostCallbackTransport = 'bundle' | 'iframe';
+export type HostCallbackAction = 'widget:host-callback' | 'store:host-callback';
+export type HostCallbackLifecycleEventType = 'callback.received' | 'callback.handler_missing' | 'callback.handler_started' | 'callback.handler_resolved' | 'callback.handler_rejected';
+export interface HostCallbackLifecycleEvent {
+    type: HostCallbackLifecycleEventType;
+    invocationId: string;
+    callbackName: string;
+    scope: string;
+    sourceWidgetType: ReturningAIWidgetType;
+    hostWidgetType: ReturningAIWidgetType;
+    completionMode: HostCallbackCompletionMode;
+    transport?: HostCallbackTransport;
+    error?: unknown;
+}
+/** Optional observation boundary. The SDK does not install an observer by default. */
+export type HostCallbackObserver = (event: HostCallbackLifecycleEvent) => void;
+export interface HostCallbackDefinition {
+    callbackName: string;
+    scope: string;
+    sourceWidgetType: ReturningAIWidgetType;
+    allowedHostWidgetTypes: readonly ReturningAIWidgetType[];
+    completionMode: HostCallbackCompletionMode;
+    missingHandler: 'reject' | 'ignore';
+    legacyActions: readonly HostCallbackAction[];
+    validatePayload(payload: unknown): payload is WidgetHostCallbackPayload;
+}
+export interface DispatchHostCallbackInput {
+    callbacks: ReturningAIWidgetCallbacks;
+    callbackName: string;
+    payload: unknown;
+    hostWidgetType: ReturningAIWidgetType;
+    invocationId?: string;
+    transport?: HostCallbackTransport;
+    observer?: HostCallbackObserver;
+}
+/** Mirrors auth identity-source precedence; token authenticity is enforced by widget authentication. */
+export declare function resolveHostUserIdentifiers(config: Pick<WidgetConfig, 'embedToken' | 'userIdentifiers'>): Record<string, string>;
+/** Adds host-owned identity values without making widget code depend on auth internals. */
+export declare function enrichHostCallbackPayload(payload: unknown, userIdentifiers?: Record<string, string>): unknown;
+export declare function getHostCallbackDefinition(callbackName: string, payload: unknown): HostCallbackDefinition | undefined;
+export declare function isHostCallbackMessageSupported(definition: HostCallbackDefinition, action: string, sourceWidgetType: string, hostWidgetType: ReturningAIWidgetType): boolean;
+/**
+ * Runs every supported host callback through one policy-driven boundary.
+ * Detached callbacks return immediately; acknowledged/result callbacks return
+ * a promise that preserves their existing request/response behavior.
+ */
+export declare function dispatchHostCallback(input: DispatchHostCallbackInput): Promise<unknown> | void;

package/dist/types/index.d.ts

@@ -18,6 +18,6 @@ declare global {
     }
 }
 export { StoreWidget, ChannelWidget, MilestoneWidget, SocialWidget, CurrencyWidget, ReferralWidget, CustomWidget };
-export type { ReturningAIStoreCallbackFieldOptionsCallback, ReturningAIStoreHostCallbackActionMessage, ReturningAIStorePurchaseSuccessCallback, ReturningAIWidgetCallback, ReturningAIWidgetCallbackRegistration, ReturningAIWidgetActionMessage, ReturningAIWidgetActionResultMessage, ReturningAIWidgetCallbacks, StoreCallbackFieldOptionsContext, StoreCallbackFieldOptionsField, StoreCallbackFieldOptionsFieldType, StoreCallbackFieldOptionsPayload, StoreCallbackFieldOptionsResult, StoreHostCallbackPayload, StorePurchaseSuccessPayload, } from './types';
-export { STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME, STORE_CALLBACK_FIELD_OPTIONS_SCOPE, STORE_CALLBACK_FIELD_OPTIONS_TIMEOUT_MS, STORE_PURCHASE_SUCCESS_CALLBACK_NAME, STORE_PURCHASE_SUCCESS_SCOPE, } from './types';
+export type { MilestoneCtaClickPayload, ReturningAIGenericHostCallbackActionMessage, ReturningAIMilestoneCtaClickCallback, ReturningAIStoreCallbackFieldOptionsCallback, ReturningAIStoreHostCallbackActionMessage, ReturningAIStorePurchaseSuccessCallback, ReturningAIWidgetCallback, ReturningAIWidgetCallbackMap, ReturningAIWidgetCallbackRegistration, ReturningAIWidgetActionMessage, ReturningAIWidgetActionResultMessage, ReturningAIWidgetCallbacks, ReturningAIWidgetHostCallbackActionMessage, ReturningAIWidgetType, StoreCallbackFieldOptionsContext, StoreCallbackFieldOptionsField, StoreCallbackFieldOptionsFieldType, StoreCallbackFieldOptionsPayload, StoreCallbackFieldOptionsResult, StoreHostCallbackPayload, StorePurchaseSuccessPayload, WidgetHostCallbackPayload, } from './types';
+export { MILESTONE_CTA_CLICK_CALLBACK_NAME, MILESTONE_CTA_CLICK_EVENT, MILESTONE_CTA_CLICK_SCOPE, STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME, STORE_CALLBACK_FIELD_OPTIONS_SCOPE, STORE_CALLBACK_FIELD_OPTIONS_TIMEOUT_MS, STORE_PURCHASE_SUCCESS_CALLBACK_NAME, STORE_PURCHASE_SUCCESS_SCOPE, } from './types';
 export type {} from './jsx';

package/dist/types/types.d.ts

@@ -3,6 +3,10 @@ export declare const STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME: "callbackFieldO
 export declare const STORE_CALLBACK_FIELD_OPTIONS_TIMEOUT_MS = 15000;
 export declare const STORE_PURCHASE_SUCCESS_SCOPE: "store.purchase_success";
 export declare const STORE_PURCHASE_SUCCESS_CALLBACK_NAME: "storePurchaseSuccess";
+export declare const MILESTONE_CTA_CLICK_SCOPE: "milestone.cta_click";
+export declare const MILESTONE_CTA_CLICK_CALLBACK_NAME: "milestoneCtaClick";
+export declare const MILESTONE_CTA_CLICK_EVENT: "milestone_cta_clicked";
+export type ReturningAIWidgetType = 'store' | 'channel' | 'milestone' | 'social' | 'currency-view' | 'referral-conditions' | 'custom';
 export type StoreCallbackFieldOptionsFieldType = 'single-select';
 export interface StoreCallbackFieldOptionsField {
     id: string;
@@ -53,25 +57,55 @@ export interface StorePurchaseSuccessPayload {
     };
 }
 export type StoreHostCallbackPayload = StoreCallbackFieldOptionsPayload | StorePurchaseSuccessPayload;
+export interface MilestoneCtaClickPayload {
+    scope: typeof MILESTONE_CTA_CLICK_SCOPE;
+    callbackName: typeof MILESTONE_CTA_CLICK_CALLBACK_NAME;
+    context: {
+        event: typeof MILESTONE_CTA_CLICK_EVENT;
+        community: {
+            id: string;
+            name?: string | null;
+        };
+        milestone: {
+            id: string;
+            name: string;
+        };
+        stage: {
+            id: string;
+            name: string;
+        };
+        button: {
+            name: string;
+        };
+        user: {
+            identifiers: Record<string, string>;
+        };
+        clickedAt: string;
+    };
+}
+export type WidgetHostCallbackPayload = StoreHostCallbackPayload | MilestoneCtaClickPayload;
 export type ReturningAIWidgetCallback<TPayload = any, TResult = any> = (payload: TPayload) => Promise<TResult> | TResult;
 export type ReturningAIStoreCallbackFieldOptionsCallback = (payload: StoreCallbackFieldOptionsPayload) => Promise<StoreCallbackFieldOptionsResult> | StoreCallbackFieldOptionsResult;
 export type ReturningAIStorePurchaseSuccessCallback = (payload: StorePurchaseSuccessPayload) => Promise<unknown> | unknown;
-export type ReturningAIWidgetCallbacks = {
-    'callbackFieldOptions'?: ReturningAIStoreCallbackFieldOptionsCallback;
-    'storePurchaseSuccess'?: ReturningAIStorePurchaseSuccessCallback;
+export type ReturningAIMilestoneCtaClickCallback = (payload: MilestoneCtaClickPayload) => Promise<unknown> | unknown;
+export interface ReturningAIWidgetCallbackMap {
+    callbackFieldOptions: ReturningAIStoreCallbackFieldOptionsCallback;
+    storePurchaseSuccess: ReturningAIStorePurchaseSuccessCallback;
+    milestoneCtaClick: ReturningAIMilestoneCtaClickCallback;
+}
+export type ReturningAIWidgetCallbacks = Partial<ReturningAIWidgetCallbackMap> & {
     [callbackName: string]: ReturningAIWidgetCallback | undefined;
 };
 export interface ReturningAIWidgetCallbackRegistration {
-    registerCallback(callbackName: typeof STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME, callback: ReturningAIStoreCallbackFieldOptionsCallback): void;
-    registerCallback(callbackName: typeof STORE_PURCHASE_SUCCESS_CALLBACK_NAME, callback: ReturningAIStorePurchaseSuccessCallback): void;
+    registerCallback<K extends keyof ReturningAIWidgetCallbackMap>(callbackName: K, callback: ReturningAIWidgetCallbackMap[K]): void;
     registerCallback(callbackName: string, callback: ReturningAIWidgetCallback): void;
     lockCallbacks(): void;
 }
-export interface ReturningAIWidgetActionMessage<TPayload extends StoreHostCallbackPayload = StoreCallbackFieldOptionsPayload> {
+export interface ReturningAIWidgetActionMessage<TPayload extends WidgetHostCallbackPayload = StoreCallbackFieldOptionsPayload, TWidgetType extends ReturningAIWidgetType = 'store', TAction extends 'widget:host-callback' | 'store:host-callback' = 'store:host-callback'> {
     type: 'RETURNINGAI_WIDGET_ACTION';
     requestId: string;
-    widgetType: 'store';
-    action: 'store:host-callback';
+    widgetType: TWidgetType;
+    action: TAction;
     containerId?: string;
     widgetId?: string;
     callbackName: string;
@@ -79,10 +113,12 @@ export interface ReturningAIWidgetActionMessage<TPayload extends StoreHostCallba
     payload: TPayload;
 }
 export type ReturningAIStoreHostCallbackActionMessage = ReturningAIWidgetActionMessage<StoreHostCallbackPayload>;
+export type ReturningAIGenericHostCallbackActionMessage = ReturningAIWidgetActionMessage<WidgetHostCallbackPayload, ReturningAIWidgetType, 'widget:host-callback'>;
+export type ReturningAIWidgetHostCallbackActionMessage = ReturningAIStoreHostCallbackActionMessage | ReturningAIGenericHostCallbackActionMessage;
 export interface ReturningAIWidgetActionResultMessage {
     type: 'RETURNINGAI_WIDGET_ACTION_RESULT';
     requestId: string;
-    action: 'store:host-callback';
+    action: 'store:host-callback' | 'widget:host-callback';
     ok: boolean;
     status: 'success' | 'failed';
     value?: StoreCallbackFieldOptionsResult;
@@ -101,7 +137,7 @@ export interface WidgetConfig {
      * Set to the same value as communityId by readConfig().
      */
     widgetId: string;
-    widgetType: 'store' | 'channel' | 'milestone' | 'social' | 'currency-view' | 'referral-conditions' | 'custom';
+    widgetType: ReturningAIWidgetType;
     theme: 'light' | 'dark';
     themeExplicit: boolean;
     container: string;
@@ -173,12 +209,30 @@ export interface WidgetState {
             };
         };
     } | null;
+    loadingSettings: {
+        backgroundColor?: string;
+        backgroundColors?: {
+            light?: string;
+            dark?: string;
+        };
+        loadingText?: {
+            enabled: boolean;
+            text: string;
+            fontFamily: string;
+            fontSizePx: number;
+            bold: boolean;
+            italic: boolean;
+            underline: boolean;
+            color: string;
+        };
+    } | null;
     themePalette: {
         light?: Record<string, string>;
         dark?: Record<string, string>;
     } | null;
     font: string | null;
     defaultColorSchema: 'light' | 'dark' | null;
+    widgetData: Record<string, unknown> | null;
 }
 export interface TokenData {
     accessToken: string;
@@ -186,4 +240,5 @@ export interface TokenData {
     tokenFamily?: string;
     accessTokenTTL: number;
     refreshTokenTTL: number;
+    widgetData?: Record<string, unknown>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@returningai/widget-sdk",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "Shadow DOM isolated widget SDK for ReturningAI",
   "main": "dist/rai-widget.iife.js",
   "module": "dist/rai-widget.js",
@@ -18,7 +18,6 @@
     "README.md"
   ],
   "scripts": {
-    "dev": "vite",
     "build": "vite build",
     "build:min": "vite build --mode production",
     "build:banner": "vite build --config vite.banner.config.ts",
@@ -26,10 +25,11 @@
     "build:all": "npm run build && npm run build:banner",
     "build:all:min": "npm run build:min && npm run build:banner:min",
     "types": "tsc --emitDeclarationOnly --outDir dist/types && cp src/jsx.d.ts dist/types/jsx.d.ts",
-    "test": "npm run test:host-callback && npm run test:bundle-readiness && npm run test:bundle-runtime-cache && npm run test:jsx-types",
+    "test": "npm run test:host-callback && npm run test:bundle-readiness && npm run test:bundle-runtime-cache && npm run test:auth-bootstrap && npm run test:jsx-types",
     "test:host-callback": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/postmessage-host-callback.test.js",
     "test:bundle-readiness": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/bundle-readiness.test.js",
     "test:bundle-runtime-cache": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/bundle-runtime-cache.test.js",
+    "test:auth-bootstrap": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/auth-bootstrap.test.js",
     "test:jsx-types": "tsc --noEmit --strict --lib ES2020,DOM --skipLibCheck false src/jsx.d.ts",
     "coverage:repowise": "rm -rf coverage && npm run coverage:host-callback && npm run coverage:bundle-readiness && npm run test:jsx-types",
     "coverage:host-callback": "rm -rf test/.tmp && tsc -p test/tsconfig.json && c8 --reporter=lcov --reports-dir=coverage/host-callback --exclude-after-remap --exclude='**/*.test.ts' node test/.tmp/test/postmessage-host-callback.test.js && node scripts/name-lcov-test.mjs coverage/host-callback/lcov.info test/postmessage-host-callback.test.ts",
@@ -43,7 +43,7 @@
     "vite": "^5.1.0"
   },
   "dependencies": {
-    "dompurify": "^3.4.9",
+    "dompurify": "^3.4.12",
     "lottie-web": "^5.13.0"
   }
 }