@returningai/widget-sdk 1.8.4 → 1.8.6

package/dist/types/BaseWidget.d.ts

@@ -22,7 +22,9 @@ export declare abstract class BaseWidget extends HTMLElement {
     private bannerNode;
     private releaseAutoThemeDisableLease?;
     private bundleUnmount?;
+    private cancelBundleForegroundRecovery?;
     private authSession?;
+    private authRenewalRecovery;
     constructor();
     registerCallback<K extends keyof ReturningAIWidgetCallbackMap>(callbackName: K, callback: ReturningAIWidgetCallbackMap[K]): void;
     registerCallback(callbackName: string, callback: ReturningAIWidgetCallback): void;
@@ -110,17 +112,12 @@ export declare abstract class BaseWidget extends HTMLElement {
     private prepareBundleRuntimeEnvironment;
     private mountWidget;
     private scheduleRefresh;
+    private performScheduledRefresh;
     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.
+     * A background refresh reached a confirmed permanent authentication failure
+     * after exhausting its safe recovery paths. Transient transport, throttling,
+     * and server failures are retained by authRenewalRecovery instead.
      */
     private handleSessionExpired;
     private logoutAndClear;

package/dist/types/core/auth-renewal-recovery.d.ts

@@ -0,0 +1,19 @@
+import type { WidgetState } from "../types";
+export interface AuthRenewalRecoveryEnvironment {
+    isHidden: () => boolean;
+    setTimeout: (callback: () => void, delayMs: number) => unknown;
+    clearTimeout: (timerId: unknown) => void;
+    addVisibilityChangeListener: (listener: () => void) => void;
+    removeVisibilityChangeListener: (listener: () => void) => void;
+    addPageShowListener: (listener: () => void) => void;
+    removePageShowListener: (listener: () => void) => void;
+    addOnlineListener: (listener: () => void) => void;
+    removeOnlineListener: (listener: () => void) => void;
+}
+export interface AuthRenewalRecoveryController {
+    schedule(): void;
+    succeeded(): void;
+    cancel(): void;
+}
+export declare function isPermanentAuthFailure(error: WidgetState["lastAuthError"]): boolean;
+export declare function createAuthRenewalRecoveryController(retry: () => Promise<void> | void, environment?: AuthRenewalRecoveryEnvironment): AuthRenewalRecoveryController;

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

@@ -1,4 +1,5 @@
 import type { WidgetConfig, WidgetState } from '../types';
+export declare function calculateRefreshDelay(accessTokenExpiry: number, now?: number): number;
 export declare function authenticateServerless(config: WidgetConfig, state: WidgetState, onRefreshScheduled?: () => void): Promise<boolean>;
 export declare function authenticateViaProxy(config: WidgetConfig, state: WidgetState, onRefreshScheduled?: () => void): Promise<boolean>;
 export declare function refreshAccessToken(config: WidgetConfig, state: WidgetState, onRefreshScheduled?: () => void, sendToken?: () => void): Promise<boolean>;

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

@@ -6,7 +6,24 @@ export interface BundleMountUnmountHandle {
     unmount: () => void;
 }
 export type BundleMountReadiness = "deep-ready" | "first-paint";
-export declare function resolveBundleMountResult(mountResult: unknown, timeoutMs?: number): Promise<unknown>;
+export type BundleReadinessPhase = "mount" | "deep-ready";
+export interface BundleReadinessEnvironment {
+    isHidden: () => boolean;
+    now: () => number;
+    setTimeout: (callback: () => void, delayMs: number) => unknown;
+    clearTimeout: (timerId: unknown) => void;
+    addVisibilityChangeListener: (listener: () => void) => void;
+    removeVisibilityChangeListener: (listener: () => void) => void;
+    addPageShowListener: (listener: () => void) => void;
+    removePageShowListener: (listener: () => void) => void;
+}
+export declare class BundleReadinessTimeoutError extends Error {
+    readonly phase: BundleReadinessPhase;
+    constructor(phase: BundleReadinessPhase, message: string);
+}
+export declare function isBundleReadinessTimeoutError(error: unknown): error is BundleReadinessTimeoutError;
+export declare function scheduleForegroundRecovery(recover: () => void, environment?: BundleReadinessEnvironment): () => void;
+export declare function resolveBundleMountResult(mountResult: unknown, timeoutMs?: number, environment?: BundleReadinessEnvironment): Promise<unknown>;
 export declare function createBundleMountCleanup(mountResult: unknown): (() => void) | undefined;
 /**
  * Wait for the strongest readiness signal a bundle provides.
@@ -17,4 +34,4 @@ export declare function createBundleMountCleanup(mountResult: unknown): (() => v
  * 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>;
+export declare function waitForBundleMountReadiness(mountResult: unknown, firstPaint: PromiseLike<void>, timeoutMs?: number, environment?: BundleReadinessEnvironment): Promise<BundleMountReadiness>;

package/dist/types/core/widget-error-presentation.d.ts

@@ -0,0 +1,15 @@
+import type { WidgetState } from "../types";
+export type WidgetFailureKind = "authentication" | "bundle";
+export interface WidgetErrorPresentationInput {
+    failureKind: WidgetFailureKind;
+    customMessage?: string | null;
+    lastAuthError: WidgetState["lastAuthError"];
+}
+export interface WidgetErrorPresentation {
+    useCustomMessage: boolean;
+    displayMessage: string;
+    emittedMessage: string;
+    hint?: string;
+    status?: number;
+}
+export declare function selectWidgetErrorPresentation({ failureKind, customMessage, lastAuthError, }: WidgetErrorPresentationInput): WidgetErrorPresentation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@returningai/widget-sdk",
-  "version": "1.8.4",
+  "version": "1.8.6",
   "description": "Shadow DOM isolated widget SDK for ReturningAI",
   "main": "dist/rai-widget.iife.js",
   "module": "dist/rai-widget.js",
@@ -25,7 +25,7 @@
     "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:auth-error-reporting && npm run test:auth-refresh-state && npm run test:auth-session-coordinator && npm run test:startup-performance && 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:auth-renewal-recovery && npm run test:auth-session-coordinator && npm run test:startup-performance && npm run test:widget-error-presentation && 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",
@@ -33,8 +33,10 @@
     "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:auth-renewal-recovery": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/auth-renewal-recovery.test.js",
     "test:auth-session-coordinator": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/auth-session-coordinator.test.js",
     "test:startup-performance": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/startup-performance.test.js",
+    "test:widget-error-presentation": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/widget-error-presentation.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",