@feelflow/ffid-sdk 5.24.2 → 5.25.0

package/dist/{ffid-client-D0Jh4bO7.d.cts → ffid-client-BZERrMAF.d.cts}

@@ -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.
  *
@@ -1304,6 +1345,57 @@ interface FFIDUpdateUserProfileRequest {
     preferences?: Record<string, unknown> | null;
 }
 
+/**
+ * OAuth flow types: client-side redirect results and OAuth token / RFC 7662
+ * introspection payloads.
+ *
+ * Extracted from `types/index.ts` to keep that barrel under the 800-line hard
+ * limit (`scripts/check-file-size.sh`). Re-exported from `types/index.ts`, so
+ * the public API is unchanged — import from `@feelflow/ffid-sdk` as before.
+ */
+
+/**
+ * Discriminant for redirect failures that callers need to handle
+ * programmatically (vs. logging the human-readable `error` string).
+ *
+ * - `'redirect_loop_detected'`: `redirectToAuthorize()` detected that the
+ *   same authorize URL (keyed by `baseUrl + client_id + organization_id`)
+ *   has been fired **3 times within 60 seconds**. Caller should surface a
+ *   manual "再度ログインする" UI rather than retry automatically (#2406 / #2411).
+ *
+ * - `'state_persistence_failed'`: `redirectToAuthorize()` could not persist
+ *   the OAuth CSRF `state` (storage unavailable / quota). Redirect is aborted
+ *   fail-closed (#4136) — callers should surface a manual retry UI.
+ *
+ * Other failure paths (SSR environment, PKCE generation failure, empty
+ * organizationId) currently return `error` without a `code`. Treat this union
+ * as forward-extensible and do NOT exhaustively `switch` over it without a
+ * `default` branch for consumer code that must stay compatible across SDK
+ * upgrades.
+ */
+type FFIDRedirectErrorCode = 'redirect_loop_detected' | 'state_persistence_failed';
+/**
+ * Result of a redirect operation (redirectToLogin / redirectToAuthorize / redirectToLogout)
+ *
+ * Structured return type so callers can inspect failure reasons
+ * instead of receiving a bare `false`. When `code` is set, branch on it
+ * for programmatic handling; otherwise log `error` for humans.
+ *
+ * `loopDetectionDisabled` (#4119): set to `true` when sessionStorage is
+ * unavailable (iOS WebKit private mode / eviction) so redirect-loop detection
+ * ran **fail-open** — the redirect fired, but repeated-redirect protection is
+ * disabled for this browser session. Callers that need loop protection on
+ * such browsers should add their own max-retry guard.
+ */
+type FFIDRedirectResult = {
+    success: true;
+    loopDetectionDisabled?: boolean;
+} | {
+    success: false;
+    error: string;
+    code?: FFIDRedirectErrorCode;
+};
+
 /**
  * FFID SDK Type Definitions
  *
@@ -1447,6 +1539,19 @@ interface FFIDOAuthUserInfoSubscription {
      * round-trip.
      */
     currentPeriodEnd: string | null;
+    /**
+     * Per-service entitlement codes (e.g. `praxis.pack.<slug>.access`) granting
+     * access to one-time / single-pack purchases not encoded in the plan tier
+     * (#4333, SDK 5.25.0). Read this list to gate per-pack access; an empty
+     * array means "no pack entitlements" (the normal case for Pro / Team tiers
+     * that unlock packs via `planCode`).
+     *
+     * The `normalizeUserinfo` boundary defaults this to `[]` when the server
+     * omits it (older FFID pre-#4333) or when the introspect path uses a service
+     * API key without `subscription:read`, so consumers always see a plain
+     * `readonly string[]` and never branch on an "unknown" sentinel.
+     */
+    entitlements: readonly string[];
 }
 /**
  * Unified user-identity shape returned by `getSession()` (→ `/oauth/userinfo`)
@@ -1608,6 +1713,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).
@@ -1725,47 +1853,6 @@ interface FFIDAnalyticsConfig {
      */
     isActive: boolean;
 }
-/**
- * Discriminant for redirect failures that callers need to handle
- * programmatically (vs. logging the human-readable `error` string).
- *
- * - `'redirect_loop_detected'`: `redirectToAuthorize()` detected that the
- *   same authorize URL (keyed by `baseUrl + client_id + organization_id`)
- *   has been fired **3 times within 60 seconds**. Caller should surface a
- *   manual "再度ログインする" UI rather than retry automatically (#2406 / #2411).
- *
- * - `'state_persistence_failed'`: `redirectToAuthorize()` could not persist
- *   the OAuth CSRF `state` (storage unavailable / quota). Redirect is aborted
- *   fail-closed (#4136) — callers should surface a manual retry UI.
- *
- * Other failure paths (SSR environment, PKCE generation failure, empty
- * organizationId) currently return `error` without a `code`. Treat this union
- * as forward-extensible and do NOT exhaustively `switch` over it without a
- * `default` branch for consumer code that must stay compatible across SDK
- * upgrades.
- */
-type FFIDRedirectErrorCode = 'redirect_loop_detected' | 'state_persistence_failed';
-/**
- * Result of a redirect operation (redirectToLogin / redirectToAuthorize / redirectToLogout)
- *
- * Structured return type so callers can inspect failure reasons
- * instead of receiving a bare `false`. When `code` is set, branch on it
- * for programmatic handling; otherwise log `error` for humans.
- *
- * `loopDetectionDisabled` (#4119): set to `true` when sessionStorage is
- * unavailable (iOS WebKit private mode / eviction) so redirect-loop detection
- * ran **fail-open** — the redirect fired, but repeated-redirect protection is
- * disabled for this browser session. Callers that need loop protection on
- * such browsers should add their own max-retry guard.
- */
-type FFIDRedirectResult = {
-    success: true;
-    loopDetectionDisabled?: boolean;
-} | {
-    success: false;
-    error: string;
-    code?: FFIDRedirectErrorCode;
-};
 
 /** OTP / magic link methods - sendOtp / verifyOtp */
 
@@ -1850,47 +1937,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 +2111,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 */

package/dist/{ffid-client-DX2PTTFr.d.ts → ffid-client-CFZPX5ej.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.
  *
@@ -1304,6 +1345,57 @@ interface FFIDUpdateUserProfileRequest {
     preferences?: Record<string, unknown> | null;
 }
 
+/**
+ * OAuth flow types: client-side redirect results and OAuth token / RFC 7662
+ * introspection payloads.
+ *
+ * Extracted from `types/index.ts` to keep that barrel under the 800-line hard
+ * limit (`scripts/check-file-size.sh`). Re-exported from `types/index.ts`, so
+ * the public API is unchanged — import from `@feelflow/ffid-sdk` as before.
+ */
+
+/**
+ * Discriminant for redirect failures that callers need to handle
+ * programmatically (vs. logging the human-readable `error` string).
+ *
+ * - `'redirect_loop_detected'`: `redirectToAuthorize()` detected that the
+ *   same authorize URL (keyed by `baseUrl + client_id + organization_id`)
+ *   has been fired **3 times within 60 seconds**. Caller should surface a
+ *   manual "再度ログインする" UI rather than retry automatically (#2406 / #2411).
+ *
+ * - `'state_persistence_failed'`: `redirectToAuthorize()` could not persist
+ *   the OAuth CSRF `state` (storage unavailable / quota). Redirect is aborted
+ *   fail-closed (#4136) — callers should surface a manual retry UI.
+ *
+ * Other failure paths (SSR environment, PKCE generation failure, empty
+ * organizationId) currently return `error` without a `code`. Treat this union
+ * as forward-extensible and do NOT exhaustively `switch` over it without a
+ * `default` branch for consumer code that must stay compatible across SDK
+ * upgrades.
+ */
+type FFIDRedirectErrorCode = 'redirect_loop_detected' | 'state_persistence_failed';
+/**
+ * Result of a redirect operation (redirectToLogin / redirectToAuthorize / redirectToLogout)
+ *
+ * Structured return type so callers can inspect failure reasons
+ * instead of receiving a bare `false`. When `code` is set, branch on it
+ * for programmatic handling; otherwise log `error` for humans.
+ *
+ * `loopDetectionDisabled` (#4119): set to `true` when sessionStorage is
+ * unavailable (iOS WebKit private mode / eviction) so redirect-loop detection
+ * ran **fail-open** — the redirect fired, but repeated-redirect protection is
+ * disabled for this browser session. Callers that need loop protection on
+ * such browsers should add their own max-retry guard.
+ */
+type FFIDRedirectResult = {
+    success: true;
+    loopDetectionDisabled?: boolean;
+} | {
+    success: false;
+    error: string;
+    code?: FFIDRedirectErrorCode;
+};
+
 /**
  * FFID SDK Type Definitions
  *
@@ -1447,6 +1539,19 @@ interface FFIDOAuthUserInfoSubscription {
      * round-trip.
      */
     currentPeriodEnd: string | null;
+    /**
+     * Per-service entitlement codes (e.g. `praxis.pack.<slug>.access`) granting
+     * access to one-time / single-pack purchases not encoded in the plan tier
+     * (#4333, SDK 5.25.0). Read this list to gate per-pack access; an empty
+     * array means "no pack entitlements" (the normal case for Pro / Team tiers
+     * that unlock packs via `planCode`).
+     *
+     * The `normalizeUserinfo` boundary defaults this to `[]` when the server
+     * omits it (older FFID pre-#4333) or when the introspect path uses a service
+     * API key without `subscription:read`, so consumers always see a plain
+     * `readonly string[]` and never branch on an "unknown" sentinel.
+     */
+    entitlements: readonly string[];
 }
 /**
  * Unified user-identity shape returned by `getSession()` (→ `/oauth/userinfo`)
@@ -1608,6 +1713,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).
@@ -1725,47 +1853,6 @@ interface FFIDAnalyticsConfig {
      */
     isActive: boolean;
 }
-/**
- * Discriminant for redirect failures that callers need to handle
- * programmatically (vs. logging the human-readable `error` string).
- *
- * - `'redirect_loop_detected'`: `redirectToAuthorize()` detected that the
- *   same authorize URL (keyed by `baseUrl + client_id + organization_id`)
- *   has been fired **3 times within 60 seconds**. Caller should surface a
- *   manual "再度ログインする" UI rather than retry automatically (#2406 / #2411).
- *
- * - `'state_persistence_failed'`: `redirectToAuthorize()` could not persist
- *   the OAuth CSRF `state` (storage unavailable / quota). Redirect is aborted
- *   fail-closed (#4136) — callers should surface a manual retry UI.
- *
- * Other failure paths (SSR environment, PKCE generation failure, empty
- * organizationId) currently return `error` without a `code`. Treat this union
- * as forward-extensible and do NOT exhaustively `switch` over it without a
- * `default` branch for consumer code that must stay compatible across SDK
- * upgrades.
- */
-type FFIDRedirectErrorCode = 'redirect_loop_detected' | 'state_persistence_failed';
-/**
- * Result of a redirect operation (redirectToLogin / redirectToAuthorize / redirectToLogout)
- *
- * Structured return type so callers can inspect failure reasons
- * instead of receiving a bare `false`. When `code` is set, branch on it
- * for programmatic handling; otherwise log `error` for humans.
- *
- * `loopDetectionDisabled` (#4119): set to `true` when sessionStorage is
- * unavailable (iOS WebKit private mode / eviction) so redirect-loop detection
- * ran **fail-open** — the redirect fired, but repeated-redirect protection is
- * disabled for this browser session. Callers that need loop protection on
- * such browsers should add their own max-retry guard.
- */
-type FFIDRedirectResult = {
-    success: true;
-    loopDetectionDisabled?: boolean;
-} | {
-    success: false;
-    error: string;
-    code?: FFIDRedirectErrorCode;
-};
 
 /** OTP / magic link methods - sendOtp / verifyOtp */
 
@@ -1850,47 +1937,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 +2111,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 */