@meistrari/auth-nuxt 3.18.0 → 3.19.0

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@meistrari/auth-nuxt",
   "configKey": "telaAuth",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/composables/admin.d.ts

@@ -1,8 +1,9 @@
-import type { AdminApplicationRecord, AdminApplicationEntitlementRecord, AdminOrganization, AdminOrganizationTeamRecord, CreateAdminApplicationEntitlementOptions, CreateAdminApplicationOptions, CreateAdminOrganizationOptions, CreateAdminOrganizationTeamOptions, GetAdminOrganizationOptions, ListAdminApplicationsOptions, ListAdminApplicationsResult, ListAdminOrganizationMembersOptions, ListAdminOrganizationMembersResult, ListAdminOrganizationsOptions, ListAdminOrganizationsResult, ListAdminOrganizationTeamsOptions, ListAdminOrganizationTeamsResult, ListAdminUsersOptions, ListAdminUsersResult, UpdateAdminOrganizationOptions } from '@meistrari/auth-core';
+import type { AdminApplicationRecord, AdminApplicationEntitlementRecord, AdminOrganization, AdminOrganizationTeamRecord, AdminUserAccess, CreateAdminApplicationEntitlementOptions, CreateAdminApplicationOptions, CreateAdminOrganizationOptions, CreateAdminOrganizationTeamOptions, GetAdminOrganizationOptions, InviteAdminOrganizationUsersOptions, InviteAdminOrganizationUsersResult, ListAdminApplicationsOptions, ListAdminApplicationsResult, ListAdminOrganizationMembersOptions, ListAdminOrganizationMembersResult, ListAdminOrganizationsOptions, ListAdminOrganizationsResult, ListAdminOrganizationTeamsOptions, ListAdminOrganizationTeamsResult, ListAdminUsersOptions, ListAdminUsersResult, AdminMember, RemoveAdminMemberOptions, ResendAdminInviteOptions, SetAdminUserApplicationRoleOptions, SetAdminUserTeamOptions, UpdateAdminMemberRoleOptions, UpdateAdminOrganizationOptions } from '@meistrari/auth-core';
 export interface UseTelaAdminReturn {
     /**
-     * Lists users from the Better Auth `user` table as a global admin.
-     * @param options - Pagination, search, filter, and ordering options
+     * Lists users as a global admin, optionally with organization previews
+     * and totals when a preview size is requested.
+     * @param options - Pagination, ordering, search, and preview options
      * @returns The paginated user listing
      */
     listUsers: (options?: ListAdminUsersOptions) => Promise<ListAdminUsersResult>;
@@ -64,6 +65,14 @@ export interface UseTelaAdminReturn {
      * @returns The created organization team
      */
     createOrganizationTeam: (options: CreateAdminOrganizationTeamOptions) => Promise<AdminOrganizationTeamRecord>;
+    /**
+     * Fetches the per-organization access report for a single user as a global
+     * admin, including organization roles, teams, and entitled applications with
+     * the user's effective application role.
+     * @param userId - ID of the user to fetch access for
+     * @returns The user access report
+     */
+    getUserAccess: (userId: string) => Promise<AdminUserAccess>;
     /**
      * Creates an organization as a global admin without joining it.
      * @param options - Organization name and optional slug, logo, metadata, and settings
@@ -76,6 +85,62 @@ export interface UseTelaAdminReturn {
      * @returns The updated organization
      */
     updateOrganization: (options: UpdateAdminOrganizationOptions) => Promise<AdminOrganization>;
+    /**
+     * Updates an organization member's role as a global admin.
+     * @param options - Membership ID and the new role
+     * @returns The updated membership
+     */
+    updateMemberRole: (options: UpdateAdminMemberRoleOptions) => Promise<AdminMember>;
+    /**
+     * Removes an organization member as a global admin.
+     * @param options - Membership ID to remove
+     * @returns The removed membership
+     */
+    removeMember: (options: RemoveAdminMemberOptions) => Promise<AdminMember>;
+    /**
+     * Sets a user's effective application role within an organization as a
+     * global admin. A non-null role grants access, a null role denies access
+     * (leave application), and clear removes the user-specific override.
+     * @param options - User, organization, application, and the role or clear flag
+     */
+    setUserApplicationRole: (options: SetAdminUserApplicationRoleOptions) => Promise<void>;
+    /**
+     * Reconciles a user's team memberships within an organization to a given set
+     * as a global admin.
+     * @param options - User, organization, and the desired teams (empty to clear)
+     */
+    setUserTeam: (options: SetAdminUserTeamOptions) => Promise<void>;
+    /**
+     * Bans a user from the auth system and invalidates all their sessions.
+     * @param userId - ID of the user to ban
+     */
+    banUser: (userId: string) => Promise<void>;
+    /**
+     * Lifts a user's ban.
+     * @param userId - ID of the user to unban
+     */
+    unbanUser: (userId: string) => Promise<void>;
+    /**
+     * Permanently removes a user from the auth system.
+     * @param userId - ID of the user to remove
+     */
+    removeUser: (userId: string) => Promise<void>;
+    /**
+     * Cancels a pending invitation as a global admin.
+     * @param invitationId - ID of the invitation to cancel
+     */
+    cancelInvite: (invitationId: string) => Promise<void>;
+    /**
+     * Re-sends an organization invitation email as a global admin.
+     * @param options - Organization, email, role, and optional application
+     */
+    resendInvite: (options: ResendAdminInviteOptions) => Promise<void>;
+    /**
+     * Invites several users to an organization in one call, isolating failures
+     * per email in the results payload.
+     * @param options - Organization, emails, role, and optional teams/application
+     */
+    inviteOrganizationUsers: (options: InviteAdminOrganizationUsersOptions) => Promise<InviteAdminOrganizationUsersResult>;
 }
 /**
  * Composable for global admin operations.

package/dist/runtime/composables/admin.js

@@ -136,12 +136,45 @@ export function useTelaAdmin() {
   async function createOrganizationTeam(options) {
     return await authClient.admin.createOrganizationTeam(options);
   }
+  async function getUserAccess(userId) {
+    return await authClient.admin.getUserAccess(userId);
+  }
   async function createOrganization(options) {
     return await authClient.admin.createOrganization(options);
   }
   async function updateOrganization(options) {
     return await authClient.admin.updateOrganization(options);
   }
+  async function updateMemberRole(options) {
+    return await authClient.admin.updateMemberRole(options);
+  }
+  async function removeMember(options) {
+    return await authClient.admin.removeMember(options);
+  }
+  async function setUserApplicationRole(options) {
+    return await authClient.admin.setUserApplicationRole(options);
+  }
+  async function setUserTeam(options) {
+    return await authClient.admin.setUserTeam(options);
+  }
+  async function banUser(userId) {
+    return await authClient.admin.banUser(userId);
+  }
+  async function unbanUser(userId) {
+    return await authClient.admin.unbanUser(userId);
+  }
+  async function removeUser(userId) {
+    return await authClient.admin.removeUser(userId);
+  }
+  async function cancelInvite(invitationId) {
+    return await authClient.admin.cancelInvite(invitationId);
+  }
+  async function resendInvite(options) {
+    return await authClient.admin.resendInvite(options);
+  }
+  async function inviteOrganizationUsers(options) {
+    return await authClient.admin.inviteOrganizationUsers(options);
+  }
   return {
     listUsers,
     listApplications,
@@ -153,7 +186,18 @@ export function useTelaAdmin() {
     listOrganizationMembers,
     listOrganizationTeams,
     createOrganizationTeam,
+    getUserAccess,
     createOrganization,
-    updateOrganization
+    updateOrganization,
+    updateMemberRole,
+    removeMember,
+    setUserApplicationRole,
+    setUserTeam,
+    banUser,
+    unbanUser,
+    removeUser,
+    cancelInvite,
+    resendInvite,
+    inviteOrganizationUsers
   };
 }

package/dist/runtime/composables/application/auth.d.ts

@@ -60,15 +60,27 @@ export interface UseTelaApplicationAuthReturn {
      * for new access and refresh tokens. The server updates the cookies and returns
      * the user and organization data.
      *
-     * @throws {RefreshTokenExpiredError} If no refresh token is available or refresh fails
+     * Concurrent calls (including the SDK plugin's background refresh) share
+     * one in-flight request, and transient failures are retried with backoff
+     * before this rejects.
+     *
+     * @throws {RefreshTokenExpiredError} If the refresh token is definitively expired or revoked (401/404)
+     * @throws {ApplicationError} If the refresh failed transiently (network failure, outage, rate limit) —
+     * the session is still valid and the call can be retried. Check `error.status` for the HTTP status,
+     * `undefined` meaning no HTTP response was received.
      */
     refreshToken: () => Promise<void>;
     /**
      * Retrieves the current access token.
      * If the token is expired, or close to expiry, it will be refreshed automatically.
      *
+     * Stale-while-revalidate: when a refresh fails transiently (network
+     * failure, outage) but the current token is still valid, the current
+     * token is returned instead of throwing.
+     *
      * @returns The current access token
-     * @throws {RefreshTokenExpiredError} If the token is expired and cannot be refreshed
+     * @throws {RefreshTokenExpiredError} If the refresh token is definitively expired or revoked (401/404)
+     * @throws {ApplicationError} If the refresh failed transiently and the current token is hard-expired
      */
     getToken: () => Promise<string | null | undefined>;
 }

package/dist/runtime/composables/application/auth.js

@@ -1,7 +1,9 @@
 import { navigateTo, useCookie, useRuntimeConfig } from "#app";
-import { AuthorizationFlowError, isTokenExpired, RefreshTokenExpiredError, UserNotLoggedInError } from "@meistrari/auth-core";
+import { ApplicationError, AuthorizationFlowError, isTokenExpired, RefreshTokenExpiredError, UserNotLoggedInError } from "@meistrari/auth-core";
 import { useApplicationSessionState } from "../state.js";
-import { willTokenExpireIn } from "../../helpers/token.js";
+import { ACCESS_TOKEN_COOKIE, readClientCookie } from "../../helpers/client-cookies.js";
+import { useRefreshOrchestrator } from "../../helpers/refresh-deps.js";
+import { extractHttpStatus } from "../../helpers/refresh-policy.js";
 import { useTelaOrganization } from "./organization.js";
 const FIFTEEN_MINUTES = 60 * 15;
 const ONE_MINUTE = 60 * 1e3;
@@ -52,18 +54,24 @@ export function useTelaApplicationAuth() {
     state.sessionAssurance.value = null;
     await $fetch("/auth/logout", { method: "POST" });
   }
+  const orchestrator = useRefreshOrchestrator(state);
+  function readAccessToken() {
+    return readClientCookie(ACCESS_TOKEN_COOKIE) ?? accessTokenCookie.value ?? null;
+  }
   async function refreshToken() {
-    try {
-      const result = await $fetch("/auth/refresh", {
-        method: "POST"
-      });
-      state.user.value = result.user;
-      state.activeOrganization.value = result.organization;
-      state.sessionAssurance.value = result.assurance;
-    } catch (error) {
-      console.error("[Auth Refresh] Failed to refresh token:", error);
-      throw new RefreshTokenExpiredError();
+    const outcome = await orchestrator.ensureFreshToken({ force: true });
+    if (outcome.status === "ok") {
+      return;
+    }
+    if (outcome.status === "auth-failed") {
+      console.error("[Auth Refresh] Refresh token expired or revoked:", outcome.error);
+      throw new RefreshTokenExpiredError({ cause: outcome.error, status: extractHttpStatus(outcome.error) });
     }
+    console.error("[Auth Refresh] Transient token refresh failure:", "error" in outcome ? outcome.error : "offline");
+    throw new ApplicationError("Failed to refresh access token", {
+      cause: "error" in outcome ? outcome.error : void 0,
+      status: "error" in outcome ? extractHttpStatus(outcome.error) : void 0
+    });
   }
   async function initSession() {
     if (!accessTokenCookie.value) {
@@ -81,11 +89,22 @@ export function useTelaApplicationAuth() {
     await useTelaOrganization().setActiveOrganization(organizationId);
   }
   async function getToken() {
-    const shouldRefresh = accessTokenCookie.value ? willTokenExpireIn(accessTokenCookie.value, ONE_MINUTE * 2) : true;
-    if (shouldRefresh) {
-      await refreshToken();
+    const outcome = await orchestrator.ensureFreshToken();
+    if (outcome.status === "ok") {
+      return readAccessToken();
+    }
+    if (outcome.status === "auth-failed") {
+      console.error("[Auth Refresh] Refresh token expired or revoked:", outcome.error);
+      throw new RefreshTokenExpiredError({ cause: outcome.error, status: extractHttpStatus(outcome.error) });
+    }
+    const currentToken = readAccessToken();
+    if (currentToken && !isTokenExpired(currentToken)) {
+      return currentToken;
     }
-    return accessTokenCookie.value;
+    throw new ApplicationError("Failed to refresh access token", {
+      cause: "error" in outcome ? outcome.error : void 0,
+      status: "error" in outcome ? extractHttpStatus(outcome.error) : void 0
+    });
   }
   return {
     user: state.user,

package/dist/runtime/helpers/client-cookies.d.ts

@@ -0,0 +1,23 @@
+/** Cookie holding the application access token (readable JWT) */
+export declare const ACCESS_TOKEN_COOKIE = "tela-access-token";
+/** Cookie holding the application refresh token (httpOnly — invisible to JS) */
+export declare const REFRESH_TOKEN_COOKIE = "tela-refresh-token";
+/**
+ * Reads a cookie value straight from `document.cookie`
+ *
+ * This is the source of truth for all token freshness math: `useCookie`
+ * refs captured at setup time can go stale after the server rotates
+ * cookies via `Set-Cookie`, which is exactly when the scheduling math
+ * must not be wrong
+ *
+ * @returns The decoded cookie value, or `null` when absent or on the server
+ */
+export declare function readClientCookie(name: string): string | null;
+/**
+ * Re-syncs the `useCookie` refs for both auth cookies after the server
+ * rotated them, so reactive app code observes the new values.
+ *
+ * Reactive sugar only — freshness logic never depends on it, it always
+ * reads `document.cookie` via {@link readClientCookie}
+ */
+export declare function syncAuthCookieRefs(): void;

package/dist/runtime/helpers/client-cookies.js

@@ -0,0 +1,28 @@
+import { refreshCookie } from "#app";
+export const ACCESS_TOKEN_COOKIE = "tela-access-token";
+export const REFRESH_TOKEN_COOKIE = "tela-refresh-token";
+export function readClientCookie(name) {
+  if (typeof document === "undefined") {
+    return null;
+  }
+  const prefix = `${name}=`;
+  for (const part of document.cookie.split(";")) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith(prefix)) {
+      const value = trimmed.slice(prefix.length);
+      try {
+        return decodeURIComponent(value);
+      } catch {
+        return value;
+      }
+    }
+  }
+  return null;
+}
+export function syncAuthCookieRefs() {
+  if (import.meta.server) {
+    return;
+  }
+  refreshCookie(ACCESS_TOKEN_COOKIE);
+  refreshCookie(REFRESH_TOKEN_COOKIE);
+}

package/dist/runtime/helpers/refresh-deps.d.ts

@@ -0,0 +1,37 @@
+import type { Ref } from 'vue';
+import type { FullOrganization, JWTPayload, User } from '@meistrari/auth-core';
+import type { RefreshOrchestrator, RefreshOrchestratorDeps } from './refresh-orchestrator.js';
+/** Success body of the `/auth/refresh` Nitro route */
+export interface RefreshResponseBody {
+    success: boolean;
+    user: User;
+    organization: FullOrganization;
+    assurance: JWTPayload['assurance'];
+    /** Epoch ms expiry of the freshly issued access token */
+    accessTokenExpiresAt: number | null;
+}
+interface ApplicationSessionState {
+    user: Ref<User | null>;
+    activeOrganization: Ref<FullOrganization | null>;
+    sessionAssurance: Ref<JWTPayload['assurance'] | null>;
+}
+/**
+ * Builds the orchestrator dependencies used by both the token-refresh
+ * plugin and `useTelaApplicationAuth`, so the two call sites can't drift
+ *
+ * `performRefresh` hits the Nitro `/auth/refresh` route with a bounded
+ * timeout (so a held Web Lock always releases), then updates session
+ * state and re-syncs the reactive cookie refs. Cookies themselves are
+ * rotated by the route via `Set-Cookie`
+ */
+export declare function buildRefreshDeps(state: ApplicationSessionState): RefreshOrchestratorDeps;
+/**
+ * Returns the refresh orchestrator for the current environment.
+ *
+ * On the client this is a singleton shared by the plugin and the
+ * composable, so their refreshes dedupe into one in-flight request.
+ * On the server each caller gets a throwaway instance — no state may
+ * leak across requests
+ */
+export declare function useRefreshOrchestrator(state: ApplicationSessionState): RefreshOrchestrator;
+export {};

package/dist/runtime/helpers/refresh-deps.js

@@ -0,0 +1,35 @@
+import { useCookie } from "#app";
+import { ACCESS_TOKEN_COOKIE, readClientCookie, syncAuthCookieRefs } from "./client-cookies.js";
+import { createRefreshOrchestrator } from "./refresh-orchestrator.js";
+import { DEFAULT_REFRESH_POLICY } from "./refresh-policy.js";
+import { parseTokenExpiry } from "./token.js";
+export function buildRefreshDeps(state) {
+  const accessTokenCookie = useCookie(ACCESS_TOKEN_COOKIE);
+  return {
+    performRefresh: async () => {
+      const result = await $fetch("/auth/refresh", {
+        method: "POST",
+        timeout: 15e3
+      });
+      state.user.value = result.user;
+      state.activeOrganization.value = result.organization;
+      state.sessionAssurance.value = result.assurance;
+      syncAuthCookieRefs();
+    },
+    // document.cookie is the live source of truth on the client; the
+    // useCookie ref covers SSR, where document is unavailable.
+    readAccessToken: () => readClientCookie(ACCESS_TOKEN_COOKIE) ?? accessTokenCookie.value ?? null,
+    parseTokenExpiry,
+    policy: DEFAULT_REFRESH_POLICY
+  };
+}
+let sharedOrchestrator = null;
+export function useRefreshOrchestrator(state) {
+  if (import.meta.server) {
+    return createRefreshOrchestrator(buildRefreshDeps(state));
+  }
+  if (!sharedOrchestrator) {
+    sharedOrchestrator = createRefreshOrchestrator(buildRefreshDeps(state));
+  }
+  return sharedOrchestrator;
+}

package/dist/runtime/helpers/refresh-orchestrator.d.ts

@@ -0,0 +1,64 @@
+import type { RefreshPolicy } from './refresh-policy.js';
+/**
+ * Result of an {@link RefreshOrchestrator.ensureFreshToken} call
+ *
+ * Always a concrete outcome — the orchestrator never throws and never
+ * resolves to `undefined`, so callers (the scheduler in particular)
+ * can't mistake a concurrent call for a failure
+ */
+export type RefreshOutcome = {
+    status: 'ok';
+    refreshed: boolean;
+} | {
+    status: 'skipped-offline';
+} | {
+    status: 'auth-failed';
+    error: unknown;
+} | {
+    status: 'transient-failed';
+    error: unknown;
+};
+/** Minimal Web Locks surface used by the orchestrator. */
+export interface RefreshLockManager {
+    request: <T>(name: string, callback: () => Promise<T>) => Promise<T>;
+}
+export interface RefreshOrchestratorDeps {
+    /**
+     * Performs one actual refresh: the network call plus any state/cookie
+     * updates. Must reject on failure; the rejection is classified via
+     * `extractHttpStatus`. Must be bounded (pass a fetch timeout) so a
+     * held Web Lock always releases
+     */
+    performRefresh: () => Promise<void>;
+    /** Reads the current access token from the live cookie source of truth */
+    readAccessToken: () => string | null;
+    /** Parses a JWT expiry to epoch ms, `null` when undecodable */
+    parseTokenExpiry: (token: string) => number | null;
+    policy: RefreshPolicy;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+    /** Returns `false` only when the browser is known to be offline */
+    isOnline?: () => boolean;
+    /** Web Locks manager; omit/`null` where unavailable (older browsers, SSR) */
+    locks?: RefreshLockManager | null;
+    lockName?: string;
+}
+export interface RefreshOrchestrator {
+    /**
+     * Ensures the access token is fresh, refreshing it if needed
+     *
+     * Concurrent callers share one in-flight promise (a single network
+     * request). Cross-tab callers are serialized by a Web Lock, and a
+     * caller that waited on the lock re-reads the cookie afterwards so it
+     * rides a sibling tab's rotation without its own network call.
+     * Transient failures back off and retry up to the policy cap;
+     * only a definitive 401/404 yields `auth-failed`
+     *
+     * @param options.force - Skip freshness checks and always hit the network
+     */
+    ensureFreshToken: (options?: {
+        force?: boolean;
+    }) => Promise<RefreshOutcome>;
+}
+export declare function createRefreshOrchestrator(deps: RefreshOrchestratorDeps): RefreshOrchestrator;

package/dist/runtime/helpers/refresh-orchestrator.js

@@ -0,0 +1,85 @@
+import { classifyRefreshStatus, computeBackoffDelay, extractHttpStatus } from "./refresh-policy.js";
+const DEFAULT_LOCK_NAME = "tela-auth-token-refresh";
+export function createRefreshOrchestrator(deps) {
+  const {
+    performRefresh,
+    readAccessToken,
+    parseTokenExpiry,
+    policy,
+    now = () => Date.now(),
+    sleep = async (ms) => await new Promise((resolve) => setTimeout(resolve, ms)),
+    random = Math.random,
+    isOnline = () => typeof navigator === "undefined" || navigator.onLine !== false,
+    locks = typeof navigator !== "undefined" && "locks" in navigator ? navigator.locks : null,
+    lockName = DEFAULT_LOCK_NAME
+  } = deps;
+  let inFlight = null;
+  function isTokenFresh() {
+    const token = readAccessToken();
+    if (!token) {
+      return false;
+    }
+    const expiry = parseTokenExpiry(token);
+    if (expiry === null) {
+      return false;
+    }
+    return expiry - now() > policy.refreshThresholdMs;
+  }
+  async function attemptWithinLock(force) {
+    if (!force && isTokenFresh()) {
+      return { kind: "ok", refreshed: false };
+    }
+    try {
+      await performRefresh();
+      return { kind: "ok", refreshed: true };
+    } catch (error) {
+      return { kind: "error", error };
+    }
+  }
+  async function attempt(force) {
+    if (locks) {
+      try {
+        return await locks.request(lockName, async () => await attemptWithinLock(force));
+      } catch {
+      }
+    }
+    return await attemptWithinLock(force);
+  }
+  async function run(force) {
+    try {
+      for (let retry = 0; ; retry++) {
+        if (!isOnline()) {
+          return { status: "skipped-offline" };
+        }
+        const result = await attempt(force);
+        if (result.kind === "ok") {
+          return { status: "ok", refreshed: result.refreshed };
+        }
+        const kind = classifyRefreshStatus(extractHttpStatus(result.error));
+        if (kind === "auth") {
+          return { status: "auth-failed", error: result.error };
+        }
+        if (retry >= policy.maxImmediateRetries) {
+          return { status: "transient-failed", error: result.error };
+        }
+        await sleep(computeBackoffDelay(retry, policy, random));
+      }
+    } catch (error) {
+      return { status: "transient-failed", error };
+    }
+  }
+  async function ensureFreshToken(options = {}) {
+    if (inFlight) {
+      return await inFlight;
+    }
+    const force = options.force ?? false;
+    if (!force && isTokenFresh()) {
+      return { status: "ok", refreshed: false };
+    }
+    inFlight = run(force).finally(() => {
+      inFlight = null;
+    });
+    return await inFlight;
+  }
+  return { ensureFreshToken };
+}

package/dist/runtime/helpers/refresh-policy.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure refresh policy: failure classification, status extraction,
+ * backoff math, and schedule math
+ */
+/** How a refresh failure should be handled */
+export type RefreshFailureKind = 'auth' | 'transient';
+/** Timing knobs shared by the orchestrator and the scheduler */
+export interface RefreshPolicy {
+    /** Refresh this long before the access token expires (ms) */
+    refreshThresholdMs: number;
+    /** How many immediate in-place retries a single refresh attempt gets */
+    maxImmediateRetries: number;
+    /** Base delay for exponential backoff between retries (ms) */
+    retryBaseDelayMs: number;
+    /** Upper bound for any backoff delay (ms) */
+    retryMaxDelayMs: number;
+    /** Hard floor between two scheduled refreshes (ms) */
+    minRefreshIntervalMs: number;
+}
+/** Default timing policy */
+export declare const DEFAULT_REFRESH_POLICY: RefreshPolicy;
+/**
+ * Classifies a refresh failure by HTTP status
+ *
+ * Only a definitive 401/404 means the session is gone. Everything else —
+ * 429, 5xx, other 4xx, or no status at all (network failure) — is
+ * transient and must never log the user out
+ */
+export declare function classifyRefreshStatus(status: number | undefined): RefreshFailureKind;
+/**
+ * Extracts an HTTP status code from an unknown error shape
+ *
+ * Checks, in order: `status`, `statusCode`, `response.status`, then the
+ * same fields on `cause` (recursively, so wrapped SDK errors still yield
+ * the upstream status). Returns `undefined` for pure transport failures
+ */
+export declare function extractHttpStatus(error: unknown, depth?: number): number | undefined;
+/**
+ * Computes a full-jitter exponential backoff delay
+ *
+ * @param attempt - Zero-based retry attempt number
+ * @param policy - Timing policy providing base and max delays
+ * @param random - Random source in [0, 1); injectable for deterministic tests
+ */
+export declare function computeBackoffDelay(attempt: number, policy: Pick<RefreshPolicy, 'retryBaseDelayMs' | 'retryMaxDelayMs'>, random?: () => number): number;
+/**
+ * Computes the delay until the next scheduled refresh from the access
+ * token's expiry, clamped to a hard minimum interval
+ *
+ * A `null` expiry (missing or undecodable token) and an already-passed
+ * expiry both return `minRefreshIntervalMs` — never 0 — so a stale
+ * cookie read can never spin the scheduler into a hot loop
+ */
+export declare function computeNextRefreshDelay(expiryMs: number | null, nowMs: number, policy: Pick<RefreshPolicy, 'refreshThresholdMs' | 'minRefreshIntervalMs'>): number;

package/dist/runtime/helpers/refresh-policy.js

@@ -0,0 +1,32 @@
+export const DEFAULT_REFRESH_POLICY = {
+  refreshThresholdMs: 2 * 60 * 1e3,
+  maxImmediateRetries: 3,
+  retryBaseDelayMs: 1e3,
+  retryMaxDelayMs: 3e4,
+  minRefreshIntervalMs: 5e3
+};
+export function classifyRefreshStatus(status) {
+  return status === 401 || status === 404 ? "auth" : "transient";
+}
+export function extractHttpStatus(error, depth = 0) {
+  if (!error || typeof error !== "object" || depth > 4) {
+    return void 0;
+  }
+  const candidate = error;
+  for (const value of [candidate.status, candidate.statusCode, candidate.response?.status]) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return extractHttpStatus(candidate.cause, depth + 1);
+}
+export function computeBackoffDelay(attempt, policy, random = Math.random) {
+  const exponential = Math.min(policy.retryMaxDelayMs, policy.retryBaseDelayMs * 2 ** Math.max(attempt, 0));
+  return Math.floor(random() * exponential);
+}
+export function computeNextRefreshDelay(expiryMs, nowMs, policy) {
+  if (expiryMs === null) {
+    return policy.minRefreshIntervalMs;
+  }
+  return Math.max(expiryMs - policy.refreshThresholdMs - nowMs, policy.minRefreshIntervalMs);
+}