@returningai/widget-sdk 1.4.2 → 1.5.0

package/dist/rai-widget.js

@@ -10697,6 +10697,9 @@ function clearState(state) {
     state.syncTimer = null;
   }
 }
+const STORE_CALLBACK_FIELD_OPTIONS_SCOPE = "store.callback_field_options";
+const STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME = "callbackFieldOptions";
+const STORE_CALLBACK_FIELD_OPTIONS_TIMEOUT_MS = 15e3;
 function debounce(fn, wait) {
   let timer = null;
   return {
@@ -10733,13 +10736,13 @@ function sendTokenToWidget(config, state, iframe) {
   } catch {
   }
 }
-function setupMessageListener(config, state, _shadow, iframe, onRefreshScheduled, onLogout, hideLoader, emit) {
+function setupMessageListener(config, state, _shadow, iframe, onRefreshScheduled, onLogout, hideLoader, emit, getCallbacks) {
   const heightSetter = debounce((h) => {
     iframe.style.height = `${h}px`;
     emit == null ? void 0 : emit("rai-height-change", { height: h });
   }, config.heightDebounce ?? 100);
   const handler = async (event) => {
-    var _a;
+    var _a, _b;
     if (event.origin !== config.widgetDomain) return;
     if (!event.data || typeof event.data.type !== "string") return;
     const { type, containerId, widgetId, payload } = event.data;
@@ -10785,6 +10788,55 @@ function setupMessageListener(config, state, _shadow, iframe, onRefreshScheduled
         if (onLogout) await onLogout();
         break;
       }
+      case "RETURNINGAI_WIDGET_ACTION": {
+        if (event.source !== iframe.contentWindow) break;
+        const message = event.data;
+        if (config.widgetType !== "store" && config.widgetType !== "custom") break;
+        if (message.widgetType !== "store") break;
+        if (message.action !== "store:host-callback") break;
+        if (message.callbackName !== STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME) break;
+        if (((_b = message.payload) == null ? void 0 : _b.scope) !== STORE_CALLBACK_FIELD_OPTIONS_SCOPE) break;
+        if (message.widgetId !== void 0 && message.widgetId !== config.widgetId) break;
+        if (message.containerId !== void 0 && message.containerId !== config.container) break;
+        const respond = (result) => {
+          var _a2;
+          (_a2 = iframe.contentWindow) == null ? void 0 : _a2.postMessage(result, config.widgetDomain);
+        };
+        const callbacks = (getCallbacks == null ? void 0 : getCallbacks()) ?? {};
+        const callback = callbacks[message.callbackName];
+        if (!callback) {
+          respond({
+            type: "RETURNINGAI_WIDGET_ACTION_RESULT",
+            requestId: message.requestId,
+            action: "store:host-callback",
+            ok: false,
+            status: "failed",
+            error: { message: "Host callback is not registered" }
+          });
+          break;
+        }
+        try {
+          const value = await callback(message.payload);
+          respond({
+            type: "RETURNINGAI_WIDGET_ACTION_RESULT",
+            requestId: message.requestId,
+            action: "store:host-callback",
+            ok: true,
+            status: "success",
+            value
+          });
+        } catch {
+          respond({
+            type: "RETURNINGAI_WIDGET_ACTION_RESULT",
+            requestId: message.requestId,
+            action: "store:host-callback",
+            ok: false,
+            status: "failed",
+            error: { message: "Host callback failed" }
+          });
+        }
+        break;
+      }
     }
   };
   window.addEventListener("message", handler);
@@ -10793,6 +10845,45 @@ function setupMessageListener(config, state, _shadow, iframe, onRefreshScheduled
     heightSetter.cancel();
   };
 }
+function assertCallbackName(callbackName) {
+  if (!callbackName || typeof callbackName !== "string") {
+    throw new TypeError("ReturningAI callback name must be a non-empty string");
+  }
+}
+function assertCallback(callback) {
+  if (typeof callback !== "function") {
+    throw new TypeError("ReturningAI callback must be a function");
+  }
+}
+class WidgetCallbackRegistry {
+  constructor() {
+    __publicField(this, "registeredCallbacks", {});
+    __publicField(this, "locked", false);
+  }
+  get isLocked() {
+    return this.locked;
+  }
+  registerCallback(callbackName, callback) {
+    if (this.locked) {
+      return;
+    }
+    assertCallbackName(callbackName);
+    assertCallback(callback);
+    this.registeredCallbacks = {
+      ...this.registeredCallbacks,
+      [callbackName]: callback
+    };
+  }
+  lock() {
+    if (this.locked) {
+      return;
+    }
+    this.locked = true;
+  }
+  read() {
+    return { ...this.registeredCallbacks };
+  }
+}
 const widgetCSS = ':host{display:block;position:relative;width:100%;height:100%}.rai-loader{position:absolute;top:0;left:0;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:.75rem;width:100%;height:100%;background:var(--background-5, var(--rai-loader-bg, #ffffff));border-radius:8px;z-index:10;transition:opacity .3s ease-out;font-family:var(--rai-loader-font, "Roboto", system-ui, -apple-system, sans-serif)}.rai-loader.fade-out{opacity:0;pointer-events:none}.rai-loader-text{margin:.5rem 0 0;font-size:1.125rem;line-height:1.75rem;font-weight:400;letter-spacing:normal;color:var(--accent-1, var(--rai-accent, #000000));text-align:center}@media (min-width: 768px){.rai-loader-text{font-size:1.5rem;line-height:2rem}}.rai-error{display:none;position:absolute;top:0;left:0;width:100%;height:100%;align-items:center;justify-content:center;flex-direction:column;gap:12px;background:var(--rai-error-bg, #1a1a1a);border-radius:8px;padding:24px;box-sizing:border-box;text-align:center;color:var(--rai-error-text, #9ca3af);font-family:system-ui,-apple-system,sans-serif;z-index:10}.rai-error.visible{display:flex}iframe{display:block;border:none;opacity:0;transition:opacity .3s ease-in}iframe.loaded{opacity:1}.rai-lottie-loader{width:100px;height:100px}.rai-lottie-loader svg{width:100%!important;height:100%!important}.rai-lottie-spinner{width:32px;height:32px;margin:34px auto;border:3px solid var(--rai-text4, #6b7280);border-top-color:var(--rai-accent, #000000);border-radius:50%;animation:rai-spin .7s linear infinite}@keyframes rai-spin{to{transform:rotate(360deg)}}.rai-sdk-loader{position:relative;width:75px;height:100px}.rai-sdk-loader__bar{position:absolute;bottom:0;width:10px;height:50%;background:var(--rai-accent, #000000);transform-origin:center bottom;box-shadow:1px 1px #0003}.rai-sdk-loader__bar:nth-child(1){left:0;transform:scaleY(.2);animation:rai-sdk-barUp1 4s infinite}.rai-sdk-loader__bar:nth-child(2){left:15px;transform:scaleY(.4);animation:rai-sdk-barUp2 4s infinite}.rai-sdk-loader__bar:nth-child(3){left:30px;transform:scaleY(.6);animation:rai-sdk-barUp3 4s infinite}.rai-sdk-loader__bar:nth-child(4){left:45px;transform:scaleY(.8);animation:rai-sdk-barUp4 4s infinite}.rai-sdk-loader__bar:nth-child(5){left:60px;transform:scale(1);animation:rai-sdk-barUp5 4s infinite}.rai-sdk-loader__ball{position:absolute;bottom:10px;left:0;width:10px;height:10px;background:var(--rai-accent, #000000);border-radius:50%;animation:rai-sdk-ball 4s infinite}@keyframes rai-sdk-ball{0%{transform:translate(0)}5%{transform:translate(8px,-14px)}10%{transform:translate(15px,-10px)}17%{transform:translate(23px,-24px)}20%{transform:translate(30px,-20px)}27%{transform:translate(38px,-34px)}30%{transform:translate(45px,-30px)}37%{transform:translate(53px,-44px)}40%{transform:translate(60px,-40px)}50%{transform:translate(60px)}57%{transform:translate(53px,-14px)}60%{transform:translate(45px,-10px)}67%{transform:translate(37px,-24px)}70%{transform:translate(30px,-20px)}77%{transform:translate(22px,-34px)}80%{transform:translate(15px,-30px)}87%{transform:translate(7px,-44px)}90%{transform:translateY(-40px)}to{transform:translate(0)}}@keyframes rai-sdk-barUp1{0%{transform:scaleY(.2)}40%{transform:scaleY(.2)}50%{transform:scale(1)}90%{transform:scale(1)}to{transform:scaleY(.2)}}@keyframes rai-sdk-barUp2{0%{transform:scaleY(.4)}40%{transform:scaleY(.4)}50%{transform:scaleY(.8)}90%{transform:scaleY(.8)}to{transform:scaleY(.4)}}@keyframes rai-sdk-barUp3{0%{transform:scaleY(.6)}to{transform:scaleY(.6)}}@keyframes rai-sdk-barUp4{0%{transform:scaleY(.8)}40%{transform:scaleY(.8)}50%{transform:scaleY(.4)}90%{transform:scaleY(.4)}to{transform:scaleY(.8)}}@keyframes rai-sdk-barUp5{0%{transform:scale(1)}40%{transform:scale(1)}50%{transform:scaleY(.2)}90%{transform:scaleY(.2)}to{transform:scale(1)}}#loading-square{width:75px;aspect-ratio:1;display:flex;color:var(--rai-accent, #000000);background:linear-gradient(currentColor 0 0) right / 51% 100%,linear-gradient(currentColor 0 0) bottom / 100% 51%;background-repeat:no-repeat;animation:l16-0 2s infinite linear .25s}#loading-square>div{width:50%;height:50%;background:currentColor;animation:l16-1 .5s infinite linear}@keyframes l16-0{0%,12.49%{transform:rotate(0)}12.5%,37.49%{transform:rotate(90deg)}37.5%,62.49%{transform:rotate(180deg)}62.5%,87.49%{transform:rotate(270deg)}87.5%,to{transform:rotate(360deg)}}@keyframes l16-1{0%{transform:perspective(80px) rotate3d(-1,-1,0,0)}80%,to{transform:perspective(80px) rotate3d(-1,-1,0,-180deg)}}#loading-circle{width:75px;aspect-ratio:1;display:grid;grid:50%/50%;color:var(--rai-accent, #000000);border-radius:50%;--_g: no-repeat linear-gradient(currentColor 0 0);background:var(--_g),var(--_g),var(--_g);background-size:50.1% 50.1%;animation:l9-0 1.5s infinite steps(1) alternate,l9-0-0 3s infinite steps(1) alternate}#loading-circle>div{background:var(--rai-text4, #6b7280);border-top-left-radius:100px;transform:perspective(150px) rotateY(0) rotateX(0);transform-origin:bottom right;animation:l9-1 1.5s infinite linear alternate}@keyframes l9-0{0%{background-position:0 100%,100% 100%,100% 0}33%{background-position:100% 100%,100% 100%,100% 0}66%{background-position:100% 0,100% 0,100% 0}}@keyframes l9-0-0{0%{transform:scaleX(1) rotate(0)}50%{transform:scaleX(-1) rotate(-90deg)}}@keyframes l9-1{16.5%{transform:perspective(150px) rotateX(-90deg) rotateY(0) rotateX(0);filter:grayscale(.8)}33%{transform:perspective(150px) rotateX(-180deg) rotateY(0) rotateX(0)}66%{transform:perspective(150px) rotateX(-180deg) rotateY(-180deg) rotateX(0)}to{transform:perspective(150px) rotateX(-180deg) rotateY(-180deg) rotateX(-180deg);filter:grayscale(.8)}}.rai-custom-error{position:absolute;top:0;left:0;width:100%;height:100%;z-index:10}.tiptap strong.tw-font-bold,.tiptap b.tw-font-bold{font-weight:700}.tiptap em.tw-font-italic,.tiptap i.tw-font-italic{font-style:italic}.tiptap a.tiptap-rich-text-link{color:#3b82f6;text-decoration:underline;position:relative;display:inline-block;width:fit-content}.tiptap a.tiptap-rich-text-link:hover{color:#3b82f6cc;text-decoration:none}.tiptap a.tiptap-rich-text-link:not([title=""]):before{content:attr(title);position:absolute;top:-2rem;left:50%;transform:translate(-50%);white-space:nowrap;border-radius:.25rem;background-color:#000;padding:.25rem .5rem;color:#fff;opacity:0;transition:opacity .2s;pointer-events:none}.tiptap a.tiptap-rich-text-link:not([title=""]):hover:before{opacity:1}.tiptap p[style*="text-align: left"]{text-align:left}.tiptap p[style*="text-align: center"]{text-align:center}.tiptap p[style*="text-align: right"]{text-align:right}.tiptap p[style*="text-align: justify"]{text-align:justify}.tiptap u{text-decoration:underline}.tiptap.ProseMirror{background-color:transparent;height:fit-content!important;word-wrap:break-word;white-space:pre-wrap;white-space:break-spaces;-webkit-font-variant-ligatures:none;font-variant-ligatures:none;font-feature-settings:"liga" 0;padding:0;width:100%;overflow-y:auto}.tiptap{line-height:1.6;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif}.tiptap p{margin:.5em 0}.tiptap p:first-child{margin-top:0}.tiptap p:last-child{margin-bottom:0}.tiptap img{max-width:100%;height:auto;display:block}.tiptap p[style*="text-align: left"] img{margin-left:0;margin-right:auto}.tiptap p[style*="text-align: center"] img{margin-left:auto;margin-right:auto}.tiptap p[style*="text-align: right"] img{margin-left:auto;margin-right:0}.rai-retry-btn{padding:8px 20px;border:none;border-radius:6px;background:var(--rai-accent, #000000);color:var(--rai-error-bg, #ffffff);font-size:14px;font-family:system-ui,-apple-system,sans-serif;cursor:pointer}.rai-retry-btn:hover{opacity:.85}';
 const DEFINED_ATTRS = /* @__PURE__ */ new Set([
   "community-id",
@@ -11104,11 +11195,18 @@ class BaseWidget extends HTMLElement {
     __publicField(this, "hasAttemptedInit", false);
     __publicField(this, "initGeneration", 0);
     __publicField(this, "lottieInstances", []);
+    __publicField(this, "callbackRegistry", new WidgetCallbackRegistry());
     this.shadow = this.attachShadow({ mode: "closed" });
   }
   static get observedAttributes() {
     return ["embed-token", "data-embed-token"];
   }
+  registerCallback(callbackName, callback) {
+    this.callbackRegistry.registerCallback(callbackName, callback);
+  }
+  lockCallbacks() {
+    this.callbackRegistry.lock();
+  }
   connectedCallback() {
     this.config = readConfig(this, void 0);
     this.identitySignature = identitySignatureForConfig(this.config);
@@ -11195,6 +11293,13 @@ class BaseWidget extends HTMLElement {
       })
     );
   }
+  /**
+   * Reads host callback registrations at call time so framework integrations
+   * can register a callback after the custom element is already mounted.
+   */
+  readRuntimeCallbacks() {
+    return this.callbackRegistry.read();
+  }
   // ── Rendering ─────────────────────────────────────────────────────────
   /**
    * Apply widget-defined CSS colors before first paint so the loader uses
@@ -11627,8 +11732,9 @@ class BaseWidget extends HTMLElement {
       () => this.scheduleRefresh(),
       () => this.logoutAndClear(),
       () => this.hideLoader(),
-      (type, detail) => this.emit(type, detail)
+      (type, detail) => this.emit(type, detail),
       // #1
+      () => this.readRuntimeCallbacks()
     );
   }
   // ── Bundle mode (no-iframe) ──────────────────────────────────────────
@@ -11698,7 +11804,15 @@ class BaseWidget extends HTMLElement {
         // post. Mirrors the iframe behavior, where `isOpenWidget` is only
         // injected by SSR for the explicit `/open-widget` route.
         isOpenWidget: !this.state.accessToken,
-        defaultColorSchema: this.config.theme === "dark" ? "dark" : "light"
+        defaultColorSchema: this.config.theme === "dark" ? "dark" : "light",
+        requestHostCallback: async (callbackName, payload) => {
+          if (this.config.widgetType !== "store" && this.config.widgetType !== "custom" || callbackName !== STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME || payload.scope !== STORE_CALLBACK_FIELD_OPTIONS_SCOPE) {
+            throw new Error("Host callback is only supported for store widgets");
+          }
+          const callback = this.readRuntimeCallbacks()[callbackName];
+          if (!callback) throw new Error("Host callback is not registered");
+          return callback(payload);
+        }
       });
       this.emit("rai-mounted");
     } catch (err) {
@@ -11886,7 +12000,7 @@ class CustomWidget extends BaseWidget {
     }
   }
 }
-console.log(`[rai-widget] v${"1.4.2"}`);
+console.log(`[rai-widget] v${"1.5.0"}`);
 class StoreWidgetCompat extends StoreWidget {
 }
 const WIDGET_REGISTRY = [
@@ -11950,7 +12064,7 @@ function exposePublicApi() {
   })();
   const widget = container == null ? void 0 : container.querySelector(ALL_WIDGET_SELECTOR);
   window.ReturningAIWidget = {
-    version: "1.4.2",
+    version: "1.5.0",
     reload: () => (widget == null ? void 0 : widget.reload()) ?? Promise.resolve(),
     logout: () => (widget == null ? void 0 : widget.logoutPublic()) ?? Promise.resolve(),
     isAuthenticated: () => (widget == null ? void 0 : widget.isAuthenticated()) ?? false,
@@ -11968,6 +12082,9 @@ export {
   CustomWidget,
   MilestoneWidget,
   ReferralWidget,
+  STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME,
+  STORE_CALLBACK_FIELD_OPTIONS_SCOPE,
+  STORE_CALLBACK_FIELD_OPTIONS_TIMEOUT_MS,
   SocialWidget,
   StoreWidget
 };

package/dist/types/BaseWidget.d.ts

@@ -1,4 +1,4 @@
-import type { WidgetConfig } from "./types";
+import type { ReturningAIWidgetCallback, WidgetConfig } from "./types";
 export declare function readConfig(el: Element, existingId?: string): WidgetConfig;
 export declare abstract class BaseWidget extends HTMLElement {
     static get observedAttributes(): string[];
@@ -16,7 +16,10 @@ export declare abstract class BaseWidget extends HTMLElement {
     private hasAttemptedInit;
     private initGeneration;
     private lottieInstances;
+    private callbackRegistry;
     constructor();
+    registerCallback(callbackName: string, callback: ReturningAIWidgetCallback): void;
+    lockCallbacks(): void;
     protected abstract buildWidgetUrl(config: WidgetConfig): string;
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -24,6 +27,11 @@ export declare abstract class BaseWidget extends HTMLElement {
     private setupIdentityAttributeObserver;
     private handleIdentityConfigChange;
     private emit;
+    /**
+     * Reads host callback registrations at call time so framework integrations
+     * can register a callback after the custom element is already mounted.
+     */
+    private readRuntimeCallbacks;
     /**
      * Apply widget-defined CSS colors before first paint so the loader uses
      * the community's actual theme — not generic light/dark — from frame 1.

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

@@ -0,0 +1,15 @@
+import type { ReturningAIWidgetCallback, ReturningAIWidgetCallbacks } from '../types';
+/**
+ * Owns callback registration for a single widget element.
+ *
+ * Callback registration is intentionally per element so pages with multiple
+ * widgets can lock each widget's callback behavior independently.
+ */
+export declare class WidgetCallbackRegistry {
+    private registeredCallbacks;
+    private locked;
+    get isLocked(): boolean;
+    registerCallback(callbackName: string, callback: ReturningAIWidgetCallback): void;
+    lock(): void;
+    read(): ReturningAIWidgetCallbacks;
+}

package/dist/types/core/postmessage.d.ts

@@ -1,3 +1,3 @@
-import type { WidgetConfig, WidgetState } from '../types';
+import type { ReturningAIWidgetCallbacks, WidgetConfig, WidgetState } from '../types';
 export declare function sendTokenToWidget(config: WidgetConfig, state: WidgetState, iframe: HTMLIFrameElement): void;
-export declare function setupMessageListener(config: WidgetConfig, state: WidgetState, _shadow: ShadowRoot, iframe: HTMLIFrameElement, onRefreshScheduled?: () => void, onLogout?: () => Promise<void>, hideLoader?: () => void, emit?: (type: string, detail?: Record<string, unknown>) => void): () => void;
+export declare function setupMessageListener(config: WidgetConfig, state: WidgetState, _shadow: ShadowRoot, iframe: HTMLIFrameElement, onRefreshScheduled?: () => void, onLogout?: () => Promise<void>, hideLoader?: () => void, emit?: (type: string, detail?: Record<string, unknown>) => void, getCallbacks?: () => ReturningAIWidgetCallbacks): () => void;

package/dist/types/index.d.ts

@@ -6,14 +6,18 @@ import { CurrencyWidget } from './CurrencyWidget';
 import { ReferralWidget } from './ReferralWidget';
 import { CustomWidget } from './CustomWidget';
 declare global {
+    interface ReturningAIWidgetGlobal {
+        version?: string;
+        reload?: () => Promise<void>;
+        logout?: () => Promise<void>;
+        isAuthenticated?: () => boolean;
+        getTokenInfo?: () => object;
+    }
     interface Window {
-        ReturningAIWidget: {
-            version: string;
-            reload: () => Promise<void>;
-            logout: () => Promise<void>;
-            isAuthenticated: () => boolean;
-            getTokenInfo: () => object;
-        };
+        ReturningAIWidget?: ReturningAIWidgetGlobal;
     }
 }
 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 {} from './jsx';

package/dist/types/jsx.d.ts

@@ -0,0 +1,55 @@
+// Shared attribute shape for all widget elements
+interface RaiWidgetAttributes {
+  'community-id': string
+  'channel-id'?: string
+  'widget-id'?: string              // deprecated — use 'community-id'
+  'data-email'?: string
+  'widget-type'?: 'store' | 'channel' | 'milestone' | 'social' | 'currency-view' | 'referral-conditions' | 'custom'
+  theme?: 'light' | 'dark'
+  width?: string
+  height?: string
+  'api-url'?: string
+  'widget-url'?: string
+  'bundle-url'?: string
+  'domain-key'?: string
+  'v2-api-url'?: string
+  'embed-token'?: string
+  'auth-url'?: string
+  'auto-refresh'?: string
+  'data-container'?: string
+  debug?: string
+  class?: string
+  style?: string
+}
+
+// ── React ──────────────────────────────────────────────────────────────────
+declare namespace React {
+  namespace JSX {
+    interface IntrinsicElements {
+      'rai-store-widget':    React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
+      'rai-channel-widget':  React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
+      'rai-milestone-widget': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
+      'rai-social-widget':   React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
+      'rai-currency-widget':  React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
+      'rai-referral-widget': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
+      'rai-custom-widget':   React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
+      'rai-widget':          React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes // deprecated
+    }
+  }
+}
+
+// ── Vue 3 (Volar / vue-tsc) ────────────────────────────────────────────────
+declare module '@vue/runtime-core' {
+  interface GlobalComponents {
+    RaiStoreWidget:    { $props: RaiWidgetAttributes }
+    RaiChannelWidget:  { $props: RaiWidgetAttributes }
+    RaiMilestoneWidget: { $props: RaiWidgetAttributes }
+    RaiSocialWidget:   { $props: RaiWidgetAttributes }
+    RaiCurrencyWidget:  { $props: RaiWidgetAttributes }
+    RaiReferralWidget: { $props: RaiWidgetAttributes }
+    RaiCustomWidget:   { $props: RaiWidgetAttributes }
+    RaiWidget:         { $props: RaiWidgetAttributes } // deprecated
+  }
+}
+
+export {}

package/dist/types/types.d.ts

@@ -1,3 +1,59 @@
+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 type StoreCallbackFieldOptionsFieldType = 'single-select';
+export interface StoreCallbackFieldOptionsField {
+    id: string;
+    name: string;
+    type: StoreCallbackFieldOptionsFieldType;
+}
+export interface StoreCallbackFieldOptionsContext {
+    productId: string;
+    productName?: string;
+    fields: StoreCallbackFieldOptionsField[];
+}
+export interface StoreCallbackFieldOptionsPayload {
+    scope: typeof STORE_CALLBACK_FIELD_OPTIONS_SCOPE;
+    callbackName: typeof STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME;
+    context: StoreCallbackFieldOptionsContext;
+}
+export interface StoreCallbackFieldOptionsResult {
+    fieldOptions: Record<string, string[]>;
+    signature?: string;
+}
+export type ReturningAIWidgetCallback<TPayload = any, TResult = any> = (payload: TPayload) => Promise<TResult> | TResult;
+export type ReturningAIStoreCallbackFieldOptionsCallback = (payload: StoreCallbackFieldOptionsPayload) => Promise<StoreCallbackFieldOptionsResult> | StoreCallbackFieldOptionsResult;
+export type ReturningAIWidgetCallbacks = {
+    'callbackFieldOptions'?: ReturningAIStoreCallbackFieldOptionsCallback;
+    [callbackName: string]: ReturningAIWidgetCallback | undefined;
+};
+export interface ReturningAIWidgetCallbackRegistration {
+    registerCallback(callbackName: typeof STORE_CALLBACK_FIELD_OPTIONS_CALLBACK_NAME, callback: ReturningAIStoreCallbackFieldOptionsCallback): void;
+    registerCallback(callbackName: string, callback: ReturningAIWidgetCallback): void;
+    lockCallbacks(): void;
+}
+export interface ReturningAIWidgetActionMessage {
+    type: 'RETURNINGAI_WIDGET_ACTION';
+    requestId: string;
+    widgetType: 'store';
+    action: 'store:host-callback';
+    containerId?: string;
+    widgetId?: string;
+    callbackName: string;
+    timeoutMs?: number;
+    payload: StoreCallbackFieldOptionsPayload;
+}
+export interface ReturningAIWidgetActionResultMessage {
+    type: 'RETURNINGAI_WIDGET_ACTION_RESULT';
+    requestId: string;
+    action: 'store:host-callback';
+    ok: boolean;
+    status: 'success' | 'failed';
+    value?: StoreCallbackFieldOptionsResult;
+    error?: {
+        message: string;
+    };
+}
 export interface WidgetConfig {
     /** The community this widget belongs to. Maps to the `community-id` HTML attribute. */
     communityId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@returningai/widget-sdk",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Shadow DOM isolated widget SDK for ReturningAI",
   "main": "dist/rai-widget.iife.js",
   "module": "dist/rai-widget.js",
@@ -21,7 +21,9 @@
     "dev": "vite",
     "build": "vite build",
     "build:min": "vite build --mode production",
-    "types": "tsc --emitDeclarationOnly --outDir dist/types",
+    "types": "tsc --emitDeclarationOnly --outDir dist/types && cp src/jsx.d.ts dist/types/jsx.d.ts",
+    "test": "npm run test:host-callback",
+    "test:host-callback": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/postmessage-host-callback.test.js",
     "prepublishOnly": "npm run build:min && npm run types"
   },
   "devDependencies": {