@returningai/widget-sdk 1.8.1 → 1.8.3

package/dist/types/BaseWidget.d.ts

@@ -6,6 +6,8 @@ export declare abstract class BaseWidget extends HTMLElement {
     protected config: WidgetConfig;
     private state;
     private loaderEl;
+    private loaderHeightRestore;
+    private loaderHeightObserver;
     private errorEl;
     private msgEl;
     private cleanupListener?;
@@ -16,10 +18,10 @@ export declare abstract class BaseWidget extends HTMLElement {
     private hasAttemptedInit;
     private initGeneration;
     private lottieInstances;
-    private renderedLoaderAnimationKey;
     private callbackRegistry;
     private bannerNode;
     private releaseAutoThemeDisableLease?;
+    private bundleUnmount?;
     constructor();
     registerCallback<K extends keyof ReturningAIWidgetCallbackMap>(callbackName: K, callback: ReturningAIWidgetCallbackMap[K]): void;
     registerCallback(callbackName: string, callback: ReturningAIWidgetCallback): void;
@@ -53,17 +55,14 @@ export declare abstract class BaseWidget extends HTMLElement {
     private applyFont;
     private applyPalette;
     private applyLoadingSettings;
-    private getLoadingAnimationRenderKey;
     private renderShell;
     /**
      * Loads the community loading animation + theme palette from cache or API
      * and renders the configured animation above the loading text.
      *
-     * Stale-while-revalidate:
-     *   - Cache hit  → apply palette & render animation synchronously, fire
-     *                  background refresh.
-     *   - Cache miss → retain the initial shell; await network; apply palette +
-     *                  render the resolved animation or fallback.
+     * Cached settings are applied synchronously. On a first visit, settings load
+     * alongside authentication so the generic loader stays hidden until the
+     * configured animation is known. This request never blocks widget launch.
      */
     private fetchAndRenderLoader;
     /**
@@ -77,6 +76,14 @@ export declare abstract class BaseWidget extends HTMLElement {
     private createDefaultLoader;
     private createPresetLoader;
     private hideLoader;
+    /**
+     * Keep percentage-based iframe embeds at their resolved startup height while
+     * the SDK loader is visible. The child iframe may resize during auth/data
+     * loading; without this pin the loader's 100% centering moves with the host.
+     */
+    private freezeIframeLoaderHeight;
+    private deferIframeLoaderHeightFreeze;
+    private restoreLoaderHeight;
     /**
      * 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
@@ -103,6 +110,18 @@ export declare abstract class BaseWidget extends HTMLElement {
     private mountWidget;
     private scheduleRefresh;
     private schedulePeriodicSync;
+    /**
+     * A background refresh exhausted every recovery path — /auth/refresh failed
+     * and the re-auth that follows it failed too, so `state.isAuthenticated` is
+     * now false and there is no live token.
+     *
+     * Every startup auth path already calls showError() on failure; this one is
+     * reached from a timer, so without it the widget stays mounted showing stale
+     * content while isAuthenticated() reports false to the host page — which is
+     * how a signed-in user ends up looking at content meant for signed-out users.
+     * The event gives hosts a signal to re-mint credentials instead of polling.
+     */
+    private handleSessionExpired;
     private logoutAndClear;
     reload(): Promise<void>;
     logoutPublic(): Promise<void>;

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

@@ -2,7 +2,12 @@ export declare const BUNDLE_READY_TIMEOUT_MS = 30000;
 export interface BundleMountReadyHandle {
     ready: PromiseLike<void>;
 }
+export interface BundleMountUnmountHandle {
+    unmount: () => void;
+}
 export type BundleMountReadiness = "deep-ready" | "first-paint";
+export declare function resolveBundleMountResult(mountResult: unknown, timeoutMs?: number): Promise<unknown>;
+export declare function createBundleMountCleanup(mountResult: unknown): (() => void) | undefined;
 /**
  * Wait for the strongest readiness signal a bundle provides.
  *

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

@@ -8,9 +8,22 @@ interface BundleRuntimeLoaderOptions {
 }
 interface BundleRuntimeWarmerOptions {
     preloadScript: (url: string) => Promise<void>;
+    preloadBundleAssets?: (bundleUrl: string) => Promise<void>;
     baseUrl: () => string;
 }
-export declare function createBundleRuntimeWarmer({ preloadScript, baseUrl, }: BundleRuntimeWarmerOptions): (globalName: string, bundleUrl: string) => void;
+interface BundlePreloadManifest {
+    version: 1;
+    scripts?: unknown;
+    styles?: unknown;
+}
+export interface BundlePreloadAsset {
+    url: string;
+    rel: "modulepreload" | "preload";
+    as: "script" | "style";
+}
+/** Resolve and constrain optional deep-preload assets advertised beside a bundle. */
+export declare function resolveBundlePreloadAssets(bundleUrl: string, manifest: BundlePreloadManifest): BundlePreloadAsset[];
+export declare function createBundleRuntimeWarmer({ preloadScript, preloadBundleAssets, 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.

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

@@ -0,0 +1,12 @@
+export declare const SUPPORTED_WIDGET_LANGUAGES: readonly ["en", "de", "es", "fr", "it", "pt", "pl", "da", "nl", "ru", "chs", "el", "ko", "cht", "th", "ja", "id", "vt", "ms", "hi", "fil", "ta", "tr", "ar", "mn", "sw"];
+/**
+ * Normalizes a BCP 47 language tag to the locale codes used by ReturningAI.
+ * Returns undefined when an explicit value cannot be mapped to a supported
+ * widget language.
+ */
+export declare function resolveWidgetLanguage(language?: string | null): string | undefined;
+/**
+ * Invalid language overrides are customer configuration errors, so surface
+ * them once per distinct value even when verbose SDK logging is disabled.
+ */
+export declare function warnUnsupportedWidgetLanguage(language: string): void;

package/dist/types/core/loader-height.d.ts

@@ -0,0 +1,13 @@
+export declare function parsePercentageHeight(value: string): number | null;
+export declare function resolvePercentageViewportHeight(value: string, viewportHeight: number): number;
+/**
+ * Return a responsive fallback only when restoring the original height leaves
+ * a rendered embed collapsed. Percentage embeds use vh so viewport changes do
+ * not leave them permanently pinned to their startup pixel measurement.
+ */
+export declare function resolveCollapsedRestoredHeight({ originalHeight, restoredHeight, resolvedHeight, isRendered, }: {
+    originalHeight: string;
+    restoredHeight: number;
+    resolvedHeight: number;
+    isRendered: boolean;
+}): string | null;

package/dist/types/core/startup-performance.d.ts

@@ -0,0 +1,23 @@
+import type { WidgetConfig } from "../types";
+interface PreconnectDocument {
+    head: {
+        appendChild(link: PreconnectLink): unknown;
+    };
+    createElement(tagName: "link"): PreconnectLink;
+    getElementById(id: string): unknown;
+}
+interface PreconnectLink {
+    id: string;
+    rel: string;
+    href: string;
+    crossOrigin: string;
+}
+/** Let successful auth launch immediately while preserving configured auth errors. */
+export declare function resolveStartupAuthentication(authentication: Promise<boolean>, loadErrorSettings: (options?: {
+    skipCache?: boolean;
+}) => Promise<unknown>): Promise<boolean>;
+/** Return the unique HTTP origins involved in widget startup. */
+export declare function resolveWidgetPreconnectOrigins(config: WidgetConfig, baseUrl: string): string[];
+/** Add deduplicated, anonymous preconnect hints without initiating script execution. */
+export declare function ensureWidgetPreconnects(origins: string[], targetDocument?: PreconnectDocument): void;
+export {};

package/dist/types/jsx.d.ts

@@ -15,6 +15,8 @@ interface RaiWidgetAttributes {
   'v2-api-url'?: string
   'embed-token'?: string
   'auth-url'?: string
+  language?: string
+  locale?: string
   'auto-refresh'?: string
   'data-container'?: string
   debug?: string

package/dist/types/types.d.ts

@@ -153,6 +153,12 @@ export interface WidgetConfig {
     maxRetries: number;
     retryDelay: number;
     heightDebounce: number;
+    /**
+     * Normalized, supported widget language. Explicit unsupported values are
+     * omitted so the widget falls back to the browser language.
+     */
+    language?: string;
+    /** @deprecated Use language. Kept for existing data-locale embeds. */
     locale?: string;
     customData?: Record<string, unknown>;
     authUrl?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@returningai/widget-sdk",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "description": "Shadow DOM isolated widget SDK for ReturningAI",
   "main": "dist/rai-widget.iife.js",
   "module": "dist/rai-widget.js",
@@ -25,12 +25,15 @@
     "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:bundle-token-sync && npm run test:auth-bootstrap && 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:bundle-token-sync && npm run test:auth-bootstrap && npm run test:auth-error-reporting && npm run test:auth-refresh-state && npm run test:startup-performance && 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:bundle-token-sync": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/bundle-token-sync.test.js",
     "test:auth-bootstrap": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/auth-bootstrap.test.js",
+    "test:auth-error-reporting": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/auth-error-reporting.test.js",
+    "test:auth-refresh-state": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/auth-refresh-state.test.js",
+    "test:startup-performance": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/startup-performance.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",