@returningai/widget-sdk 1.2.16 → 1.4.0

package/dist/types/BaseWidget.d.ts

@@ -1,4 +1,4 @@
-import type { WidgetConfig } from './types';
+import type { WidgetConfig } from "./types";
 export declare function readConfig(el: Element, existingId?: string): WidgetConfig;
 export declare abstract class BaseWidget extends HTMLElement {
     protected shadow: ShadowRoot;
@@ -10,27 +10,70 @@ export declare abstract class BaseWidget extends HTMLElement {
     private cleanupListener?;
     private intersectionObserver?;
     private themeObserver?;
+    private lottieInstances;
     constructor();
     protected abstract buildWidgetUrl(config: WidgetConfig): string;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private emit;
+    /**
+     * Apply widget-defined CSS colors before first paint so the loader uses
+     * the community's actual theme — not generic light/dark — from frame 1.
+     *
+     * Priority:
+     *   1. Cached themePalette (synchronous localStorage read)
+     *   2. HTML attribute hints (`bg`, `text`, `accent`)
+     *   3. Generic light/dark fallback (--rai-* vars set in connectedCallback)
+     *
+     * After the API response arrives, fetchAndRenderLoader() re-applies the
+     * fresh palette via applyPaletteFromState(). On every load except the
+     * absolute first-ever, the cached palette is already correct.
+     */
+    private applyFirstPaintColors;
+    private applyFont;
+    private applyPalette;
     private renderShell;
     /**
-     * Fetches the community's loading animation config from the error-settings
-     * API (which now also returns loadingAnimation) and renders the appropriate
-     * loader. Falls back to the default bar loader if the API fails or if no
-     * custom animation is configured.
+     * 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.
      *
-     * This runs in parallel with auth — the API call is fire-and-forget and
-     * the loader is rendered as soon as the response arrives. The result is
-     * also cached by fetchErrorSettings so init() doesn't re-fetch.
+     * 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.
      */
     private fetchAndRenderLoader;
-    private renderLottieLoader;
+    /**
+     * Append the loading animation above the text. Removes any previous
+     * animation first so this is safe to call repeatedly (e.g. after a
+     * background refresh changes the configured loader).
+     */
+    private renderLoaderAnimation;
+    private renderLottieInto;
+    private clearLottieInstances;
     private createDefaultLoader;
     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.
+     */
+    private deferLoaderRemovalUntilReactPaints;
     private showError;
     private renderCustomError;
     private init;

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

@@ -4,7 +4,15 @@ export declare function authenticateViaProxy(config: WidgetConfig, state: Widget
 export declare function refreshAccessToken(config: WidgetConfig, state: WidgetState, onRefreshScheduled?: () => void, sendToken?: () => void): Promise<boolean>;
 export declare function getValidToken(config: WidgetConfig, state: WidgetState, onRefreshScheduled?: () => void): Promise<string>;
 export declare function logout(config: WidgetConfig, state: WidgetState): Promise<void>;
-export declare function validateEmbedToken(config: WidgetConfig): Promise<boolean>;
-export declare function fetchErrorSettings(config: WidgetConfig, state: WidgetState): Promise<typeof state.errorSettings>;
+export declare function applyErrorSettingsToState(state: WidgetState, data: Record<string, unknown>): void;
+/**
+ * Fetches widget error settings + community loading animation.
+ *
+ * Stale-while-revalidate: serves from cache instantly when present (no TTL).
+ * Pass { skipCache: true } to force a network fetch (used for background refresh).
+ */
+export declare function fetchErrorSettings(config: WidgetConfig, state: WidgetState, opts?: {
+    skipCache?: boolean;
+}): Promise<typeof state.errorSettings>;
 declare function clearState(state: WidgetState): void;
 export { clearState };

package/dist/types/types.d.ts

@@ -11,6 +11,7 @@ export interface WidgetConfig {
     widgetId: string;
     widgetType: 'store' | 'channel' | 'milestone' | 'social' | 'currency-view' | 'referral-conditions' | 'custom';
     theme: 'light' | 'dark';
+    themeExplicit: boolean;
     container: string;
     width: string;
     height: string;
@@ -30,7 +31,14 @@ export interface WidgetConfig {
     bundleUrl?: string;
     embedToken?: string;
     v2ApiUrl?: string;
-    domainKey?: string;
+    domainKey: string;
+    loadingText: string;
+    firstPaintColors?: {
+        bg?: string;
+        text?: string;
+        accent?: string;
+    };
+    firstPaintFont?: string;
 }
 export interface WidgetState {
     accessToken: string | null;
@@ -49,6 +57,11 @@ export interface WidgetState {
         modalColor?: string;
         backgroundImage?: string;
     } | null;
+    lastAuthError: {
+        status: number;
+        error?: string;
+        hint?: string;
+    } | null;
     loadingAnimation: {
         type?: string;
         preset?: string;
@@ -68,6 +81,12 @@ export interface WidgetState {
             };
         };
     } | null;
+    themePalette: {
+        light?: Record<string, string>;
+        dark?: Record<string, string>;
+    } | null;
+    font: string | null;
+    defaultColorSchema: 'light' | 'dark' | null;
 }
 export interface TokenData {
     accessToken: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@returningai/widget-sdk",
-  "version": "1.2.16",
+  "version": "1.4.0",
   "description": "Shadow DOM isolated widget SDK for ReturningAI",
   "main": "dist/rai-widget.iife.js",
   "module": "dist/rai-widget.js",
@@ -26,5 +26,8 @@
     "terser": "^5.46.0",
     "typescript": "^5.3.3",
     "vite": "^5.1.0"
+  },
+  "dependencies": {
+    "lottie-web": "^5.13.0"
   }
 }