@iqauth/sdk 2.6.4 → 2.8.1

package/dist/index.mjs

@@ -1,27 +1,38 @@
+import {
+  expandPermissions,
+  hasPermission
+} from "./chunk-GLXSIGVS.mjs";
 import {
   createProvisioningBridge
-} from "./chunk-SL3KRS4W.mjs";
+} from "./chunk-CIJORODR.mjs";
 import {
   createTestIssuer
-} from "./chunk-MKKZULZR.mjs";
+} from "./chunk-WIFG74IK.mjs";
 import {
+  IQAUTH_SIGNATURE_HEADER,
+  LEGACY_SIGNATURE_HEADERS,
   WebhookSignatureError,
   isValidWebhookSignature,
+  parseWebhookEvent,
   verifyWebhookSignature
-} from "./chunk-UKZLOHZG.mjs";
+} from "./chunk-VYQ3ETCK.mjs";
 import {
   verifyWsUpgrade
-} from "./chunk-3JULWS6F.mjs";
+} from "./chunk-WCELYTJ3.mjs";
 import {
   iqAuthMiddleware
-} from "./chunk-BVV54LPI.mjs";
+} from "./chunk-25SSYDIP.mjs";
+import {
+  buildUserinfoResponse,
+  handleUserinfo
+} from "./chunk-WSH4SW7F.mjs";
 import {
   assertPublishableKey,
   encodePublishableKey,
   isPublishableKey,
   isSecretKey,
   parsePublishableKey
-} from "./chunk-WQWBJSSS.mjs";
+} from "./chunk-HVHNYPDC.mjs";
 import {
   ApiKeysModule,
   AppsModule,
@@ -48,17 +59,18 @@ import {
   UsersModule,
   VendorsModule,
   WebhooksModule
-} from "./chunk-W3F4JYGP.mjs";
+} from "./chunk-ZLJPABB7.mjs";
 import {
   DEFAULT_CLOCK_TOLERANCE_SECONDS,
   DEFAULT_TOKEN_AUDIENCE,
   DEFAULT_TOKEN_ISSUER,
   TokensModule
-} from "./chunk-UNYDG2L4.mjs";
+} from "./chunk-NUO2I65G.mjs";
 import {
   ErrorCodes,
-  IQAuthError
-} from "./chunk-6I6RM4MN.mjs";
+  IQAuthError,
+  IQ_AUTH_ERROR_CODES
+} from "./chunk-6PJRLRB4.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
   ApiKeysModule,
@@ -73,10 +85,13 @@ export {
   ErrorCodes,
   GdprModule,
   HierarchyModule,
+  IQAUTH_SIGNATURE_HEADER,
   IQAuthClient,
   IQAuthError,
+  IQ_AUTH_ERROR_CODES,
   InMemoryOidcStateStore,
   InvitesModule,
+  LEGACY_SIGNATURE_HEADERS,
   MembershipsModule,
   MfaModule,
   OidcModule,
@@ -94,14 +109,19 @@ export {
   WebhookSignatureError,
   WebhooksModule,
   assertPublishableKey,
+  buildUserinfoResponse,
   createProvisioningBridge,
   createTestIssuer,
   encodePublishableKey,
+  expandPermissions,
+  handleUserinfo,
+  hasPermission,
   iqAuthMiddleware,
   isPublishableKey,
   isSecretKey,
   isValidWebhookSignature,
   parsePublishableKey,
+  parseWebhookEvent,
   verifyWebhookSignature,
   verifyWsUpgrade
 };

package/dist/{keys-NLWFAOEM.mjs → keys-6Y776TG2.mjs}

@@ -10,10 +10,10 @@ async function getCtx(flags) {
   const env = await loadEnv(flags.get("env-file") || ".env");
   const baseUrl = flags.get("base-url") || env.IQAUTH_ISSUER;
   const token = flags.get("token") || env.IQAUTH_ADMIN_TOKEN || env.IQAUTH_SECRET_KEY;
-  const app = flags.get("app") || env.IQAUTH_APP_ID || env.IQAUTH_APP_KEY;
+  const app = flags.get("app") || env.IQAUTH_APP_ID;
   if (!baseUrl) throw new Error("Missing --base-url (or IQAUTH_ISSUER in env).");
   if (!token) throw new Error("Missing --token (or IQAUTH_ADMIN_TOKEN / IQAUTH_SECRET_KEY in env).");
-  if (!app) throw new Error("Missing --app <appId|appKey> (or IQAUTH_APP_ID in env).");
+  if (!app) throw new Error("Missing --app <appId> (or IQAUTH_APP_ID in env). The `IQAUTH_APP_KEY` env-var fallback has been removed (Task #130) \u2014 pass --app explicitly.");
   return { baseUrl, token, app };
 }
 async function runKeys(argv) {

package/dist/locales.d.mts

@@ -1,4 +1,4 @@
-import { I as IQAuthLocaleBundle, a as IQAuthLocaleOverride, b as IQAuthLocaleKey } from './types-6bNdxesb.mjs';
+import { I as IQAuthLocaleBundle, b as IQAuthLocaleOverride, a as IQAuthLocaleKey } from './types-DnU2LhXR.mjs';
 
 declare const enUS: IQAuthLocaleBundle;
 

package/dist/locales.d.ts

@@ -1,4 +1,4 @@
-import { I as IQAuthLocaleBundle, a as IQAuthLocaleOverride, b as IQAuthLocaleKey } from './types-6bNdxesb.js';
+import { I as IQAuthLocaleBundle, b as IQAuthLocaleOverride, a as IQAuthLocaleKey } from './types-DnU2LhXR.js';
 
 declare const enUS: IQAuthLocaleBundle;
 

package/dist/locales.js

@@ -74,6 +74,7 @@ var enUS = {
   "signIn.useDifferentAccount": "Use a different account",
   "signIn.selectTenant": "Choose an organization",
   "signIn.selectTenantSubtitle": "You belong to multiple organizations. Pick one to continue.",
+  "signIn.selectScope": "Choose scope",
   "signIn.dividerOr": "or",
   "signIn.preparingExperience": "Preparing your sign-in experience.",
   "signIn.applicationUnavailable": "Application unavailable",
@@ -162,6 +163,11 @@ var enUS = {
   "orgSwitcher.createNew": "Create organization",
   "orgSwitcher.manage": "Manage organization",
   "orgSwitcher.noOrgs": "You don't belong to any organizations yet.",
+  "orgSwitcher.mfaRequiredTitle": "Two-factor verification required",
+  "orgSwitcher.mfaRequiredBody": "This organization requires an extra verification step. Continue in the hosted sign-in to finish switching.",
+  "orgSwitcher.scopeSelectionRequiredTitle": "Choose what to access",
+  "orgSwitcher.scopeSelectionRequiredBody": "This organization needs you to pick which workspace to open. Continue in the hosted sign-in to choose.",
+  "orgSwitcher.continueInHostedSignIn": "Continue in hosted sign-in \u2192",
   "orgProfile.title": "Organization settings",
   "orgProfile.generalTab": "General",
   "orgProfile.membersTab": "Members",
@@ -254,6 +260,7 @@ var frFR = {
   "signIn.useDifferentAccount": "Utiliser un autre compte",
   "signIn.selectTenant": "Choisir une organisation",
   "signIn.selectTenantSubtitle": "Vous appartenez \xE0 plusieurs organisations. Choisissez-en une pour continuer.",
+  "signIn.selectScope": "Choisir une port\xE9e",
   "signIn.dividerOr": "ou",
   "signIn.preparingExperience": "Pr\xE9paration de votre exp\xE9rience de connexion.",
   "signIn.applicationUnavailable": "Application indisponible",
@@ -342,6 +349,11 @@ var frFR = {
   "orgSwitcher.createNew": "Cr\xE9er une organisation",
   "orgSwitcher.manage": "G\xE9rer l'organisation",
   "orgSwitcher.noOrgs": "Vous n'appartenez encore \xE0 aucune organisation.",
+  "orgSwitcher.mfaRequiredTitle": "V\xE9rification en deux \xE9tapes requise",
+  "orgSwitcher.mfaRequiredBody": "Cette organisation n\xE9cessite une \xE9tape de v\xE9rification suppl\xE9mentaire. Poursuivez sur la page de connexion h\xE9berg\xE9e pour terminer le changement.",
+  "orgSwitcher.scopeSelectionRequiredTitle": "Choisir l'espace \xE0 ouvrir",
+  "orgSwitcher.scopeSelectionRequiredBody": "Cette organisation n\xE9cessite que vous choisissiez un espace de travail. Poursuivez sur la page de connexion h\xE9berg\xE9e pour choisir.",
+  "orgSwitcher.continueInHostedSignIn": "Continuer sur la connexion h\xE9berg\xE9e \u2192",
   "orgProfile.title": "Param\xE8tres de l'organisation",
   "orgProfile.generalTab": "G\xE9n\xE9ral",
   "orgProfile.membersTab": "Membres",
@@ -434,6 +446,7 @@ var esES = {
   "signIn.useDifferentAccount": "Usar otra cuenta",
   "signIn.selectTenant": "Elige una organizaci\xF3n",
   "signIn.selectTenantSubtitle": "Perteneces a varias organizaciones. Selecciona una para continuar.",
+  "signIn.selectScope": "Elegir \xE1mbito",
   "signIn.dividerOr": "o",
   "signIn.preparingExperience": "Preparando tu experiencia de inicio de sesi\xF3n.",
   "signIn.applicationUnavailable": "Aplicaci\xF3n no disponible",
@@ -522,6 +535,11 @@ var esES = {
   "orgSwitcher.createNew": "Crear organizaci\xF3n",
   "orgSwitcher.manage": "Gestionar organizaci\xF3n",
   "orgSwitcher.noOrgs": "A\xFAn no perteneces a ninguna organizaci\xF3n.",
+  "orgSwitcher.mfaRequiredTitle": "Se requiere verificaci\xF3n en dos pasos",
+  "orgSwitcher.mfaRequiredBody": "Esta organizaci\xF3n requiere un paso de verificaci\xF3n adicional. Contin\xFAa en el inicio de sesi\xF3n alojado para completar el cambio.",
+  "orgSwitcher.scopeSelectionRequiredTitle": "Elige a qu\xE9 acceder",
+  "orgSwitcher.scopeSelectionRequiredBody": "Esta organizaci\xF3n requiere que elijas un espacio de trabajo. Contin\xFAa en el inicio de sesi\xF3n alojado para elegir.",
+  "orgSwitcher.continueInHostedSignIn": "Continuar en el inicio de sesi\xF3n alojado \u2192",
   "orgProfile.title": "Configuraci\xF3n de la organizaci\xF3n",
   "orgProfile.generalTab": "Generales",
   "orgProfile.membersTab": "Miembros",
@@ -614,6 +632,7 @@ var deDE = {
   "signIn.useDifferentAccount": "Anderes Konto verwenden",
   "signIn.selectTenant": "Organisation ausw\xE4hlen",
   "signIn.selectTenantSubtitle": "Sie geh\xF6ren zu mehreren Organisationen. Bitte w\xE4hlen Sie eine aus.",
+  "signIn.selectScope": "Bereich ausw\xE4hlen",
   "signIn.preparingExperience": "Anmeldung wird vorbereitet.",
   "signIn.applicationUnavailable": "Anwendung nicht verf\xFCgbar",
   "signIn.applicationNotFound": "Anwendung nicht gefunden",
@@ -702,6 +721,11 @@ var deDE = {
   "orgSwitcher.createNew": "Organisation erstellen",
   "orgSwitcher.manage": "Organisation verwalten",
   "orgSwitcher.noOrgs": "Sie geh\xF6ren noch keiner Organisation an.",
+  "orgSwitcher.mfaRequiredTitle": "Zwei-Faktor-Verifizierung erforderlich",
+  "orgSwitcher.mfaRequiredBody": "Diese Organisation erfordert einen zus\xE4tzlichen Verifizierungsschritt. Fahren Sie in der gehosteten Anmeldung fort, um den Wechsel abzuschlie\xDFen.",
+  "orgSwitcher.scopeSelectionRequiredTitle": "Zugriff ausw\xE4hlen",
+  "orgSwitcher.scopeSelectionRequiredBody": "F\xFCr diese Organisation m\xFCssen Sie einen Arbeitsbereich ausw\xE4hlen. Fahren Sie in der gehosteten Anmeldung fort, um auszuw\xE4hlen.",
+  "orgSwitcher.continueInHostedSignIn": "In der gehosteten Anmeldung fortfahren \u2192",
   "orgProfile.title": "Organisationseinstellungen",
   "orgProfile.generalTab": "Allgemein",
   "orgProfile.membersTab": "Mitglieder",
@@ -794,6 +818,7 @@ var jaJP = {
   "signIn.useDifferentAccount": "\u5225\u306E\u30A2\u30AB\u30A6\u30F3\u30C8\u3092\u4F7F\u7528",
   "signIn.selectTenant": "\u7D44\u7E54\u3092\u9078\u629E",
   "signIn.selectTenantSubtitle": "\u8907\u6570\u306E\u7D44\u7E54\u306B\u6240\u5C5E\u3057\u3066\u3044\u307E\u3059\u3002\u7D9A\u3051\u308B\u306B\u306F 1 \u3064\u3092\u9078\u629E\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+  "signIn.selectScope": "\u30B9\u30B3\u30FC\u30D7\u3092\u9078\u629E",
   "signIn.preparingExperience": "\u30B5\u30A4\u30F3\u30A4\u30F3\u306E\u6E96\u5099\u3092\u3057\u3066\u3044\u307E\u3059\u3002",
   "signIn.applicationUnavailable": "\u30A2\u30D7\u30EA\u30B1\u30FC\u30B7\u30E7\u30F3\u3092\u5229\u7528\u3067\u304D\u307E\u305B\u3093",
   "signIn.applicationNotFound": "\u30A2\u30D7\u30EA\u30B1\u30FC\u30B7\u30E7\u30F3\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093",
@@ -882,6 +907,11 @@ var jaJP = {
   "orgSwitcher.createNew": "\u7D44\u7E54\u3092\u4F5C\u6210",
   "orgSwitcher.manage": "\u7D44\u7E54\u3092\u7BA1\u7406",
   "orgSwitcher.noOrgs": "\u307E\u3060\u3069\u306E\u7D44\u7E54\u306B\u3082\u6240\u5C5E\u3057\u3066\u3044\u307E\u305B\u3093\u3002",
+  "orgSwitcher.mfaRequiredTitle": "\u4E8C\u6BB5\u968E\u8A8D\u8A3C\u304C\u5FC5\u8981\u3067\u3059",
+  "orgSwitcher.mfaRequiredBody": "\u3053\u306E\u7D44\u7E54\u3067\u306F\u8FFD\u52A0\u306E\u672C\u4EBA\u78BA\u8A8D\u304C\u5FC5\u8981\u3067\u3059\u3002\u30DB\u30B9\u30C8\u3055\u308C\u305F\u30B5\u30A4\u30F3\u30A4\u30F3\u3067\u7D9A\u3051\u3066\u5207\u308A\u66FF\u3048\u3092\u5B8C\u4E86\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+  "orgSwitcher.scopeSelectionRequiredTitle": "\u30A2\u30AF\u30BB\u30B9\u5148\u3092\u9078\u629E",
+  "orgSwitcher.scopeSelectionRequiredBody": "\u3053\u306E\u7D44\u7E54\u3067\u306F\u30EF\u30FC\u30AF\u30B9\u30DA\u30FC\u30B9\u306E\u9078\u629E\u304C\u5FC5\u8981\u3067\u3059\u3002\u30DB\u30B9\u30C8\u3055\u308C\u305F\u30B5\u30A4\u30F3\u30A4\u30F3\u3067\u9078\u629E\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+  "orgSwitcher.continueInHostedSignIn": "\u30DB\u30B9\u30C8\u3055\u308C\u305F\u30B5\u30A4\u30F3\u30A4\u30F3\u306B\u9032\u3080 \u2192",
   "orgProfile.title": "\u7D44\u7E54\u306E\u8A2D\u5B9A",
   "orgProfile.generalTab": "\u4E00\u822C",
   "orgProfile.membersTab": "\u30E1\u30F3\u30D0\u30FC",
@@ -974,6 +1004,7 @@ var ptBR = {
   "signIn.useDifferentAccount": "Usar outra conta",
   "signIn.selectTenant": "Escolher uma organiza\xE7\xE3o",
   "signIn.selectTenantSubtitle": "Voc\xEA pertence a v\xE1rias organiza\xE7\xF5es. Escolha uma para continuar.",
+  "signIn.selectScope": "Escolher escopo",
   "signIn.preparingExperience": "Preparando sua experi\xEAncia de login.",
   "signIn.applicationUnavailable": "Aplicativo indispon\xEDvel",
   "signIn.applicationNotFound": "Aplicativo n\xE3o encontrado",
@@ -1061,6 +1092,11 @@ var ptBR = {
   "orgSwitcher.personal": "Conta pessoal",
   "orgSwitcher.createNew": "Criar organiza\xE7\xE3o",
   "orgSwitcher.manage": "Gerenciar organiza\xE7\xE3o",
+  "orgSwitcher.mfaRequiredTitle": "Verifica\xE7\xE3o em duas etapas necess\xE1ria",
+  "orgSwitcher.mfaRequiredBody": "Esta organiza\xE7\xE3o requer uma etapa de verifica\xE7\xE3o adicional. Continue no login hospedado para concluir a troca.",
+  "orgSwitcher.scopeSelectionRequiredTitle": "Escolha o que acessar",
+  "orgSwitcher.scopeSelectionRequiredBody": "Esta organiza\xE7\xE3o exige que voc\xEA escolha um espa\xE7o de trabalho. Continue no login hospedado para escolher.",
+  "orgSwitcher.continueInHostedSignIn": "Continuar no login hospedado \u2192",
   "orgSwitcher.noOrgs": "Voc\xEA ainda n\xE3o pertence a nenhuma organiza\xE7\xE3o.",
   "orgProfile.title": "Configura\xE7\xF5es da organiza\xE7\xE3o",
   "orgProfile.generalTab": "Geral",

package/dist/locales.mjs

@@ -11,7 +11,7 @@ import {
   ptBR,
   resolveBundle,
   t
-} from "./chunk-5T7GHBX6.mjs";
+} from "./chunk-TLET552H.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 export {
   builtInLocales,

package/dist/mobile.d.mts

@@ -1,11 +1,81 @@
-import { I as IQAuthClient } from './client-kYlJFgPv.mjs';
-import { b as IQAuthTokenClientConfig } from './types-DZAflmmq.mjs';
-export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
-import './tokens-DCyzzn8L.mjs';
+import { I as IQAuthClient } from './client-D8L-PaWr.mjs';
+import { f as IQAuthTokenClientConfig } from './types-Bn8O-OEd.mjs';
+export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.mjs';
+import './tokens-B06VtvUi.mjs';
 
+/**
+ * Mobile client — wraps IQAuthClient with React Native / Expo–aware behavior.
+ *
+ * Notable mode: `autoRefresh: 'app-state'`
+ *   The default per-request "expiring soon" proactive refresh fights with
+ *   Expo / React Native's app-suspension lifecycle (the JS engine pauses in
+ *   background, fetch in-flight when the OS suspends the app fails on resume,
+ *   and the resulting cascade of refresh attempts can blow up with
+ *   `Network request failed` rather than recovering cleanly).
+ *
+ *   In `'app-state'` mode the SDK:
+ *     - DISABLES the per-request proactive refresh.
+ *     - KEEPS the reactive 401 retry on TOKEN_EXPIRED (one attempt).
+ *     - SUBSCRIBES to `AppState.addEventListener('change', ...)` and triggers
+ *       a refresh when the app transitions back to `'active'` from background
+ *       or inactive — but only if a refresh token exists and the access token
+ *       is within 5 minutes of expiry (or already expired).
+ *
+ *   The AppState listener is started automatically when `'app-state'` mode is
+ *   selected and react-native is resolvable. Call `client.stop()` to remove
+ *   the subscription (e.g. in a unit test or on logout).
+ */
+
+type AppStateStatus = "active" | "background" | "inactive" | string;
+interface AppStateLike {
+    currentState: AppStateStatus;
+    addEventListener(type: "change", handler: (state: AppStateStatus) => void): {
+        remove: () => void;
+    } | (() => void) | void;
+    removeEventListener?: (type: "change", handler: (state: AppStateStatus) => void) => void;
+}
+interface MobileClientOptions extends IQAuthTokenClientConfig {
+    /**
+     * Override how AppState is resolved. Defaults to a runtime
+     * `require('react-native').AppState`. Tests inject a fake here.
+     */
+    appState?: AppStateLike | null;
+    /**
+     * Seconds-of-life-remaining threshold below which a foreground transition
+     * triggers a refresh. Default 300 (5 min).
+     */
+    appStateRefreshLeewaySeconds?: number;
+    /**
+     * Optional hook invoked when an AppState-triggered refresh fails. The
+     * default behavior is to swallow the error so the host app doesn't crash
+     * on a foreground tick — the next API call's reactive 401 path will
+     * surface the same error to the caller. Use this hook for telemetry.
+     */
+    onAppStateRefreshError?: (err: unknown) => void;
+}
 declare class MobileIQAuthClient extends IQAuthClient {
-    constructor(config: IQAuthTokenClientConfig);
+    private appStateSub;
+    private appStateMode;
+    private leewaySeconds;
+    private lastAppState;
+    private refreshing;
+    private onTokenRefreshCb?;
+    private onAppStateRefreshError?;
+    constructor(config: MobileClientOptions);
+    /** True iff the client is configured for AppState-driven refresh. */
+    get isAppStateMode(): boolean;
+    private startAppStateListener;
+    /**
+     * Public hook: call this from your own AppState handler if you've passed
+     * `appState: null` to opt out of the auto-subscription. Returns true if a
+     * refresh was attempted.
+     */
+    refreshIfStale(): Promise<boolean>;
+    private maybeRefreshOnForeground;
+    private isAccessTokenStale;
+    /** Remove the AppState subscription. Idempotent. */
+    stop(): void;
 }
-declare function createMobileClient(config: IQAuthTokenClientConfig): MobileIQAuthClient;
+declare function createMobileClient(config: MobileClientOptions): MobileIQAuthClient;
 
-export { IQAuthClient, IQAuthTokenClientConfig, MobileIQAuthClient, createMobileClient };
+export { IQAuthClient, IQAuthTokenClientConfig, type MobileClientOptions, MobileIQAuthClient, createMobileClient };

package/dist/mobile.d.ts

@@ -1,11 +1,81 @@
-import { I as IQAuthClient } from './client-BNQe3AgF.js';
-import { b as IQAuthTokenClientConfig } from './types-DZAflmmq.js';
-export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
-import './tokens-aHiGFr_E.js';
+import { I as IQAuthClient } from './client-DkPL0EPZ.js';
+import { f as IQAuthTokenClientConfig } from './types-Bn8O-OEd.js';
+export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.js';
+import './tokens-9F6ETrzk.js';
 
+/**
+ * Mobile client — wraps IQAuthClient with React Native / Expo–aware behavior.
+ *
+ * Notable mode: `autoRefresh: 'app-state'`
+ *   The default per-request "expiring soon" proactive refresh fights with
+ *   Expo / React Native's app-suspension lifecycle (the JS engine pauses in
+ *   background, fetch in-flight when the OS suspends the app fails on resume,
+ *   and the resulting cascade of refresh attempts can blow up with
+ *   `Network request failed` rather than recovering cleanly).
+ *
+ *   In `'app-state'` mode the SDK:
+ *     - DISABLES the per-request proactive refresh.
+ *     - KEEPS the reactive 401 retry on TOKEN_EXPIRED (one attempt).
+ *     - SUBSCRIBES to `AppState.addEventListener('change', ...)` and triggers
+ *       a refresh when the app transitions back to `'active'` from background
+ *       or inactive — but only if a refresh token exists and the access token
+ *       is within 5 minutes of expiry (or already expired).
+ *
+ *   The AppState listener is started automatically when `'app-state'` mode is
+ *   selected and react-native is resolvable. Call `client.stop()` to remove
+ *   the subscription (e.g. in a unit test or on logout).
+ */
+
+type AppStateStatus = "active" | "background" | "inactive" | string;
+interface AppStateLike {
+    currentState: AppStateStatus;
+    addEventListener(type: "change", handler: (state: AppStateStatus) => void): {
+        remove: () => void;
+    } | (() => void) | void;
+    removeEventListener?: (type: "change", handler: (state: AppStateStatus) => void) => void;
+}
+interface MobileClientOptions extends IQAuthTokenClientConfig {
+    /**
+     * Override how AppState is resolved. Defaults to a runtime
+     * `require('react-native').AppState`. Tests inject a fake here.
+     */
+    appState?: AppStateLike | null;
+    /**
+     * Seconds-of-life-remaining threshold below which a foreground transition
+     * triggers a refresh. Default 300 (5 min).
+     */
+    appStateRefreshLeewaySeconds?: number;
+    /**
+     * Optional hook invoked when an AppState-triggered refresh fails. The
+     * default behavior is to swallow the error so the host app doesn't crash
+     * on a foreground tick — the next API call's reactive 401 path will
+     * surface the same error to the caller. Use this hook for telemetry.
+     */
+    onAppStateRefreshError?: (err: unknown) => void;
+}
 declare class MobileIQAuthClient extends IQAuthClient {
-    constructor(config: IQAuthTokenClientConfig);
+    private appStateSub;
+    private appStateMode;
+    private leewaySeconds;
+    private lastAppState;
+    private refreshing;
+    private onTokenRefreshCb?;
+    private onAppStateRefreshError?;
+    constructor(config: MobileClientOptions);
+    /** True iff the client is configured for AppState-driven refresh. */
+    get isAppStateMode(): boolean;
+    private startAppStateListener;
+    /**
+     * Public hook: call this from your own AppState handler if you've passed
+     * `appState: null` to opt out of the auto-subscription. Returns true if a
+     * refresh was attempted.
+     */
+    refreshIfStale(): Promise<boolean>;
+    private maybeRefreshOnForeground;
+    private isAccessTokenStale;
+    /** Remove the AppState subscription. Idempotent. */
+    stop(): void;
 }
-declare function createMobileClient(config: IQAuthTokenClientConfig): MobileIQAuthClient;
+declare function createMobileClient(config: MobileClientOptions): MobileIQAuthClient;
 
-export { IQAuthClient, IQAuthTokenClientConfig, MobileIQAuthClient, createMobileClient };
+export { IQAuthClient, IQAuthTokenClientConfig, type MobileClientOptions, MobileIQAuthClient, createMobileClient };