@returningai/widget-sdk 1.8.13 → 1.8.14

package/dist/types/BaseWidget.d.ts

@@ -15,6 +15,14 @@ export declare abstract class BaseWidget extends HTMLElement {
     private themeObserver?;
     private identityAttributeObserver?;
     private identitySignature;
+    /** The `embed-token` attribute as last read; `config.embedToken` may hold a renewed pass instead. */
+    private lastEmbedTokenAttribute;
+    /** The init generation whose widget launched; part of the silent-swap health check. */
+    private launchedInitId;
+    /** Set when the expired-pass error was shown with no `embedTokenRequest` registered. */
+    private lateEmbedTokenRegistrationReload;
+    /** An error screen is showing for the current init (any cause); clears on the next launch. */
+    private errorScreenShown;
     private hasAttemptedInit;
     private initGeneration;
     private lottieInstances;
@@ -35,6 +43,15 @@ export declare abstract class BaseWidget extends HTMLElement {
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     private setupIdentityAttributeObserver;
     private handleIdentityConfigChange;
+    private readEmbedTokenProvider;
+    /**
+     * Renewal options for auth calls started by init `initId`; the provider is
+     * read at call time. A disconnect or a newer init stops the retry. Writes
+     * from this call land only in the state object init `initId` owns.
+     */
+    private embedTokenRenewal;
+    /** Authenticated, no error state or error screen, and launched for the current init. */
+    private isHealthyForEmbedTokenSwap;
     private emit;
     /**
      * Reads host callback registrations at call time so framework integrations
@@ -106,6 +123,15 @@ export declare abstract class BaseWidget extends HTMLElement {
      * sub-type + community. Best-effort: never throws into the host page.
      */
     private mountBannerForWidget;
+    /**
+     * Starts a new init: it owns a fresh state object and its own auth-session
+     * subscription. The previous init's in-flight work keeps the retired state,
+     * so it can finish but never writes this init's state or storage. It still
+     * publishes to the session it started on; after a same-member reload that is
+     * the same shared session this init joined, which is intended (siblings and
+     * this init get the result).
+     */
+    private beginInit;
     private init;
     private isCurrentInit;
     private teardownMountedWidget;

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

@@ -1,9 +1,24 @@
 import type { WidgetConfig, WidgetState } from '../types';
+import { type EmbedTokenRenewalOptions } from './embed-token-renewal';
+export type { EmbedTokenRenewalOptions } from './embed-token-renewal';
 export declare function calculateRefreshDelay(accessTokenExpiry: number, now?: number): number;
-export declare function authenticateServerless(config: WidgetConfig, state: WidgetState, onRefreshScheduled?: () => void): Promise<boolean>;
+/**
+ * Signs in with the embed token or Public Embed identifiers.
+ *
+ * `renewal` is required so every call site declares whether the host page can
+ * supply a fresh embed token (`embedTokenRequest`). With a provider:
+ * - a pass past `exp` (or within 30 s of it) is renewed before signing in;
+ * - after the backend's expired-pass 401, the pass is renewed once and a new
+ *   sign-in attempt (new nonce and timestamp) is made, if the widget is still
+ *   current.
+ * The provider is consulted at most once per call. With a null provider this
+ * behaves as before, except that `lastAuthError` always describes the latest
+ * attempt.
+ */
+export declare function authenticateServerless(config: WidgetConfig, state: WidgetState, renewal: EmbedTokenRenewalOptions, 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>;
-export declare function getValidToken(config: WidgetConfig, state: WidgetState, onRefreshScheduled?: () => void): Promise<string>;
+export declare function refreshAccessToken(config: WidgetConfig, state: WidgetState, renewal: EmbedTokenRenewalOptions, onRefreshScheduled?: () => void, sendToken?: () => void): Promise<boolean>;
+export declare function getValidToken(config: WidgetConfig, state: WidgetState, renewal: EmbedTokenRenewalOptions, onRefreshScheduled?: () => void): Promise<string>;
 export declare function logout(config: WidgetConfig, state: WidgetState): Promise<void>;
 export declare function applyErrorSettingsToState(state: WidgetState, data: Record<string, unknown>): void;
 /**

package/dist/types/core/embed-token-renewal.d.ts

@@ -0,0 +1,116 @@
+import type { ReturningAIEmbedTokenRequestCallback, ReturningAIEmbedTokenRequestReason, ReturningAIWidgetCallbacks, WidgetConfig } from '../types';
+/**
+ * Host-page embed-token renewal (`embedTokenRequest`).
+ *
+ * Pure logic with no DOM: decoding pass claims, the acceptance rule for a
+ * renewed pass, the page-wide de-duplicated renewal registry, and the
+ * identity-change decision used when a host sets a new `embed-token`.
+ * The SDK only decodes passes; their signatures are verified by the server.
+ */
+export declare const EMBED_TOKEN_REJECTED_ERROR = "Invalid or expired embed token";
+/** A pass within this many ms of `exp` is treated as expired before sign-in. */
+export declare const EMBED_TOKEN_EXPIRY_WINDOW_MS = 30000;
+/** The host gets this long to answer before the widget keeps today's error. */
+export declare const EMBED_TOKEN_REQUEST_TIMEOUT_MS = 10000;
+/** After a failed or rejected answer, the host is not asked again for this long. */
+export declare const EMBED_TOKEN_REQUEST_COOLDOWN_MS = 30000;
+/** An accepted pass is reused until this long before its `exp`. */
+export declare const EMBED_TOKEN_CACHE_MARGIN_MS = 60000;
+export type EmbedTokenProvider = ReturningAIEmbedTokenRequestCallback;
+/**
+ * Required by every sign-in and renewal entry point in `auth.ts`, so a call
+ * site that forgets to declare its provider fails `tsc`. Pass
+ * `{ getEmbedTokenProvider: null }` where the host cannot supply one.
+ */
+export interface EmbedTokenRenewalOptions {
+    getEmbedTokenProvider: (() => EmbedTokenProvider | null) | null;
+    /** False once the widget that started the sign-in was disconnected or re-initialised. Stops the retry. */
+    isCurrent?: () => boolean;
+    /** Set by the refresh-failure path; defaults to `expired`. */
+    reason?: ReturningAIEmbedTokenRequestReason;
+}
+export interface EmbedTokenClaims {
+    accessId?: string;
+    communityId?: string;
+    userIdentifiers?: Record<string, string>;
+    exp?: number;
+}
+export interface EmbedTokenRenewalClock {
+    now: () => number;
+    setTimeout: (callback: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+}
+/** A pass's claims, decoded without verification (the server verifies). Null when undecodable. */
+export declare function decodeEmbedTokenClaims(embedToken?: string | null): EmbedTokenClaims | null;
+/**
+ * The member a pass is for: `accessId`, `communityId` and sorted
+ * `userIdentifiers`. Falls back to the raw string for an undecodable pass or a
+ * legacy pass without identifiers; an absent pass is `""`.
+ */
+export declare function embedIdentityKey(embedToken?: string | null): string;
+/**
+ * The swap signature: the pass's identity key plus the `data-*` identifiers.
+ * A same-member pass keeps the signature; a different member, access key or
+ * `data-*` identifier changes it.
+ */
+export declare function identitySignatureForConfig(config: Pick<WidgetConfig, 'embedToken' | 'userIdentifiers'>): string;
+/** True only for the backend's expired-pass refusal, the one refusal a new pass can fix. */
+export declare function isEmbedTokenRejected(error: {
+    status?: number;
+    error?: string;
+} | null | undefined): boolean;
+/** True when the pass's `exp` is past or within the pre-check window. */
+export declare function isEmbedTokenExpiring(embedToken: string | null | undefined, now?: number): boolean;
+/** Reads the host's registered provider, ignoring a non-function registration. */
+export declare function readEmbedTokenProvider(callbacks: ReturningAIWidgetCallbacks | null | undefined): EmbedTokenProvider | null;
+/**
+ * Accepts the host's answer only when it is a fresh pass for the same member:
+ * a string other than the stale pass, `exp` more than 30 s ahead, the same
+ * `communityId`, and the same `userIdentifiers` (or none, when the stale pass
+ * has none). `accessId` may differ, so an access-key rotation can recover.
+ */
+export declare function acceptRenewedEmbedToken(staleToken: string, result: unknown, now?: number): string | null;
+/**
+ * The server still refused a renewed pass the SDK had accepted (for example a
+ * host minting from the wrong environment). Forget it and do not ask the host
+ * again for that member for 30 s, as for a rejected answer.
+ */
+export declare function markRenewedEmbedTokenRefused(staleToken: string, refusedToken: string, clock?: EmbedTokenRenewalClock): void;
+/** Test-only: forget every in-flight request, cached pass and cooldown on the page. */
+export declare function resetEmbedTokenRenewalForTests(): void;
+export interface RenewEmbedTokenRequest {
+    staleToken: string;
+    reason: ReturningAIEmbedTokenRequestReason;
+    provider: EmbedTokenProvider;
+    clock?: EmbedTokenRenewalClock;
+}
+/**
+ * Asks the host page for a fresh pass for the stale pass's member.
+ *
+ * Every widget on the page shares one in-flight request per member, so seven
+ * widgets with the same stale pass make one host call. Resolves to the
+ * accepted pass, or null when the host throws, answers with anything the
+ * acceptance rule refuses, or does not answer within 10 s; a null result
+ * leaves the caller's existing error in place.
+ */
+export declare function renewEmbedToken(request: RenewEmbedTokenRequest): Promise<string | null>;
+export type EmbedTokenChangeDecision = 'update' | 'swap' | 'reload';
+export interface EmbedTokenChangeInput {
+    /** The `embed-token` attribute differs from the last attribute value read (not from `config.embedToken`). */
+    tokenChanged: boolean;
+    /** The swap signature is unchanged. */
+    sameSignature: boolean;
+    hasAttemptedInit: boolean;
+    /** Authenticated, no `lastAuthError`, no error screen shown, and launched for the current init. */
+    healthy: boolean;
+    /** `embedTokenRequest` is registered; the silent swap is opt-in. */
+    hasProvider: boolean;
+}
+/**
+ * What an identity attribute change does to a widget:
+ * - `update`: not started yet, or nothing identity-relevant changed. Keep going.
+ * - `swap`: a same-member pass on a healthy widget whose host registered
+ *   `embedTokenRequest`. Replace the pass in place, no reload.
+ * - `reload`: everything else once started, as today.
+ */
+export declare function decideEmbedTokenChange(input: EmbedTokenChangeInput): EmbedTokenChangeDecision;

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

@@ -35,11 +35,15 @@ export interface DispatchHostCallbackInput {
     transport?: HostCallbackTransport;
     observer?: HostCallbackObserver;
 }
+/** Decode an embed token's claims without verifying it; the server verifies. */
+export declare function readEmbedTokenClaims(embedToken?: string): Record<string, unknown> | null;
 /** Mirrors auth identity-source precedence; token authenticity is enforced by widget authentication. */
 export declare function resolveHostUserIdentifiers(config: Pick<WidgetConfig, 'embedToken' | 'userIdentifiers'>): Record<string, string>;
 /** Adds host-owned identity values without making widget code depend on auth internals. */
 export declare function enrichHostCallbackPayload(payload: unknown, userIdentifiers?: Record<string, string>): unknown;
 export declare function getHostCallbackDefinition(callbackName: string, payload: unknown): HostCallbackDefinition | undefined;
+/** Read registered capabilities without invoking customer code. */
+export declare function getSupportedHostCallbacks(callbacks: ReturningAIWidgetCallbacks, hostWidgetType: ReturningAIWidgetType): string[];
 export declare function isHostCallbackMessageSupported(definition: HostCallbackDefinition, action: string, sourceWidgetType: string, hostWidgetType: ReturningAIWidgetType): boolean;
 /**
  * Runs every supported host callback through one policy-driven boundary.

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

@@ -1,7 +1,9 @@
 import type { WidgetConfig, WidgetState } from '../types';
+/** A state a newer init replaced: its in-flight work may finish, but never reaches storage. */
+export declare function retireWidgetState(state: WidgetState): void;
 export declare function saveToStorage(config: WidgetConfig, state: WidgetState): void;
 export declare function loadFromStorage(config: WidgetConfig, state: WidgetState): boolean;
-export declare function clearStorage(config: WidgetConfig): void;
+export declare function clearStorage(config: WidgetConfig, state?: WidgetState): void;
 export declare function loadErrorSettingsFromStorage(config: WidgetConfig): Record<string, unknown> | null;
 export declare function saveErrorSettingsToStorage(config: WidgetConfig, settings: Record<string, unknown>): void;
 declare function isTokenExpired(expiry: number | null): boolean;

package/dist/types/index.d.ts

@@ -18,6 +18,6 @@ declare global {
     }
 }
 export { StoreWidget, ChannelWidget, MilestoneWidget, SocialWidget, CurrencyWidget, ReferralWidget, CustomWidget };
-export type { MilestoneCtaClickPayload, ReturningAIGenericHostCallbackActionMessage, ReturningAIMilestoneCtaClickCallback, ReturningAIStoreCallbackFieldOptionsCallback, ReturningAIStoreHostCallbackActionMessage, ReturningAIStorePurchaseSuccessCallback, ReturningAIWidgetCallback, ReturningAIWidgetCallbackMap, ReturningAIWidgetCallbackRegistration, ReturningAIWidgetActionMessage, ReturningAIWidgetActionResultMessage, ReturningAIWidgetCallbacks, ReturningAIWidgetHostCallbackActionMessage, ReturningAIWidgetType, StoreCallbackFieldOptionsContext, StoreCallbackFieldOptionsField, StoreCallbackFieldOptionsFieldType, StoreCallbackFieldOptionsPayload, StoreCallbackFieldOptionsResult, StoreHostCallbackPayload, StorePurchaseSuccessPayload, WidgetHostCallbackPayload, } from './types';
+export type { EmbedTokenRequestPayload, EmbedTokenRequestResult, MilestoneCtaClickPayload, ReturningAIEmbedTokenRequestCallback, ReturningAIEmbedTokenRequestReason, ReturningAIGenericHostCallbackActionMessage, ReturningAIMilestoneCtaClickCallback, ReturningAIStoreCallbackFieldOptionsCallback, ReturningAIStoreHostCallbackActionMessage, ReturningAIStorePurchaseSuccessCallback, ReturningAIWidgetCallback, ReturningAIWidgetCallbackMap, ReturningAIWidgetCallbackRegistration, ReturningAIWidgetActionMessage, ReturningAIWidgetActionResultMessage, ReturningAIWidgetCallbacks, ReturningAIWidgetHostCallbackActionMessage, ReturningAIWidgetType, StoreCallbackFieldOptionsContext, StoreCallbackFieldOptionsField, StoreCallbackFieldOptionsFieldType, StoreCallbackFieldOptionsPayload, StoreCallbackFieldOptionsResult, StoreHostCallbackPayload, StorePurchaseSuccessPayload, WidgetHostCallbackPayload, } from './types';
 export { MILESTONE_CTA_CLICK_CALLBACK_NAME, MILESTONE_CTA_CLICK_EVENT, MILESTONE_CTA_CLICK_SCOPE, 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

@@ -26,6 +26,13 @@ export interface StoreCallbackFieldOptionsPayload {
 export interface StoreCallbackFieldOptionsResult {
     fieldOptions: Record<string, string[]>;
     signature?: string;
+    /** Display-only disabled accounts by field ID; excluded from the signed result. */
+    ineligibleOptions?: Record<string, string[]>;
+    /** Plain-text hints keyed by field ID and canonical account value.
+     * Display-only: the frontend ignores invalid/blank entries and limits text to
+     * 200 Unicode code points, appending an ellipsis when truncated.
+     */
+    optionDescriptions?: Record<string, Record<string, string>>;
 }
 export interface StorePurchaseSuccessPayload {
     scope: typeof STORE_PURCHASE_SUCCESS_SCOPE;
@@ -88,10 +95,33 @@ export type ReturningAIWidgetCallback<TPayload = any, TResult = any> = (payload:
 export type ReturningAIStoreCallbackFieldOptionsCallback = (payload: StoreCallbackFieldOptionsPayload) => Promise<StoreCallbackFieldOptionsResult> | StoreCallbackFieldOptionsResult;
 export type ReturningAIStorePurchaseSuccessCallback = (payload: StorePurchaseSuccessPayload) => Promise<unknown> | unknown;
 export type ReturningAIMilestoneCtaClickCallback = (payload: MilestoneCtaClickPayload) => Promise<unknown> | unknown;
+/**
+ * Why the SDK asks the host page for a new embed token:
+ * - `session-expired`: renewing a running session failed and signing in again
+ *   needs a fresh pass.
+ * - `expired`: the pass is past its expiry, or the server refused it as
+ *   expired, when signing in outside session renewal (for example at mount).
+ */
+export type ReturningAIEmbedTokenRequestReason = 'expired' | 'session-expired';
+export interface EmbedTokenRequestPayload {
+    reason: ReturningAIEmbedTokenRequestReason;
+}
+export interface EmbedTokenRequestResult {
+    /** A freshly minted embed token for the same member and community. */
+    embedToken: string;
+}
+/**
+ * SDK-invoked host callback: return a fresh embed token for the widget's
+ * member. Widgets for the same member share one call. Answers that are not a
+ * fresh same-member pass, throws, or no answer within 10 seconds leave the
+ * widget's existing error in place. Never advertised to widget content.
+ */
+export type ReturningAIEmbedTokenRequestCallback = (payload: EmbedTokenRequestPayload) => Promise<EmbedTokenRequestResult> | EmbedTokenRequestResult;
 export interface ReturningAIWidgetCallbackMap {
     callbackFieldOptions: ReturningAIStoreCallbackFieldOptionsCallback;
     storePurchaseSuccess: ReturningAIStorePurchaseSuccessCallback;
     milestoneCtaClick: ReturningAIMilestoneCtaClickCallback;
+    embedTokenRequest: ReturningAIEmbedTokenRequestCallback;
 }
 export type ReturningAIWidgetCallbacks = Partial<ReturningAIWidgetCallbackMap> & {
     [callbackName: string]: ReturningAIWidgetCallback | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@returningai/widget-sdk",
-  "version": "1.8.13",
+  "version": "1.8.14",
   "description": "Shadow DOM isolated widget SDK for ReturningAI",
   "main": "dist/rai-widget.iife.js",
   "module": "dist/rai-widget.js",
@@ -42,7 +42,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 src/react18.d.ts src/react19.d.ts dist/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:fonts && npm run test:jsx-types && npm run test:loader-lifecycle",
+    "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:embed-token-renewal && npm run test:auth-embed-token-request && npm run test:fonts && npm run test:jsx-types && npm run test:loader-lifecycle && npm run test:auth-renewal-budget && npm run test:state-ownership",
     "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",
@@ -54,13 +54,17 @@
     "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:auth-embed-token-request": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/auth-embed-token-request.test.js",
+    "test:embed-token-renewal": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/embed-token-renewal.test.js",
     "test:fonts": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/fonts.test.js",
     "test:jsx-types": "npm run types && node --test test/jsx/declaration-shape.test.mjs test/jsx/packed-consumer.test.mjs && tsc -p test/jsx/tsconfig.react.json && tsc -p test/jsx/tsconfig.vue.json",
     "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",
-    "test:loader-lifecycle": "node --test test/loader-lifecycle.test.mjs"
+    "test:loader-lifecycle": "node --test test/loader-lifecycle.test.mjs",
+    "test:state-ownership": "node --test test/state-ownership.test.mjs",
+    "test:auth-renewal-budget": "node --test test/auth-renewal-budget.test.mjs"
   },
   "devDependencies": {
     "@types/react": "^19.1.10",