@athenaintel/react 0.26.5 → 0.27.0

package/dist/runtime/auth.d.ts

@@ -1,4 +1,5 @@
 import type { AthenaTokenRenewer } from '../auth/credential-source';
+import { AthenaSdkError } from '../diagnostics/errors';
 export interface ParentBridgeState {
     /** PropelAuth access token from the parent window. */
     token: string | null;
@@ -25,6 +26,19 @@ export interface ParentBridgeState {
     hostAnswered: boolean;
     /** True once config has been received from the parent (or timeout fired). */
     ready: boolean;
+    /**
+     * Set when the Marathon mint (`/_athena/auth`) gave up. It gives up when it
+     * gets a refusal (401, 403, or any 4xx other than 404), a body it cannot
+     * read, or a transient failure (5xx, 408, 429, a network error, a timeout)
+     * on every attempt of one bounded retry cycle. `code` is
+     * `auth_bridge_failed`, or `auth_bridge_timeout` when the last attempt
+     * timed out. After that the bridge does not mint again in the background. A
+     * forced renewal (`renewToken({ force: true })`) starts one new bounded
+     * cycle. A token that an earlier mint handed out is kept (the server still
+     * validates it), and the bridge never puts an empty token in its place. The
+     * next successful mint clears it. Absent or `null` otherwise.
+     */
+    error?: AthenaSdkError | null;
 }
 /**
  * {@link ParentBridgeState} plus the bridge's token renewal: `force` (the
@@ -57,9 +71,65 @@ export interface ParentBridgeOptions {
      * Useful for private-cloud or custom-domain deployments.
      */
     trustedOrigins?: string[];
+    /** @internal Overrides {@link DEFAULT_MINT_RETRY_POLICY}; used by tests. */
+    mintRetryPolicy?: MintRetryPolicy;
+}
+/**
+ * How one Marathon mint cycle retries. A cycle is the initial acquisition, a
+ * scheduled refresh, or a forced renewal. It sends at most `maxAttempts`
+ * requests. It retries only a transient failure (5xx, 408, 429, a network
+ * error, a timeout), after a capped exponential backoff with jitter, and then
+ * it gives up. Nothing retries in the background after a cycle gave up.
+ */
+export interface MintRetryPolicy {
+    /** Requests per cycle, the first one included. */
+    maxAttempts: number;
+    /** Ceiling of the delay before the first retry; it doubles for each retry. */
+    baseDelayMs: number;
+    /** Largest delay before any retry. */
+    maxDelayMs: number;
+    /** How long one request can take before it is aborted and counted as a timeout. */
+    timeoutMs: number;
+    /** Source of jitter in `[0, 1)`. */
+    random: () => number;
 }
+export declare const DEFAULT_MINT_RETRY_POLICY: MintRetryPolicy;
 export declare const getTokenRefreshDelay: (expiresAt: unknown, nowMs: number) => number;
-export declare const getAuthRetryDelay: (retryAttempt: number) => number;
+/**
+ * The delay before retry number `retry` of a mint cycle (1 is the first
+ * retry). The ceiling is `min(maxDelayMs, baseDelayMs * 2^(retry - 1))`, and
+ * equal jitter puts the wait between half of that ceiling and all of it, so
+ * viewers whose mint failed at the same time do not retry at the same time.
+ */
+export declare function getMintRetryDelay({ retry, policy, }: {
+    retry: number;
+    policy?: Pick<MintRetryPolicy, 'baseDelayMs' | 'maxDelayMs' | 'random'>;
+}): number;
+/** A mint status worth another attempt: the host, or something in front of it, is briefly unwell. */
+export declare function isRetryableMintStatus(status: number): boolean;
+/** A failed `/_athena/auth` request that is worth another attempt. */
+interface TransientMintFailure {
+    kind: 'transient';
+    status: number | null;
+    reason: 'status' | 'network' | 'timeout';
+    hostError: string | null;
+    cause?: unknown;
+}
+/** A failed `/_athena/auth` request that ends its cycle at once. */
+interface RefusedMintFailure {
+    kind: 'refused';
+    status: number;
+    /** `status`: a 4xx other than 404, 408 and 429. `invalid_body`: a 2xx whose body is not a JSON object. */
+    reason: 'status' | 'invalid_body';
+    hostError: string | null;
+}
+export type MintFailure = TransientMintFailure | RefusedMintFailure;
+/** The typed error that a mint cycle reports when it gives up. */
+export declare function mintFailureError({ failure, attempts, phase, }: {
+    failure: MintFailure;
+    attempts: number;
+    phase: 'initial' | 'renewal';
+}): AthenaSdkError;
 /**
  * Listens for auth tokens AND environment config from the host environment.
  *
@@ -75,12 +145,16 @@ export declare const getAuthRetryDelay: (retryAttempt: number) => number;
  *    returns `{ token, statewireSyncUrl, backendBaseUrl, appUrl }` — the
  *    statewire mount, the bare Agora base and the app origin. A 404 means
  *    we're not on a Marathon origin — the hook falls through with empty
- *    state.
+ *    state. Any other failure fails closed: one bounded retry cycle
+ *    ({@link MintRetryPolicy}) for a transient failure, none for a refusal,
+ *    and then `error` is set and `ready` flips with no token — never an
+ *    empty or anonymous one.
  *
- * In both modes a timeout safety net flips `ready: true` so the app never
- * blocks indefinitely.
+ * In both modes the app never blocks indefinitely: the iframe bridge flips
+ * `ready: true` after a timeout, and a Marathon mint cycle ends after at most
+ * `maxAttempts` requests.
  */
-export declare function useParentBridge({ trustedOrigins, }?: ParentBridgeOptions): ParentBridge;
+export declare function useParentBridge({ trustedOrigins, mintRetryPolicy, }?: ParentBridgeOptions): ParentBridge;
 /**
  * Legacy hook — returns just the auth token from the parent bridge.
  * Prefer useParentBridge() for new code.

package/dist/runtime/auth.js

@@ -1,5 +1,6 @@
 import { useMemo, useState, useRef, useEffect, useCallback } from "react";
 import { athenaDiagnostics } from "../diagnostics/athena-diagnostics.js";
+import { AthenaSdkError } from "../diagnostics/errors.js";
 function isTrustedOrigin({
   origin,
   trustedOrigins
@@ -41,10 +42,16 @@ function readAuthMintUrls(data) {
 const BRIDGE_TIMEOUT_MS = 2e3;
 const PARENT_TOKEN_RENEWAL_TIMEOUT_MS = 5e3;
 const TOKEN_REFRESH_BUFFER_MS = 5 * 60 * 1e3;
-const TOKEN_REFRESH_RETRY_BASE_MS = 60 * 1e3;
-const TOKEN_REFRESH_RETRY_MAX_MS = 5 * 60 * 1e3;
+const TOKEN_REFRESH_MIN_DELAY_MS = 60 * 1e3;
 const DEFAULT_TOKEN_REFRESH_MS = 55 * 60 * 1e3;
 const EMPTY_TRUSTED_ORIGINS = [];
+const DEFAULT_MINT_RETRY_POLICY = {
+  maxAttempts: 4,
+  baseDelayMs: 500,
+  maxDelayMs: 4e3,
+  timeoutMs: BRIDGE_TIMEOUT_MS,
+  random: Math.random
+};
 const normalizeOrigin = (value) => {
   try {
     return new URL(value).origin;
@@ -60,14 +67,74 @@ const getTokenRefreshDelay = (expiresAt, nowMs) => {
   if (!Number.isFinite(expiresAtMs)) {
     return DEFAULT_TOKEN_REFRESH_MS;
   }
-  return Math.max(TOKEN_REFRESH_RETRY_BASE_MS, expiresAtMs - nowMs - TOKEN_REFRESH_BUFFER_MS);
-};
-const getAuthRetryDelay = (retryAttempt) => {
-  const safeAttempt = Number.isFinite(retryAttempt) ? Math.max(0, Math.floor(retryAttempt)) : 0;
-  return Math.min(TOKEN_REFRESH_RETRY_MAX_MS, TOKEN_REFRESH_RETRY_BASE_MS * 2 ** safeAttempt);
+  return Math.max(TOKEN_REFRESH_MIN_DELAY_MS, expiresAtMs - nowMs - TOKEN_REFRESH_BUFFER_MS);
 };
+function getMintRetryDelay({
+  retry,
+  policy = DEFAULT_MINT_RETRY_POLICY
+}) {
+  const safeRetry = Number.isFinite(retry) ? Math.max(1, Math.floor(retry)) : 1;
+  const ceiling = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** (safeRetry - 1));
+  const jitter = Math.min(1, Math.max(0, policy.random()));
+  return Math.round(ceiling / 2 + ceiling / 2 * jitter);
+}
+function isRetryableMintStatus(status) {
+  return status >= 500 || status === 408 || status === 429;
+}
+async function readHostError(resp) {
+  try {
+    const body = await resp.json();
+    if (body && typeof body === "object" && "error" in body) {
+      const value = body.error;
+      return typeof value === "string" ? value.slice(0, 100) : null;
+    }
+  } catch {
+  }
+  return null;
+}
+const MINT_RETRY_NOTE = "The SDK stopped retrying and does not connect without a credential. Remount the provider, or call renewToken({ force: true }), to try again.";
+function mintFailureHint(failure) {
+  if (failure.kind === "transient") {
+    return `The host could not mint a viewer token. Check the Marathon and Agora logs. ${MINT_RETRY_NOTE}`;
+  }
+  if (failure.reason === "invalid_body") {
+    return `The host answered /_athena/auth without a JSON mint body, so this origin is not a Marathon bridge. Pass token, getToken or apiKey. ${MINT_RETRY_NOTE}`;
+  }
+  if (failure.status === 401) {
+    return `The host has no session for this viewer. Sign in again through the app URL. ${MINT_RETRY_NOTE}`;
+  }
+  if (failure.status === 403) {
+    return `The host does not give this viewer access to the app. ${MINT_RETRY_NOTE}`;
+  }
+  return `The host refused the mint request. ${MINT_RETRY_NOTE}`;
+}
+function mintFailureError({
+  failure,
+  attempts,
+  phase
+}) {
+  const timedOut = failure.kind === "transient" && failure.reason === "timeout";
+  const answer = failure.status !== null ? `HTTP ${failure.status}` : timedOut ? "a timeout" : "a network error";
+  const message = failure.kind === "transient" ? `The host auth bridge (/_athena/auth) failed ${attempts} time${attempts === 1 ? "" : "s"} (last: ${answer}).` : failure.reason === "invalid_body" ? `The host auth bridge (/_athena/auth) answered ${answer} without a JSON mint body.` : `The host auth bridge (/_athena/auth) refused the mint (${answer}).`;
+  return new AthenaSdkError({
+    code: timedOut ? "auth_bridge_timeout" : "auth_bridge_failed",
+    message,
+    hint: mintFailureHint(failure),
+    ...failure.status !== null && { status: failure.status },
+    ...failure.hostError !== null && { detail: { code: failure.hostError } },
+    ...failure.kind === "transient" && failure.cause !== void 0 && { cause: failure.cause },
+    context: {
+      mode: "marathon",
+      phase,
+      attempts,
+      reason: failure.reason,
+      host_error: failure.hostError
+    }
+  });
+}
 function useParentBridge({
-  trustedOrigins = EMPTY_TRUSTED_ORIGINS
+  trustedOrigins = EMPTY_TRUSTED_ORIGINS,
+  mintRetryPolicy = DEFAULT_MINT_RETRY_POLICY
 } = {}) {
   const isInIframe = typeof window !== "undefined" && window.parent !== window;
   const runtimeTrustedOrigins = useMemo(() => {
@@ -87,8 +154,11 @@ function useParentBridge({
     token: null,
     ...EMPTY_BRIDGE_URLS,
     hostAnswered: false,
-    ready: false
+    ready: false,
+    error: null
   });
+  const mintRetryPolicyRef = useRef(mintRetryPolicy);
+  mintRetryPolicyRef.current = mintRetryPolicy;
   const readySignalSent = useRef(false);
   const configReceived = useRef(false);
   const tokenRef = useRef(state.token);
@@ -179,147 +249,189 @@ function useParentBridge({
     let refreshTimer = null;
     let controller = null;
     let inFlight = null;
-    let retryAttempt = 0;
+    let retryWait = null;
     const clearRefreshTimer = () => {
       if (refreshTimer) {
         clearTimeout(refreshTimer);
         refreshTimer = null;
       }
     };
-    const markReady = () => {
-      if (cancelled) return;
-      setState((prev) => prev.ready ? prev : { ...prev, ready: true });
+    const endRetryWait = () => {
+      if (!retryWait) return;
+      clearTimeout(retryWait.timer);
+      const { resolve } = retryWait;
+      retryWait = null;
+      resolve();
     };
+    const waitBeforeRetry = (delayMs) => new Promise((resolve) => {
+      retryWait = { timer: setTimeout(endRetryWait, delayMs), resolve };
+    });
     const scheduleRefresh = (expiresAt) => {
       clearRefreshTimer();
-      retryAttempt = 0;
       const delay = getTokenRefreshDelay(expiresAt, Date.now());
       refreshTimer = setTimeout(() => {
-        void fetchAuth({ markReadyOnFailure: false });
-      }, delay);
-    };
-    const scheduleRetry = () => {
-      clearRefreshTimer();
-      const delay = getAuthRetryDelay(retryAttempt);
-      retryAttempt += 1;
-      refreshTimer = setTimeout(() => {
-        void fetchAuth({ markReadyOnFailure: false });
+        refreshTimer = null;
+        void fetchAuth({ initial: false });
       }, delay);
     };
-    const mintAuth = async ({
-      markReadyOnFailure
-    }) => {
+    const mintOnce = async (timeoutMs) => {
       const requestController = new AbortController();
       controller = requestController;
-      const isInitial = markReadyOnFailure;
-      const rawEndSpan = isInitial ? athenaDiagnostics.span("auth.bridge", "auth.bridge.start", { mode: "marathon" }) : null;
-      let spanEnded = false;
-      const endBridgeSpan = rawEndSpan ? (name, options) => {
-        if (spanEnded) return 0;
-        spanEnded = true;
-        return rawEndSpan(name, options);
-      } : null;
+      let timedOut = false;
       const requestTimer = setTimeout(() => {
+        timedOut = true;
         requestController.abort();
-        endBridgeSpan == null ? void 0 : endBridgeSpan("auth.bridge.timeout", {
-          data: { mode: "marathon", timeout_ms: BRIDGE_TIMEOUT_MS }
-        });
-        if (markReadyOnFailure) {
-          markReady();
-        }
-      }, BRIDGE_TIMEOUT_MS);
+      }, timeoutMs);
       try {
         const resp = await fetch("/_athena/auth", {
           credentials: "include",
           headers: { Accept: "application/json" },
           signal: requestController.signal
         });
-        if (cancelled) return null;
+        if (cancelled) return { kind: "cancelled" };
+        if (resp.status === 404) return { kind: "absent", status: resp.status };
         if (!resp.ok) {
-          if (resp.status === 404) {
-            endBridgeSpan == null ? void 0 : endBridgeSpan("auth.bridge.absent", {
-              data: { mode: "marathon", status: resp.status }
-            });
-            markReady();
-          } else {
-            const failure = {
-              level: "warn",
-              data: { mode: "marathon", status: resp.status }
-            };
-            if (endBridgeSpan) {
-              endBridgeSpan("auth.bridge.error", failure);
-            } else {
-              athenaDiagnostics.emit("auth.token.refresh_failed", failure);
-            }
-            if (markReadyOnFailure) {
-              markReady();
-            }
-            scheduleRetry();
+          const hostError = await readHostError(resp);
+          if (cancelled) return { kind: "cancelled" };
+          if (timedOut && isRetryableMintStatus(resp.status)) {
+            return { kind: "transient", status: null, reason: "timeout", hostError: null };
           }
-          return null;
-        }
-        const data = await resp.json();
-        if (cancelled) return null;
-        if (endBridgeSpan) {
-          endBridgeSpan("auth.bridge.ready", {
-            data: { mode: "marathon", has_token: typeof data.token === "string" }
-          });
-          athenaDiagnostics.emit("auth.token.acquired", {
-            level: "debug",
-            data: { source: "marathon", expires_at: data.expires_at }
-          });
-        } else {
-          athenaDiagnostics.emit("auth.token.refreshed", {
-            level: "debug",
-            data: { source: "marathon", expires_at: data.expires_at }
-          });
+          return isRetryableMintStatus(resp.status) ? { kind: "transient", status: resp.status, reason: "status", hostError } : { kind: "refused", status: resp.status, reason: "status", hostError };
         }
-        const token = typeof data.token === "string" ? data.token : null;
-        setState({
-          token,
-          ...readAuthMintUrls(data),
-          hostAnswered: true,
-          ready: true
-        });
-        tokenRef.current = token;
-        scheduleRefresh(data.expires_at);
-        return token;
-      } catch (error) {
-        if (!cancelled && !(error instanceof DOMException && error.name === "AbortError")) {
-          const failure = { level: "warn", data: { mode: "marathon" }, error };
-          if (endBridgeSpan) {
-            endBridgeSpan("auth.bridge.error", failure);
-          } else {
-            athenaDiagnostics.emit("auth.token.refresh_failed", failure);
+        let data;
+        try {
+          data = await resp.json();
+        } catch (error) {
+          if (cancelled) return { kind: "cancelled" };
+          if (timedOut) {
+            return { kind: "transient", status: null, reason: "timeout", hostError: null, cause: error };
           }
+          return { kind: "refused", status: resp.status, reason: "invalid_body", hostError: null };
         }
-        if (markReadyOnFailure) {
-          markReady();
+        if (cancelled) return { kind: "cancelled" };
+        const token = data && typeof data === "object" ? data.token : null;
+        if (typeof token !== "string" || token === "") {
+          return { kind: "refused", status: resp.status, reason: "invalid_body", hostError: null };
         }
-        if (!cancelled) {
-          scheduleRetry();
+        return { kind: "minted", data };
+      } catch (error) {
+        if (cancelled) return { kind: "cancelled" };
+        if (timedOut) {
+          return { kind: "transient", status: null, reason: "timeout", hostError: null, cause: error };
         }
-        return null;
+        return { kind: "transient", status: null, reason: "network", hostError: null, cause: error };
       } finally {
         clearTimeout(requestTimer);
         if (controller === requestController) controller = null;
       }
     };
+    const runMintCycle = async ({ initial }) => {
+      const policy = mintRetryPolicyRef.current;
+      const maxAttempts = Math.max(1, Math.floor(policy.maxAttempts));
+      const phase = initial ? "initial" : "renewal";
+      const endBridgeSpan = initial ? athenaDiagnostics.span("auth.bridge", "auth.bridge.start", { mode: "marathon" }) : null;
+      let attempts = 0;
+      let lastFailure = null;
+      while (attempts < maxAttempts) {
+        attempts += 1;
+        const outcome = await mintOnce(policy.timeoutMs);
+        if (cancelled || outcome.kind === "cancelled") return null;
+        if (outcome.kind === "absent") {
+          endBridgeSpan == null ? void 0 : endBridgeSpan("auth.bridge.absent", {
+            data: { mode: "marathon", status: outcome.status }
+          });
+          setState(
+            (prev) => prev.ready && prev.error == null ? prev : { ...prev, ready: true, error: null }
+          );
+          return null;
+        }
+        if (outcome.kind === "minted") {
+          const { data } = outcome;
+          if (endBridgeSpan) {
+            endBridgeSpan("auth.bridge.ready", {
+              data: { mode: "marathon", has_token: typeof data.token === "string", attempts }
+            });
+            athenaDiagnostics.emit("auth.token.acquired", {
+              level: "debug",
+              data: { source: "marathon", expires_at: data.expires_at }
+            });
+          } else {
+            athenaDiagnostics.emit("auth.token.refreshed", {
+              level: "debug",
+              data: { source: "marathon", expires_at: data.expires_at, attempts }
+            });
+          }
+          const token = typeof data.token === "string" ? data.token : null;
+          setState({
+            token,
+            ...readAuthMintUrls(data),
+            hostAnswered: true,
+            ready: true,
+            error: null
+          });
+          tokenRef.current = token;
+          scheduleRefresh(data.expires_at);
+          return token;
+        }
+        lastFailure = outcome;
+        if (outcome.kind === "refused" || attempts >= maxAttempts) break;
+        const delayMs = getMintRetryDelay({ retry: attempts, policy });
+        athenaDiagnostics.emit("auth.bridge.retry", {
+          level: "warn",
+          data: {
+            mode: "marathon",
+            phase,
+            status: outcome.status,
+            reason: outcome.reason,
+            host_error: outcome.hostError,
+            attempt: attempts,
+            max_attempts: maxAttempts,
+            delay_ms: delayMs
+          }
+        });
+        await waitBeforeRetry(delayMs);
+        if (cancelled) return null;
+      }
+      if (!lastFailure) return null;
+      const error = mintFailureError({ failure: lastFailure, attempts, phase });
+      const failureData = {
+        mode: "marathon",
+        phase,
+        status: lastFailure.status,
+        reason: lastFailure.reason,
+        attempts
+      };
+      if (endBridgeSpan) {
+        endBridgeSpan(
+          error.code === "auth_bridge_timeout" ? "auth.bridge.timeout" : "auth.bridge.error",
+          { data: failureData, error }
+        );
+      } else {
+        athenaDiagnostics.emit("auth.token.refresh_failed", {
+          level: "error",
+          data: failureData,
+          error
+        });
+      }
+      setState((prev) => ({ ...prev, error, ready: true }));
+      return null;
+    };
     const fetchAuth = (options) => {
-      inFlight ?? (inFlight = mintAuth(options).finally(() => {
+      inFlight ?? (inFlight = runMintCycle(options).finally(() => {
         inFlight = null;
       }));
       return inFlight;
     };
     renewerRef.current = ({ force }) => {
       if (!force) return Promise.resolve(tokenRef.current);
-      return fetchAuth({ markReadyOnFailure: false }).then((token) => token ?? tokenRef.current);
+      return fetchAuth({ initial: false }).then((token) => token ?? tokenRef.current);
     };
-    void fetchAuth({ markReadyOnFailure: true });
+    void fetchAuth({ initial: true });
     return () => {
       cancelled = true;
       controller == null ? void 0 : controller.abort();
       clearRefreshTimer();
+      endRetryWait();
       renewerRef.current = null;
     };
   }, [isInIframe]);
@@ -336,9 +448,12 @@ function useParentAuth() {
   return useParentBridge().token;
 }
 export {
-  getAuthRetryDelay,
+  DEFAULT_MINT_RETRY_POLICY,
+  getMintRetryDelay,
   getTokenRefreshDelay,
+  isRetryableMintStatus,
   mergeBridgeConfigMessage,
+  mintFailureError,
   readAuthMintUrls,
   useParentAuth,
   useParentBridge