@returningai/widget-sdk 1.6.2 → 1.7.1

package/dist/types/BaseWidget.d.ts

@@ -1,4 +1,5 @@
-import type { ReturningAIWidgetCallback, WidgetConfig } from "./types";
+import type { ReturningAIStoreCallbackFieldOptionsCallback, ReturningAIStorePurchaseSuccessCallback, ReturningAIWidgetCallback, WidgetConfig } from "./types";
+import { STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME, STORE_PURCHASE_SUCCESS_CALLBACK_NAME } from "./types";
 export declare function readConfig(el: Element, existingId?: string): WidgetConfig;
 export declare abstract class BaseWidget extends HTMLElement {
     static get observedAttributes(): string[];
@@ -19,6 +20,8 @@ export declare abstract class BaseWidget extends HTMLElement {
     private callbackRegistry;
     private bannerNode;
     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(callbackName: string, callback: ReturningAIWidgetCallback): void;
     lockCallbacks(): void;
     protected abstract buildWidgetUrl(config: WidgetConfig): string;
@@ -52,15 +55,13 @@ export declare abstract class BaseWidget extends HTMLElement {
     private renderShell;
     /**
      * Loads the community loading animation + theme palette from cache or API
-     * and renders the animation above the "Loading ..." text. The text is
-     * already painted by renderShell so this method only ADDS the animation;
-     * users see two states at most: text-only → text + animation.
+     * and renders the configured animation above the loading text.
      *
      * Stale-while-revalidate:
      *   - Cache hit  → apply palette & render animation synchronously, fire
      *                  background refresh.
-     *   - Cache miss → text remains visible; await network; apply palette
-     *                  + render animation when response arrives.
+     *   - Cache miss → retain the initial shell; await network; apply palette +
+     *                  render the resolved animation or fallback.
      */
     private fetchAndRenderLoader;
     /**
@@ -75,22 +76,12 @@ export declare abstract class BaseWidget extends HTMLElement {
     private createPresetLoader;
     private hideLoader;
     /**
-     * Bundle mode: keep the SDK loader visible until React has actually
-     * painted into `container`, eliminating the brief bg-color gap that
-     * happens when the loader is removed before the React app's first frame.
-     *
-     * Strategy:
-     *   1. MutationObserver fires when React commits any DOM mutation into
-     *      the container — synchronous inside mount(), but the callback runs
-     *      as a microtask, so it observes the first child addition.
-     *   2. requestAnimationFrame waits one paint cycle so the React content
-     *      is actually visible before the SDK loader fades out.
-     *   3. 2s fallback covers silent React mount errors so the loader doesn't
-     *      hang forever.
-     *
-     * Calls hideLoader() (with its 300ms fade-out) so the transition is smooth.
+     * Resolve after a legacy bundle's first rendered child has reached a paint.
+     * This remains the fallback for bundles that do not expose a deep-ready
+     * handle from mount(). It intentionally does not hide the loader itself so
+     * a stronger nested-MFE readiness signal can take ownership of the handoff.
      */
-    private deferLoaderRemovalUntilReactPaints;
+    private waitForFirstBundlePaint;
     private showError;
     private renderCustomError;
     private resolveBannerApiUrl;

package/dist/types/core/bundle-readiness.d.ts

@@ -0,0 +1,15 @@
+export declare const BUNDLE_READY_TIMEOUT_MS = 30000;
+export interface BundleMountReadyHandle {
+    ready: PromiseLike<void>;
+}
+export type BundleMountReadiness = "deep-ready" | "first-paint";
+/**
+ * Wait for the strongest readiness signal a bundle provides.
+ *
+ * Split-bundle loaders may return a promise merely because they dynamically
+ * import their app. That promise is not proof that the nested micro-frontend
+ * has rendered. A bundle opts into deep readiness by resolving its mount call
+ * to an object with a `ready` promise. Legacy bundles keep the first-paint
+ * behavior unchanged.
+ */
+export declare function waitForBundleMountReadiness(mountResult: unknown, firstPaint: PromiseLike<void>, timeoutMs?: number): Promise<BundleMountReadiness>;

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

@@ -0,0 +1,20 @@
+export interface WidgetBundleRuntime {
+    mount(container: HTMLElement, config: unknown): unknown;
+}
+interface BundleRuntimeLoaderOptions {
+    loadScript: (url: string) => Promise<void>;
+    readGlobal: (globalName: string) => unknown;
+    baseUrl: () => string;
+}
+export declare function normalizeBundleUrl(url: string, baseUrl: string): string;
+/**
+ * Cache widget runtimes by both their window global and normalized bundle URL.
+ *
+ * Different custom-widget bundles intentionally reuse the same global name, so
+ * the current value on window is not enough to identify the requested runtime.
+ * Capturing the runtime immediately after its script loads also lets A -> B -> A
+ * reuse A without re-evaluating its IIFE.
+ */
+export declare function createBundleRuntimeLoader({ loadScript, readGlobal, baseUrl, }: BundleRuntimeLoaderOptions): (globalName: string, bundleUrl: string) => Promise<WidgetBundleRuntime>;
+export declare function getOrLoadBundleRuntime(globalName: string, bundleUrl: string): Promise<WidgetBundleRuntime>;
+export {};

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

@@ -0,0 +1,3 @@
+import type { ReturningAIWidgetCallbacks, StoreCallbackFieldOptionsResult, StoreHostCallbackPayload } from '../types';
+export declare function isSupportedStoreHostCallback(callbackName: string, payload: StoreHostCallbackPayload | null | undefined): boolean;
+export declare function invokeStoreHostCallback(callbacks: ReturningAIWidgetCallbacks, callbackName: string, payload: StoreHostCallbackPayload): Promise<StoreCallbackFieldOptionsResult | undefined>;

package/dist/types/index.d.ts

@@ -18,6 +18,6 @@ declare global {
     }
 }
 export { StoreWidget, ChannelWidget, MilestoneWidget, SocialWidget, CurrencyWidget, ReferralWidget, CustomWidget };
-export type { ReturningAIStoreCallbackFieldOptionsCallback, ReturningAIWidgetCallback, ReturningAIWidgetCallbackRegistration, ReturningAIWidgetActionMessage, ReturningAIWidgetActionResultMessage, ReturningAIWidgetCallbacks, StoreCallbackFieldOptionsContext, StoreCallbackFieldOptionsField, StoreCallbackFieldOptionsFieldType, StoreCallbackFieldOptionsPayload, StoreCallbackFieldOptionsResult, } from './types';
-export { STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME, STORE_CALLBACK_FIELD_OPTIONS_SCOPE, STORE_CALLBACK_FIELD_OPTIONS_TIMEOUT_MS, } from './types';
+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 {} from './jsx';

package/dist/types/types.d.ts

@@ -1,6 +1,8 @@
 export declare const STORE_CALLBACK_FIELD_OPTIONS_SCOPE: "store.callback_field_options";
 export declare const STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME: "callbackFieldOptions";
 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 type StoreCallbackFieldOptionsFieldType = 'single-select';
 export interface StoreCallbackFieldOptionsField {
     id: string;
@@ -21,18 +23,51 @@ export interface StoreCallbackFieldOptionsResult {
     fieldOptions: Record<string, string[]>;
     signature?: string;
 }
+export interface StorePurchaseSuccessPayload {
+    scope: typeof STORE_PURCHASE_SUCCESS_SCOPE;
+    callbackName: typeof STORE_PURCHASE_SUCCESS_CALLBACK_NAME;
+    context: {
+        event: 'purchased_store_item';
+        orderId: string;
+        purchaseHistoryId: string;
+        server: {
+            id: string;
+            name?: string | null;
+        };
+        product: {
+            id: string;
+            name?: string | null;
+            cost: number;
+        };
+        customer: {
+            customIdentifier: string | null;
+        };
+        coins: {
+            beforePurchase: number;
+            cost: number;
+            afterPurchase: number;
+        };
+        userInformation?: Record<string, unknown>;
+        customRedemptionOption?: Record<string, unknown> | unknown[];
+        purchasedAt: string;
+    };
+}
+export type StoreHostCallbackPayload = StoreCallbackFieldOptionsPayload | StorePurchaseSuccessPayload;
 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;
     [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(callbackName: string, callback: ReturningAIWidgetCallback): void;
     lockCallbacks(): void;
 }
-export interface ReturningAIWidgetActionMessage {
+export interface ReturningAIWidgetActionMessage<TPayload extends StoreHostCallbackPayload = StoreCallbackFieldOptionsPayload> {
     type: 'RETURNINGAI_WIDGET_ACTION';
     requestId: string;
     widgetType: 'store';
@@ -41,8 +76,9 @@ export interface ReturningAIWidgetActionMessage {
     widgetId?: string;
     callbackName: string;
     timeoutMs?: number;
-    payload: StoreCallbackFieldOptionsPayload;
+    payload: TPayload;
 }
+export type ReturningAIStoreHostCallbackActionMessage = ReturningAIWidgetActionMessage<StoreHostCallbackPayload>;
 export interface ReturningAIWidgetActionResultMessage {
     type: 'RETURNINGAI_WIDGET_ACTION_RESULT';
     requestId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@returningai/widget-sdk",
-  "version": "1.6.2",
+  "version": "1.7.1",
   "description": "Shadow DOM isolated widget SDK for ReturningAI",
   "main": "dist/rai-widget.iife.js",
   "module": "dist/rai-widget.js",
@@ -26,12 +26,18 @@
     "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:jsx-types",
+    "test": "npm run test:host-callback && npm run test:bundle-readiness && npm run test:bundle-runtime-cache && 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: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",
+    "coverage:bundle-readiness": "rm -rf test/.tmp && tsc -p test/tsconfig.json && c8 --reporter=lcov --reports-dir=coverage/bundle-readiness --exclude-after-remap --exclude='**/*.test.ts' node test/.tmp/test/bundle-readiness.test.js && node scripts/name-lcov-test.mjs coverage/bundle-readiness/lcov.info test/bundle-readiness.test.ts",
     "prepublishOnly": "npm run build:all:min && npm run types"
   },
   "devDependencies": {
+    "c8": "^11.0.0",
     "terser": "^5.46.0",
     "typescript": "^5.3.3",
     "vite": "^5.1.0"