@feelflow/ffid-sdk 5.24.1 → 5.24.3

package/dist/{chunk-L5SBAHY3.cjs → chunk-AMVL7J2G.cjs}

@@ -1228,8 +1228,35 @@ function createNonContractMethods(deps) {
   };
 }
 
+// src/shared/token-response.ts
+function invalidTokenFields(tokenResponse) {
+  const invalid = [];
+  if (typeof tokenResponse.access_token !== "string" || tokenResponse.access_token.length === 0) {
+    invalid.push("access_token");
+  }
+  if (typeof tokenResponse.refresh_token !== "string" || tokenResponse.refresh_token.length === 0) {
+    invalid.push("refresh_token");
+  }
+  if (typeof tokenResponse.expires_in !== "number" || !Number.isFinite(tokenResponse.expires_in) || tokenResponse.expires_in <= 0) {
+    invalid.push("expires_in");
+  }
+  return invalid;
+}
+function hasValidatedTokens(tokenResponse) {
+  return invalidTokenFields(tokenResponse).length === 0;
+}
+function validateTokenResponse(tokenResponse) {
+  if (hasValidatedTokens(tokenResponse)) {
+    return { ok: true, tokens: tokenResponse };
+  }
+  return {
+    ok: false,
+    message: `\u30C8\u30FC\u30AF\u30F3\u30EC\u30B9\u30DD\u30F3\u30B9\u306B\u4E0D\u6B63\u306A\u30D5\u30A3\u30FC\u30EB\u30C9\u304C\u3042\u308A\u307E\u3059: ${invalidTokenFields(tokenResponse).join(", ")}`
+  };
+}
+
 // src/client/version-check.ts
-var SDK_VERSION = "5.24.1";
+var SDK_VERSION = "5.24.3";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1276,22 +1303,6 @@ npm install @feelflow/ffid-sdk@latest \u3067\u30A2\u30C3\u30D7\u30C7\u30FC\u30C8
 var OAUTH_TOKEN_ENDPOINT = "/api/v1/oauth/token";
 var OAUTH_REVOKE_ENDPOINT = "/api/v1/oauth/revoke";
 var MS_PER_SECOND = 1e3;
-function validateTokenResponse(tokenResponse) {
-  const invalid = [];
-  if (!tokenResponse.access_token) {
-    invalid.push("access_token");
-  }
-  if (!tokenResponse.refresh_token) {
-    invalid.push("refresh_token");
-  }
-  if (typeof tokenResponse.expires_in !== "number" || !Number.isFinite(tokenResponse.expires_in) || tokenResponse.expires_in <= 0) {
-    invalid.push("expires_in");
-  }
-  if (invalid.length > 0) {
-    return `\u30C8\u30FC\u30AF\u30F3\u30EC\u30B9\u30DD\u30F3\u30B9\u306B\u4E0D\u6B63\u306A\u30D5\u30A3\u30FC\u30EB\u30C9\u304C\u3042\u308A\u307E\u3059: ${invalid.join(", ")}`;
-  }
-  return null;
-}
 function createOAuthTokenMethods(deps) {
   const {
     baseUrl,
@@ -1379,20 +1390,20 @@ function createOAuthTokenMethods(deps) {
         }
       };
     }
-    const validationError = validateTokenResponse(tokenResponse);
-    if (validationError) {
-      logger.error("Token exchange validation failed:", validationError);
+    const validation = validateTokenResponse(tokenResponse);
+    if (!validation.ok) {
+      logger.error("Token exchange validation failed:", validation.message);
       return {
         error: {
           code: errorCodes.TOKEN_EXCHANGE_ERROR,
-          message: validationError
+          message: validation.message
         }
       };
     }
     tokenStore.setTokens({
-      accessToken: tokenResponse.access_token,
-      refreshToken: tokenResponse.refresh_token,
-      expiresAt: Date.now() + tokenResponse.expires_in * MS_PER_SECOND
+      accessToken: validation.tokens.access_token,
+      refreshToken: validation.tokens.refresh_token,
+      expiresAt: Date.now() + validation.tokens.expires_in * MS_PER_SECOND
     });
     logger.debug("Token exchange successful");
     return { data: void 0 };
@@ -1457,20 +1468,20 @@ function createOAuthTokenMethods(deps) {
         }
       };
     }
-    const validationError = validateTokenResponse(tokenResponse);
-    if (validationError) {
-      logger.error("Token refresh validation failed:", validationError);
+    const validation = validateTokenResponse(tokenResponse);
+    if (!validation.ok) {
+      logger.error("Token refresh validation failed:", validation.message);
       return {
         error: {
           code: errorCodes.TOKEN_REFRESH_ERROR,
-          message: validationError
+          message: validation.message
         }
       };
     }
     tokenStore.setTokens({
-      accessToken: tokenResponse.access_token,
-      refreshToken: tokenResponse.refresh_token,
-      expiresAt: Date.now() + tokenResponse.expires_in * MS_PER_SECOND
+      accessToken: validation.tokens.access_token,
+      refreshToken: validation.tokens.refresh_token,
+      expiresAt: Date.now() + validation.tokens.expires_in * MS_PER_SECOND
     });
     logger.debug("Token refresh successful");
     return { data: void 0 };
@@ -3012,10 +3023,16 @@ function createFFIDClient(config) {
   }
   const logger = config.logger ?? (config.debug ? consoleLogger : noopLogger);
   const resolvedRedirectUri = resolveRedirectUri(rawRedirectUri, logger);
-  const tokenStore = authMode === "token" ? createTokenStore() : createTokenStore("memory");
+  const tokenStore = authMode === "token" ? config.tokenStore ?? createTokenStore() : createTokenStore("memory");
   function createError(code, message) {
     return { code, message };
   }
+  function getAccessToken() {
+    if (authMode !== "token") return null;
+    if (tokenStore.isAccessTokenExpired()) return null;
+    const accessToken = tokenStore.getTokens()?.accessToken;
+    return accessToken && accessToken.length > 0 ? accessToken : null;
+  }
   function buildFetchOptions(options, authOverride) {
     if (authOverride) {
       return {
@@ -3425,6 +3442,11 @@ function createFFIDClient(config) {
     inquiry,
     /** Token store (token mode only) */
     tokenStore,
+    /**
+     * Return the currently-valid access token, or null (token mode only; #4318).
+     * Live-reads the store and applies the 30s expiry buffer.
+     */
+    getAccessToken,
     /** Resolved auth mode */
     authMode,
     /** Resolved logger instance */
@@ -3549,6 +3571,7 @@ function FFIDProvider({
   authMode,
   clientId,
   timeout,
+  tokenStore,
   cleanCallbackUrl = true
 }) {
   const [user, setUser] = react.useState(null);
@@ -3574,9 +3597,10 @@ function FFIDProvider({
       logger,
       authMode,
       clientId,
-      timeout
+      timeout,
+      tokenStore
     }),
-    [serviceCode, scope, apiBaseUrl, debug, logger, authMode, clientId, timeout]
+    [serviceCode, scope, apiBaseUrl, debug, logger, authMode, clientId, timeout, tokenStore]
   );
   const refresh = react.useCallback(async () => {
     client.logger.debug("Refreshing session...");
@@ -3790,7 +3814,10 @@ function FFIDProvider({
       login,
       logout,
       switchOrganization,
-      refresh
+      refresh,
+      // Stable across renders (client is memoized): live-reads the shared store
+      // so refreshed/cleared tokens are reflected without host polling (#4318).
+      getAccessToken: client.getAccessToken
     }),
     [
       user,
@@ -3802,7 +3829,8 @@ function FFIDProvider({
       login,
       logout,
       switchOrganization,
-      refresh
+      refresh,
+      client
     ]
   );
   return /* @__PURE__ */ jsxRuntime.jsx(FFIDClientContext.Provider, { value: client, children: /* @__PURE__ */ jsxRuntime.jsx(FFIDContext.Provider, { value: contextValue, children }) });
@@ -3841,6 +3869,7 @@ function useFFID() {
     switchAccount: client.switchAccount,
     switchOrganization: context.switchOrganization,
     refresh: context.refresh,
+    getAccessToken: context.getAccessToken,
     getLoginUrl: client.getLoginUrl,
     getSignupUrl: client.getSignupUrl,
     getSubscribeUrl: client.getSubscribeUrl,

package/dist/{chunk-C4RNFEME.js → chunk-O3HGRALD.js}

@@ -1226,8 +1226,35 @@ function createNonContractMethods(deps) {
   };
 }
 
+// src/shared/token-response.ts
+function invalidTokenFields(tokenResponse) {
+  const invalid = [];
+  if (typeof tokenResponse.access_token !== "string" || tokenResponse.access_token.length === 0) {
+    invalid.push("access_token");
+  }
+  if (typeof tokenResponse.refresh_token !== "string" || tokenResponse.refresh_token.length === 0) {
+    invalid.push("refresh_token");
+  }
+  if (typeof tokenResponse.expires_in !== "number" || !Number.isFinite(tokenResponse.expires_in) || tokenResponse.expires_in <= 0) {
+    invalid.push("expires_in");
+  }
+  return invalid;
+}
+function hasValidatedTokens(tokenResponse) {
+  return invalidTokenFields(tokenResponse).length === 0;
+}
+function validateTokenResponse(tokenResponse) {
+  if (hasValidatedTokens(tokenResponse)) {
+    return { ok: true, tokens: tokenResponse };
+  }
+  return {
+    ok: false,
+    message: `\u30C8\u30FC\u30AF\u30F3\u30EC\u30B9\u30DD\u30F3\u30B9\u306B\u4E0D\u6B63\u306A\u30D5\u30A3\u30FC\u30EB\u30C9\u304C\u3042\u308A\u307E\u3059: ${invalidTokenFields(tokenResponse).join(", ")}`
+  };
+}
+
 // src/client/version-check.ts
-var SDK_VERSION = "5.24.1";
+var SDK_VERSION = "5.24.3";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1274,22 +1301,6 @@ npm install @feelflow/ffid-sdk@latest \u3067\u30A2\u30C3\u30D7\u30C7\u30FC\u30C8
 var OAUTH_TOKEN_ENDPOINT = "/api/v1/oauth/token";
 var OAUTH_REVOKE_ENDPOINT = "/api/v1/oauth/revoke";
 var MS_PER_SECOND = 1e3;
-function validateTokenResponse(tokenResponse) {
-  const invalid = [];
-  if (!tokenResponse.access_token) {
-    invalid.push("access_token");
-  }
-  if (!tokenResponse.refresh_token) {
-    invalid.push("refresh_token");
-  }
-  if (typeof tokenResponse.expires_in !== "number" || !Number.isFinite(tokenResponse.expires_in) || tokenResponse.expires_in <= 0) {
-    invalid.push("expires_in");
-  }
-  if (invalid.length > 0) {
-    return `\u30C8\u30FC\u30AF\u30F3\u30EC\u30B9\u30DD\u30F3\u30B9\u306B\u4E0D\u6B63\u306A\u30D5\u30A3\u30FC\u30EB\u30C9\u304C\u3042\u308A\u307E\u3059: ${invalid.join(", ")}`;
-  }
-  return null;
-}
 function createOAuthTokenMethods(deps) {
   const {
     baseUrl,
@@ -1377,20 +1388,20 @@ function createOAuthTokenMethods(deps) {
         }
       };
     }
-    const validationError = validateTokenResponse(tokenResponse);
-    if (validationError) {
-      logger.error("Token exchange validation failed:", validationError);
+    const validation = validateTokenResponse(tokenResponse);
+    if (!validation.ok) {
+      logger.error("Token exchange validation failed:", validation.message);
       return {
         error: {
           code: errorCodes.TOKEN_EXCHANGE_ERROR,
-          message: validationError
+          message: validation.message
         }
       };
     }
     tokenStore.setTokens({
-      accessToken: tokenResponse.access_token,
-      refreshToken: tokenResponse.refresh_token,
-      expiresAt: Date.now() + tokenResponse.expires_in * MS_PER_SECOND
+      accessToken: validation.tokens.access_token,
+      refreshToken: validation.tokens.refresh_token,
+      expiresAt: Date.now() + validation.tokens.expires_in * MS_PER_SECOND
     });
     logger.debug("Token exchange successful");
     return { data: void 0 };
@@ -1455,20 +1466,20 @@ function createOAuthTokenMethods(deps) {
         }
       };
     }
-    const validationError = validateTokenResponse(tokenResponse);
-    if (validationError) {
-      logger.error("Token refresh validation failed:", validationError);
+    const validation = validateTokenResponse(tokenResponse);
+    if (!validation.ok) {
+      logger.error("Token refresh validation failed:", validation.message);
       return {
         error: {
           code: errorCodes.TOKEN_REFRESH_ERROR,
-          message: validationError
+          message: validation.message
         }
       };
     }
     tokenStore.setTokens({
-      accessToken: tokenResponse.access_token,
-      refreshToken: tokenResponse.refresh_token,
-      expiresAt: Date.now() + tokenResponse.expires_in * MS_PER_SECOND
+      accessToken: validation.tokens.access_token,
+      refreshToken: validation.tokens.refresh_token,
+      expiresAt: Date.now() + validation.tokens.expires_in * MS_PER_SECOND
     });
     logger.debug("Token refresh successful");
     return { data: void 0 };
@@ -3010,10 +3021,16 @@ function createFFIDClient(config) {
   }
   const logger = config.logger ?? (config.debug ? consoleLogger : noopLogger);
   const resolvedRedirectUri = resolveRedirectUri(rawRedirectUri, logger);
-  const tokenStore = authMode === "token" ? createTokenStore() : createTokenStore("memory");
+  const tokenStore = authMode === "token" ? config.tokenStore ?? createTokenStore() : createTokenStore("memory");
   function createError(code, message) {
     return { code, message };
   }
+  function getAccessToken() {
+    if (authMode !== "token") return null;
+    if (tokenStore.isAccessTokenExpired()) return null;
+    const accessToken = tokenStore.getTokens()?.accessToken;
+    return accessToken && accessToken.length > 0 ? accessToken : null;
+  }
   function buildFetchOptions(options, authOverride) {
     if (authOverride) {
       return {
@@ -3423,6 +3440,11 @@ function createFFIDClient(config) {
     inquiry,
     /** Token store (token mode only) */
     tokenStore,
+    /**
+     * Return the currently-valid access token, or null (token mode only; #4318).
+     * Live-reads the store and applies the 30s expiry buffer.
+     */
+    getAccessToken,
     /** Resolved auth mode */
     authMode,
     /** Resolved logger instance */
@@ -3547,6 +3569,7 @@ function FFIDProvider({
   authMode,
   clientId,
   timeout,
+  tokenStore,
   cleanCallbackUrl = true
 }) {
   const [user, setUser] = useState(null);
@@ -3572,9 +3595,10 @@ function FFIDProvider({
       logger,
       authMode,
       clientId,
-      timeout
+      timeout,
+      tokenStore
     }),
-    [serviceCode, scope, apiBaseUrl, debug, logger, authMode, clientId, timeout]
+    [serviceCode, scope, apiBaseUrl, debug, logger, authMode, clientId, timeout, tokenStore]
   );
   const refresh = useCallback(async () => {
     client.logger.debug("Refreshing session...");
@@ -3788,7 +3812,10 @@ function FFIDProvider({
       login,
       logout,
       switchOrganization,
-      refresh
+      refresh,
+      // Stable across renders (client is memoized): live-reads the shared store
+      // so refreshed/cleared tokens are reflected without host polling (#4318).
+      getAccessToken: client.getAccessToken
     }),
     [
       user,
@@ -3800,7 +3827,8 @@ function FFIDProvider({
       login,
       logout,
       switchOrganization,
-      refresh
+      refresh,
+      client
     ]
   );
   return /* @__PURE__ */ jsx(FFIDClientContext.Provider, { value: client, children: /* @__PURE__ */ jsx(FFIDContext.Provider, { value: contextValue, children }) });
@@ -3839,6 +3867,7 @@ function useFFID() {
     switchAccount: client.switchAccount,
     switchOrganization: context.switchOrganization,
     refresh: context.refresh,
+    getAccessToken: context.getAccessToken,
     getLoginUrl: client.getLoginUrl,
     getSignupUrl: client.getSignupUrl,
     getSubscribeUrl: client.getSubscribeUrl,

package/dist/components/index.cjs

@@ -1,34 +1,34 @@
 'use strict';
 
-var chunkL5SBAHY3_cjs = require('../chunk-L5SBAHY3.cjs');
+var chunkAMVL7J2G_cjs = require('../chunk-AMVL7J2G.cjs');
 
 
 
 Object.defineProperty(exports, "FFIDAnnouncementBadge", {
   enumerable: true,
-  get: function () { return chunkL5SBAHY3_cjs.FFIDAnnouncementBadge; }
+  get: function () { return chunkAMVL7J2G_cjs.FFIDAnnouncementBadge; }
 });
 Object.defineProperty(exports, "FFIDAnnouncementList", {
   enumerable: true,
-  get: function () { return chunkL5SBAHY3_cjs.FFIDAnnouncementList; }
+  get: function () { return chunkAMVL7J2G_cjs.FFIDAnnouncementList; }
 });
 Object.defineProperty(exports, "FFIDInquiryForm", {
   enumerable: true,
-  get: function () { return chunkL5SBAHY3_cjs.FFIDInquiryForm; }
+  get: function () { return chunkAMVL7J2G_cjs.FFIDInquiryForm; }
 });
 Object.defineProperty(exports, "FFIDLoginButton", {
   enumerable: true,
-  get: function () { return chunkL5SBAHY3_cjs.FFIDLoginButton; }
+  get: function () { return chunkAMVL7J2G_cjs.FFIDLoginButton; }
 });
 Object.defineProperty(exports, "FFIDOrganizationSwitcher", {
   enumerable: true,
-  get: function () { return chunkL5SBAHY3_cjs.FFIDOrganizationSwitcher; }
+  get: function () { return chunkAMVL7J2G_cjs.FFIDOrganizationSwitcher; }
 });
 Object.defineProperty(exports, "FFIDSubscriptionBadge", {
   enumerable: true,
-  get: function () { return chunkL5SBAHY3_cjs.FFIDSubscriptionBadge; }
+  get: function () { return chunkAMVL7J2G_cjs.FFIDSubscriptionBadge; }
 });
 Object.defineProperty(exports, "FFIDUserMenu", {
   enumerable: true,
-  get: function () { return chunkL5SBAHY3_cjs.FFIDUserMenu; }
+  get: function () { return chunkAMVL7J2G_cjs.FFIDUserMenu; }
 });

package/dist/components/index.d.cts

@@ -1,3 +1,3 @@
-export { H as FFIDAnnouncementBadge, ai as FFIDAnnouncementBadgeClassNames, aj as FFIDAnnouncementBadgeProps, I as FFIDAnnouncementList, ak as FFIDAnnouncementListClassNames, al as FFIDAnnouncementListProps, S as FFIDInquiryForm, T as FFIDInquiryFormCategoryItem, U as FFIDInquiryFormClassNames, V as FFIDInquiryFormLegalLayout, W as FFIDInquiryFormOrganization, X as FFIDInquiryFormPlaceholderContext, Y as FFIDInquiryFormPrefill, Z as FFIDInquiryFormProps, _ as FFIDInquiryFormSubmitData, $ as FFIDInquiryFormSubmitResult, a1 as FFIDLoginButton, am as FFIDLoginButtonProps, a4 as FFIDOrganizationSwitcher, an as FFIDOrganizationSwitcherClassNames, ao as FFIDOrganizationSwitcherProps, a9 as FFIDSubscriptionBadge, ap as FFIDSubscriptionBadgeClassNames, aq as FFIDSubscriptionBadgeProps, ab as FFIDUserMenu, ar as FFIDUserMenuClassNames, as as FFIDUserMenuProps } from '../index-GqflEaKi.cjs';
+export { H as FFIDAnnouncementBadge, al as FFIDAnnouncementBadgeClassNames, am as FFIDAnnouncementBadgeProps, I as FFIDAnnouncementList, an as FFIDAnnouncementListClassNames, ao as FFIDAnnouncementListProps, S as FFIDInquiryForm, U as FFIDInquiryFormCategoryItem, V as FFIDInquiryFormClassNames, W as FFIDInquiryFormLegalLayout, X as FFIDInquiryFormOrganization, Y as FFIDInquiryFormPlaceholderContext, Z as FFIDInquiryFormPrefill, _ as FFIDInquiryFormProps, $ as FFIDInquiryFormSubmitData, a0 as FFIDInquiryFormSubmitResult, a2 as FFIDLoginButton, ap as FFIDLoginButtonProps, a5 as FFIDOrganizationSwitcher, aq as FFIDOrganizationSwitcherClassNames, ar as FFIDOrganizationSwitcherProps, aa as FFIDSubscriptionBadge, as as FFIDSubscriptionBadgeClassNames, at as FFIDSubscriptionBadgeProps, ac as FFIDUserMenu, au as FFIDUserMenuClassNames, av as FFIDUserMenuProps } from '../index-BRMn6xT0.cjs';
 import 'react/jsx-runtime';
 import 'react';

package/dist/components/index.d.ts

@@ -1,3 +1,3 @@
-export { H as FFIDAnnouncementBadge, ai as FFIDAnnouncementBadgeClassNames, aj as FFIDAnnouncementBadgeProps, I as FFIDAnnouncementList, ak as FFIDAnnouncementListClassNames, al as FFIDAnnouncementListProps, S as FFIDInquiryForm, T as FFIDInquiryFormCategoryItem, U as FFIDInquiryFormClassNames, V as FFIDInquiryFormLegalLayout, W as FFIDInquiryFormOrganization, X as FFIDInquiryFormPlaceholderContext, Y as FFIDInquiryFormPrefill, Z as FFIDInquiryFormProps, _ as FFIDInquiryFormSubmitData, $ as FFIDInquiryFormSubmitResult, a1 as FFIDLoginButton, am as FFIDLoginButtonProps, a4 as FFIDOrganizationSwitcher, an as FFIDOrganizationSwitcherClassNames, ao as FFIDOrganizationSwitcherProps, a9 as FFIDSubscriptionBadge, ap as FFIDSubscriptionBadgeClassNames, aq as FFIDSubscriptionBadgeProps, ab as FFIDUserMenu, ar as FFIDUserMenuClassNames, as as FFIDUserMenuProps } from '../index-GqflEaKi.js';
+export { H as FFIDAnnouncementBadge, al as FFIDAnnouncementBadgeClassNames, am as FFIDAnnouncementBadgeProps, I as FFIDAnnouncementList, an as FFIDAnnouncementListClassNames, ao as FFIDAnnouncementListProps, S as FFIDInquiryForm, U as FFIDInquiryFormCategoryItem, V as FFIDInquiryFormClassNames, W as FFIDInquiryFormLegalLayout, X as FFIDInquiryFormOrganization, Y as FFIDInquiryFormPlaceholderContext, Z as FFIDInquiryFormPrefill, _ as FFIDInquiryFormProps, $ as FFIDInquiryFormSubmitData, a0 as FFIDInquiryFormSubmitResult, a2 as FFIDLoginButton, ap as FFIDLoginButtonProps, a5 as FFIDOrganizationSwitcher, aq as FFIDOrganizationSwitcherClassNames, ar as FFIDOrganizationSwitcherProps, aa as FFIDSubscriptionBadge, as as FFIDSubscriptionBadgeClassNames, at as FFIDSubscriptionBadgeProps, ac as FFIDUserMenu, au as FFIDUserMenuClassNames, av as FFIDUserMenuProps } from '../index-BRMn6xT0.js';
 import 'react/jsx-runtime';
 import 'react';

package/dist/components/index.js

@@ -1 +1 @@
-export { FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDSubscriptionBadge, FFIDUserMenu } from '../chunk-C4RNFEME.js';
+export { FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDSubscriptionBadge, FFIDUserMenu } from '../chunk-O3HGRALD.js';

package/dist/{ffid-client-DX2PTTFr.d.ts → ffid-client-B-xjtrCb.d.ts}

@@ -270,6 +270,47 @@ interface FFIDServiceAccessDecision {
     error?: FFIDServiceAccessError;
 }
 
+/**
+ * Token Store
+ *
+ * Manages OAuth 2.0 tokens (access + refresh) with dual-storage support.
+ * Falls back to in-memory storage when localStorage is unavailable
+ * (e.g., Safari private browsing mode).
+ */
+/**
+ * Token data stored by the token store
+ */
+interface TokenData {
+    /** OAuth 2.0 access token */
+    accessToken: string;
+    /** OAuth 2.0 refresh token */
+    refreshToken: string;
+    /** Expiration timestamp in milliseconds (Unix epoch) */
+    expiresAt: number;
+}
+/**
+ * Token store interface for managing OAuth tokens
+ */
+interface TokenStore {
+    /** Get stored tokens (null if not stored) */
+    getTokens(): TokenData | null;
+    /** Store new tokens */
+    setTokens(tokens: TokenData): void;
+    /** Clear all stored tokens */
+    clearTokens(): void;
+    /** Check if access token is expired (with 30s buffer) */
+    isAccessTokenExpired(): boolean;
+}
+/**
+ * Create a token store with the specified storage type.
+ *
+ * When storageType is 'localStorage' (default in browser), falls back
+ * to memory if localStorage is not available (e.g., Safari private mode).
+ *
+ * @param storageType - 'localStorage' (default) or 'memory'
+ */
+declare function createTokenStore(storageType?: 'localStorage' | 'memory'): TokenStore;
+
 /**
  * Billing checkout / portal session types.
  *
@@ -1608,6 +1649,29 @@ interface FFIDConfig {
      * @default undefined (no timeout, uses fetch default)
      */
     timeout?: number | undefined;
+    /**
+     * Token mode only: inject a shared {@link TokenStore} instance so the SDK and
+     * the host app read/write the *same* token source (#4318).
+     *
+     * By default the client creates its own store internally
+     * (`createTokenStore()` in `token` mode, `createTokenStore('memory')`
+     * otherwise). That is fine when `localStorage` is available, because a
+     * separately-created `localStorage` store still points at the same
+     * `ffid_tokens` key. But when `localStorage` is unavailable (e.g. Safari
+     * Private Mode) the SDK falls back to an *in-memory* store, and a store the
+     * host app creates independently is a **different** object — so the app would
+     * see the user as signed-out even though the SDK holds valid tokens.
+     *
+     * Passing a single instance here (typically `createTokenStore()` created once
+     * by the host) guarantees both sides share one source of truth regardless of
+     * storage backend. Prefer reading the token via `useFFID().getAccessToken()`
+     * so refresh/logout stay reflected without the host polling the store.
+     *
+     * Ignored in `cookie` and `service-key` modes (neither exposes a browser
+     * access-token store). When omitted, behavior is unchanged from previous
+     * versions.
+     */
+    tokenStore?: TokenStore | undefined;
 }
 /**
  * OIDC `prompt` values the SDK forwards to FFID `/oauth/authorize` (#4027).
@@ -1850,47 +1914,6 @@ interface FFIDGetLoginHistoryParams {
     limit?: number;
 }
 
-/**
- * Token Store
- *
- * Manages OAuth 2.0 tokens (access + refresh) with dual-storage support.
- * Falls back to in-memory storage when localStorage is unavailable
- * (e.g., Safari private browsing mode).
- */
-/**
- * Token data stored by the token store
- */
-interface TokenData {
-    /** OAuth 2.0 access token */
-    accessToken: string;
-    /** OAuth 2.0 refresh token */
-    refreshToken: string;
-    /** Expiration timestamp in milliseconds (Unix epoch) */
-    expiresAt: number;
-}
-/**
- * Token store interface for managing OAuth tokens
- */
-interface TokenStore {
-    /** Get stored tokens (null if not stored) */
-    getTokens(): TokenData | null;
-    /** Store new tokens */
-    setTokens(tokens: TokenData): void;
-    /** Clear all stored tokens */
-    clearTokens(): void;
-    /** Check if access token is expired (with 30s buffer) */
-    isAccessTokenExpired(): boolean;
-}
-/**
- * Create a token store with the specified storage type.
- *
- * When storageType is 'localStorage' (default in browser), falls back
- * to memory if localStorage is not available (e.g., Safari private mode).
- *
- * @param storageType - 'localStorage' (default) or 'memory'
- */
-declare function createTokenStore(storageType?: 'localStorage' | 'memory'): TokenStore;
-
 /** OAuth token operations - exchangeCodeForTokens / refreshAccessToken / signOutToken */
 
 /**
@@ -2065,6 +2088,11 @@ declare function createFFIDClient(config: FFIDConfig): {
     };
     /** Token store (token mode only) */
     tokenStore: TokenStore;
+    /**
+     * Return the currently-valid access token, or null (token mode only; #4318).
+     * Live-reads the store and applies the 30s expiry buffer.
+     */
+    getAccessToken: () => string | null;
     /** Resolved auth mode */
     authMode: FFIDAuthMode;
     /** Resolved logger instance */