@feelflow/ffid-sdk 2.17.1 → 2.19.0

package/dist/components/index.cjs

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

package/dist/components/index.d.cts

@@ -1,3 +1,3 @@
-export { K as FFIDAnnouncementBadge, aj as FFIDAnnouncementBadgeClassNames, ak as FFIDAnnouncementBadgeProps, M as FFIDAnnouncementList, al as FFIDAnnouncementListClassNames, am as FFIDAnnouncementListProps, U as FFIDInquiryForm, V as FFIDInquiryFormCategoryItem, W as FFIDInquiryFormClassNames, X as FFIDInquiryFormOrganization, Y as FFIDInquiryFormPlaceholderContext, Z as FFIDInquiryFormPrefill, _ as FFIDInquiryFormProps, $ as FFIDInquiryFormSubmitData, a0 as FFIDInquiryFormSubmitResult, a2 as FFIDLoginButton, an as FFIDLoginButtonProps, a8 as FFIDOrganizationSwitcher, ao as FFIDOrganizationSwitcherClassNames, ap as FFIDOrganizationSwitcherProps, aa as FFIDSubscriptionBadge, aq as FFIDSubscriptionBadgeClassNames, ar as FFIDSubscriptionBadgeProps, ac as FFIDUserMenu, as as FFIDUserMenuClassNames, at as FFIDUserMenuProps } from '../index-Cv1qXIl1.cjs';
+export { M as FFIDAnnouncementBadge, al as FFIDAnnouncementBadgeClassNames, am as FFIDAnnouncementBadgeProps, N as FFIDAnnouncementList, an as FFIDAnnouncementListClassNames, ao as FFIDAnnouncementListProps, V as FFIDInquiryForm, W as FFIDInquiryFormCategoryItem, X as FFIDInquiryFormClassNames, Y as FFIDInquiryFormOrganization, Z as FFIDInquiryFormPlaceholderContext, _ as FFIDInquiryFormPrefill, $ as FFIDInquiryFormProps, a0 as FFIDInquiryFormSubmitData, a1 as FFIDInquiryFormSubmitResult, a3 as FFIDLoginButton, ap as FFIDLoginButtonProps, a9 as FFIDOrganizationSwitcher, aq as FFIDOrganizationSwitcherClassNames, ar as FFIDOrganizationSwitcherProps, ac as FFIDSubscriptionBadge, as as FFIDSubscriptionBadgeClassNames, at as FFIDSubscriptionBadgeProps, ae as FFIDUserMenu, au as FFIDUserMenuClassNames, av as FFIDUserMenuProps } from '../index-0D2vYSLq.cjs';
 import 'react/jsx-runtime';
 import 'react';

package/dist/components/index.d.ts

@@ -1,3 +1,3 @@
-export { K as FFIDAnnouncementBadge, aj as FFIDAnnouncementBadgeClassNames, ak as FFIDAnnouncementBadgeProps, M as FFIDAnnouncementList, al as FFIDAnnouncementListClassNames, am as FFIDAnnouncementListProps, U as FFIDInquiryForm, V as FFIDInquiryFormCategoryItem, W as FFIDInquiryFormClassNames, X as FFIDInquiryFormOrganization, Y as FFIDInquiryFormPlaceholderContext, Z as FFIDInquiryFormPrefill, _ as FFIDInquiryFormProps, $ as FFIDInquiryFormSubmitData, a0 as FFIDInquiryFormSubmitResult, a2 as FFIDLoginButton, an as FFIDLoginButtonProps, a8 as FFIDOrganizationSwitcher, ao as FFIDOrganizationSwitcherClassNames, ap as FFIDOrganizationSwitcherProps, aa as FFIDSubscriptionBadge, aq as FFIDSubscriptionBadgeClassNames, ar as FFIDSubscriptionBadgeProps, ac as FFIDUserMenu, as as FFIDUserMenuClassNames, at as FFIDUserMenuProps } from '../index-Cv1qXIl1.js';
+export { M as FFIDAnnouncementBadge, al as FFIDAnnouncementBadgeClassNames, am as FFIDAnnouncementBadgeProps, N as FFIDAnnouncementList, an as FFIDAnnouncementListClassNames, ao as FFIDAnnouncementListProps, V as FFIDInquiryForm, W as FFIDInquiryFormCategoryItem, X as FFIDInquiryFormClassNames, Y as FFIDInquiryFormOrganization, Z as FFIDInquiryFormPlaceholderContext, _ as FFIDInquiryFormPrefill, $ as FFIDInquiryFormProps, a0 as FFIDInquiryFormSubmitData, a1 as FFIDInquiryFormSubmitResult, a3 as FFIDLoginButton, ap as FFIDLoginButtonProps, a9 as FFIDOrganizationSwitcher, aq as FFIDOrganizationSwitcherClassNames, ar as FFIDOrganizationSwitcherProps, ac as FFIDSubscriptionBadge, as as FFIDSubscriptionBadgeClassNames, at as FFIDSubscriptionBadgeProps, ae as FFIDUserMenu, au as FFIDUserMenuClassNames, av as FFIDUserMenuProps } from '../index-0D2vYSLq.js';
 import 'react/jsx-runtime';
 import 'react';

package/dist/components/index.js

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

package/dist/{index-Cv1qXIl1.d.cts → index-0D2vYSLq.d.cts}

@@ -22,6 +22,42 @@ interface FFIDCacheConfig {
     ttl: number;
 }
 
+/**
+ * Subscription access-control types (Chain of Pacts / Issue #2443).
+ *
+ * Defines `EffectiveSubscriptionStatus` — the semantic status surfaced by
+ * `/api/v1/subscriptions/ext/check` for external services that need a single
+ * value to drive access-control decisions. Mirrors the server-side type in
+ * `src/lib/common/subscription-helpers.ts` so the FFID backend, SDK, and
+ * consuming services agree on the same vocabulary.
+ */
+/**
+ * Semantic subscription status used for access-control decisions by external
+ * services.
+ *
+ * Unlike the raw DB `FFIDSubscriptionStatus` (which keeps the Stripe-aligned
+ * status machine, e.g. `past_due` / `incomplete` / `incomplete_expired`), this
+ * narrowed union flattens dunning-window vs. hard-block cases so callers can
+ * branch on a single value:
+ *
+ * - `active` — normal paying subscription; grant full access.
+ * - `past_due_grace` — payment failed but FFID is still retrying. Service
+ *   SHOULD keep access and surface a recovery banner.
+ * - `blocked` — payment dunning exhausted (`past_due` over grace,
+ *   `unpaid`, `incomplete_expired`, `paused`, `incomplete`). Deny access.
+ * - `canceled` — contract ended (voluntary or auto-cancel). Deny access;
+ *   check the accompanying `reactivatable` flag before showing a restart CTA.
+ * - `trial_expired` — `status = 'trialing'` but the trial end is in the past.
+ *   DB row is still `trialing`; deny access and prompt for a paid plan.
+ * - `expired` — `status = 'active'` but `current_period_end` is in the past.
+ *   This is the FFID-internal runtime-expired case (see
+ *   `getEffectiveSubscriptionStatus` on the server). Deny access.
+ *
+ * @see /api/v1/subscriptions/ext/check
+ * @see docs/03-implementation/EXPIRED_CONTRACT_HANDLING.md
+ */
+type EffectiveSubscriptionStatus = 'active' | 'past_due_grace' | 'blocked' | 'canceled' | 'trial_expired' | 'expired';
+
 /**
  * FFID SDK Type Definitions
  *
@@ -284,10 +320,59 @@ interface FFIDSubscriptionContextValue {
     isTrialExpired: boolean;
     /** Whether subscription is canceled */
     isCanceled: boolean;
+    /**
+     * Semantic access-control status for the current subscription.
+     *
+     * Always computed locally from the session response via
+     * `computeEffectiveStatusFromSession` (status + currentPeriodEnd + trialEnd).
+     * The session endpoint does not currently surface an authoritative
+     * effectiveStatus, so this is a best-effort approximation suitable for UI
+     * decisions that tolerate ~1 request worth of staleness.
+     *
+     * For authoritative decisions (e.g., paywall gates on billing-critical UI,
+     * grace-window banners that depend on `gracePeriodEndsAt`, or reactivation
+     * CTAs that depend on `reactivatable`), call the server-side
+     * `/api/v1/subscriptions/ext/check` endpoint directly — it returns a richer
+     * payload (`effectiveStatus`, `gracePeriodEndsAt`, `reactivatable`) computed
+     * against the live DB.
+     *
+     * `null` when there is no subscription for the current service.
+     *
+     * @see {@link EffectiveSubscriptionStatus}
+     */
+    effectiveStatus: EffectiveSubscriptionStatus | null;
+    /**
+     * Whether the subscription is in an access-blocking terminal state
+     * (`blocked` | `expired` | `canceled` | `trial_expired`).
+     */
+    isBlocked: boolean;
+    /**
+     * Whether the subscription is inside the payment-failure grace window
+     * (`past_due_grace`). Access is still granted by `hasAccess`, but UIs
+     * should surface a recovery banner.
+     */
+    isGrace: boolean;
     /** Check if user has specific plan */
     hasPlan: (plans: string | string[]) => boolean;
-    /** Check if user has access (active or trialing subscription) */
+    /**
+     * Whether the user currently has access.
+     *
+     * Post Chain-of-Pacts (Issue #2444): `true` when
+     * `effectiveStatus === 'active' || effectiveStatus === 'past_due_grace'`.
+     * Legacy consumers that need the pre-2444 semantics
+     * (`status === 'active' || status === 'trialing'`) can use
+     * `hasAccessLegacy()`.
+     */
     hasAccess: () => boolean;
+    /**
+     * Pre-2444 `hasAccess` semantics: `true` when the raw DB status is
+     * `active` or `trialing` (and, for trialing, the trial is not runtime-
+     * expired). Kept as a backwards-compatibility escape hatch so services
+     * that have not yet migrated to the effective-status model keep working.
+     *
+     * @deprecated Prefer `hasAccess()` or branch on `effectiveStatus` directly.
+     */
+    hasAccessLegacy: () => boolean;
 }
 /**
  * Logger interface for SDK debug output
@@ -537,17 +622,36 @@ interface FFIDUpdateUserProfileRequest {
     /** Arbitrary user preferences bag (null clears the column; reads return {}) */
     preferences?: Record<string, unknown> | null;
 }
+/**
+ * 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).
+ *
+ * SDK 2.18.0 only ships `'redirect_loop_detected'`. Other failure paths
+ * (SSR environment, PKCE generation failure, empty organizationId) currently
+ * return `error` without a `code`. New codes will be added in future minor
+ * versions — 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';
 /**
  * Result of a redirect operation (redirectToLogin / redirectToAuthorize / redirectToLogout)
  *
  * Structured return type so callers can inspect failure reasons
- * instead of receiving a bare `false`.
+ * instead of receiving a bare `false`. When `code` is set, branch on it
+ * for programmatic handling; otherwise log `error` for humans.
  */
 type FFIDRedirectResult = {
     success: true;
 } | {
     success: false;
     error: string;
+    code?: FFIDRedirectErrorCode;
 };
 /**
  * OAuth 2.0 token response from FFID token endpoint
@@ -1282,4 +1386,4 @@ interface FFIDInquiryFormPlaceholderContext {
 }
 declare function FFIDInquiryForm({ mode, prefill, organizations, preselectedOrganizationId, categories, termsVersion, privacyVersion, termsHref, privacyHref, turnstileToken, turnstileSlot, onSubmit, onChange, separateLegalCheckboxes, messagePlaceholder, requireCategorySelection, unstyled, classNames, locale, className, }: FFIDInquiryFormProps): react_jsx_runtime.JSX.Element;
 
-export { type FFIDInquiryFormSubmitData as $, type FFIDSubscription as A, type FFIDSubscriptionContextValue as B, type FFIDAnnouncementsClientConfig as C, type FFIDAnnouncementsApiResponse as D, type AnnouncementListResponse as E, type FFIDSubscriptionStatus as F, type FFIDAnnouncementsLogger as G, type Announcement as H, type AnnouncementStatus as I, type AnnouncementType as J, FFIDAnnouncementBadge as K, type ListAnnouncementsOptions as L, FFIDAnnouncementList as M, type FFIDAnnouncementsError as N, type FFIDAnnouncementsErrorCode as O, type FFIDAnnouncementsServerResponse as P, type FFIDCacheConfig as Q, type FFIDContextValue as R, type FFIDInquiryCategory as S, type FFIDInquiryCategorySite2026 as T, FFIDInquiryForm as U, type FFIDInquiryFormCategoryItem as V, type FFIDInquiryFormClassNames as W, type FFIDInquiryFormOrganization as X, type FFIDInquiryFormPlaceholderContext as Y, type FFIDInquiryFormPrefill as Z, type FFIDInquiryFormProps as _, type FFIDConfig as a, type FFIDInquiryFormSubmitResult as a0, type FFIDJwtClaims as a1, FFIDLoginButton as a2, type FFIDMemberStatus as a3, type FFIDOAuthTokenResponse as a4, type FFIDOAuthUserInfoMemberRole as a5, type FFIDOAuthUserInfoSubscription as a6, type FFIDOrganizationMember as a7, FFIDOrganizationSwitcher as a8, type FFIDSeatModel as a9, FFIDSubscriptionBadge as aa, type FFIDTokenIntrospectionResponse as ab, FFIDUserMenu as ac, FFID_INQUIRY_CATEGORIES as ad, FFID_INQUIRY_CATEGORIES_SITE_2026 as ae, type UseFFIDAnnouncementsOptions as af, type UseFFIDAnnouncementsReturn as ag, isFFIDInquiryCategorySite2026 as ah, useFFIDAnnouncements as ai, type FFIDAnnouncementBadgeClassNames as aj, type FFIDAnnouncementBadgeProps as ak, type FFIDAnnouncementListClassNames as al, type FFIDAnnouncementListProps as am, type FFIDLoginButtonProps as an, type FFIDOrganizationSwitcherClassNames as ao, type FFIDOrganizationSwitcherProps as ap, type FFIDSubscriptionBadgeClassNames as aq, type FFIDSubscriptionBadgeProps as ar, type FFIDUserMenuClassNames as as, type FFIDUserMenuProps as at, type FFIDApiResponse as b, type FFIDSessionResponse as c, type FFIDRedirectResult as d, type FFIDError as e, type FFIDSubscriptionCheckResponse as f, type FFIDListMembersResponse as g, type FFIDMemberRole as h, type FFIDUpdateMemberRoleResponse as i, type FFIDRemoveMemberResponse as j, type FFIDProfileCallOptions as k, type FFIDUserProfile as l, type FFIDUpdateUserProfileRequest as m, type FFIDCreateCheckoutParams as n, type FFIDCheckoutSessionResponse as o, type FFIDCreatePortalParams as p, type FFIDPortalSessionResponse as q, type FFIDVerifyAccessTokenOptions as r, type FFIDOAuthUserInfo as s, type FFIDInquiryCreateParams as t, type FFIDInquiryCreateResponse as u, type FFIDAuthMode as v, type FFIDLogger as w, type FFIDCacheAdapter as x, type FFIDUser as y, type FFIDOrganization as z };
+export { type FFIDInquiryFormProps as $, type FFIDSubscription as A, type FFIDSubscriptionContextValue as B, type FFIDAnnouncementsClientConfig as C, type FFIDAnnouncementsApiResponse as D, type EffectiveSubscriptionStatus as E, type FFIDSubscriptionStatus as F, type AnnouncementListResponse as G, type FFIDAnnouncementsLogger as H, type Announcement as I, type AnnouncementStatus as J, type AnnouncementType as K, type ListAnnouncementsOptions as L, FFIDAnnouncementBadge as M, FFIDAnnouncementList as N, type FFIDAnnouncementsError as O, type FFIDAnnouncementsErrorCode as P, type FFIDAnnouncementsServerResponse as Q, type FFIDCacheConfig as R, type FFIDContextValue as S, type FFIDInquiryCategory as T, type FFIDInquiryCategorySite2026 as U, FFIDInquiryForm as V, type FFIDInquiryFormCategoryItem as W, type FFIDInquiryFormClassNames as X, type FFIDInquiryFormOrganization as Y, type FFIDInquiryFormPlaceholderContext as Z, type FFIDInquiryFormPrefill as _, type FFIDConfig as a, type FFIDInquiryFormSubmitData as a0, type FFIDInquiryFormSubmitResult as a1, type FFIDJwtClaims as a2, FFIDLoginButton as a3, type FFIDMemberStatus as a4, type FFIDOAuthTokenResponse as a5, type FFIDOAuthUserInfoMemberRole as a6, type FFIDOAuthUserInfoSubscription as a7, type FFIDOrganizationMember as a8, FFIDOrganizationSwitcher as a9, type FFIDRedirectErrorCode as aa, type FFIDSeatModel as ab, FFIDSubscriptionBadge as ac, type FFIDTokenIntrospectionResponse as ad, FFIDUserMenu as ae, FFID_INQUIRY_CATEGORIES as af, FFID_INQUIRY_CATEGORIES_SITE_2026 as ag, type UseFFIDAnnouncementsOptions as ah, type UseFFIDAnnouncementsReturn as ai, isFFIDInquiryCategorySite2026 as aj, useFFIDAnnouncements as ak, type FFIDAnnouncementBadgeClassNames as al, type FFIDAnnouncementBadgeProps as am, type FFIDAnnouncementListClassNames as an, type FFIDAnnouncementListProps as ao, type FFIDLoginButtonProps as ap, type FFIDOrganizationSwitcherClassNames as aq, type FFIDOrganizationSwitcherProps as ar, type FFIDSubscriptionBadgeClassNames as as, type FFIDSubscriptionBadgeProps as at, type FFIDUserMenuClassNames as au, type FFIDUserMenuProps as av, type FFIDApiResponse as b, type FFIDSessionResponse as c, type FFIDRedirectResult as d, type FFIDError as e, type FFIDSubscriptionCheckResponse as f, type FFIDListMembersResponse as g, type FFIDMemberRole as h, type FFIDUpdateMemberRoleResponse as i, type FFIDRemoveMemberResponse as j, type FFIDProfileCallOptions as k, type FFIDUserProfile as l, type FFIDUpdateUserProfileRequest as m, type FFIDCreateCheckoutParams as n, type FFIDCheckoutSessionResponse as o, type FFIDCreatePortalParams as p, type FFIDPortalSessionResponse as q, type FFIDVerifyAccessTokenOptions as r, type FFIDOAuthUserInfo as s, type FFIDInquiryCreateParams as t, type FFIDInquiryCreateResponse as u, type FFIDAuthMode as v, type FFIDLogger as w, type FFIDCacheAdapter as x, type FFIDUser as y, type FFIDOrganization as z };

package/dist/{index-Cv1qXIl1.d.ts → index-0D2vYSLq.d.ts}

@@ -22,6 +22,42 @@ interface FFIDCacheConfig {
     ttl: number;
 }
 
+/**
+ * Subscription access-control types (Chain of Pacts / Issue #2443).
+ *
+ * Defines `EffectiveSubscriptionStatus` — the semantic status surfaced by
+ * `/api/v1/subscriptions/ext/check` for external services that need a single
+ * value to drive access-control decisions. Mirrors the server-side type in
+ * `src/lib/common/subscription-helpers.ts` so the FFID backend, SDK, and
+ * consuming services agree on the same vocabulary.
+ */
+/**
+ * Semantic subscription status used for access-control decisions by external
+ * services.
+ *
+ * Unlike the raw DB `FFIDSubscriptionStatus` (which keeps the Stripe-aligned
+ * status machine, e.g. `past_due` / `incomplete` / `incomplete_expired`), this
+ * narrowed union flattens dunning-window vs. hard-block cases so callers can
+ * branch on a single value:
+ *
+ * - `active` — normal paying subscription; grant full access.
+ * - `past_due_grace` — payment failed but FFID is still retrying. Service
+ *   SHOULD keep access and surface a recovery banner.
+ * - `blocked` — payment dunning exhausted (`past_due` over grace,
+ *   `unpaid`, `incomplete_expired`, `paused`, `incomplete`). Deny access.
+ * - `canceled` — contract ended (voluntary or auto-cancel). Deny access;
+ *   check the accompanying `reactivatable` flag before showing a restart CTA.
+ * - `trial_expired` — `status = 'trialing'` but the trial end is in the past.
+ *   DB row is still `trialing`; deny access and prompt for a paid plan.
+ * - `expired` — `status = 'active'` but `current_period_end` is in the past.
+ *   This is the FFID-internal runtime-expired case (see
+ *   `getEffectiveSubscriptionStatus` on the server). Deny access.
+ *
+ * @see /api/v1/subscriptions/ext/check
+ * @see docs/03-implementation/EXPIRED_CONTRACT_HANDLING.md
+ */
+type EffectiveSubscriptionStatus = 'active' | 'past_due_grace' | 'blocked' | 'canceled' | 'trial_expired' | 'expired';
+
 /**
  * FFID SDK Type Definitions
  *
@@ -284,10 +320,59 @@ interface FFIDSubscriptionContextValue {
     isTrialExpired: boolean;
     /** Whether subscription is canceled */
     isCanceled: boolean;
+    /**
+     * Semantic access-control status for the current subscription.
+     *
+     * Always computed locally from the session response via
+     * `computeEffectiveStatusFromSession` (status + currentPeriodEnd + trialEnd).
+     * The session endpoint does not currently surface an authoritative
+     * effectiveStatus, so this is a best-effort approximation suitable for UI
+     * decisions that tolerate ~1 request worth of staleness.
+     *
+     * For authoritative decisions (e.g., paywall gates on billing-critical UI,
+     * grace-window banners that depend on `gracePeriodEndsAt`, or reactivation
+     * CTAs that depend on `reactivatable`), call the server-side
+     * `/api/v1/subscriptions/ext/check` endpoint directly — it returns a richer
+     * payload (`effectiveStatus`, `gracePeriodEndsAt`, `reactivatable`) computed
+     * against the live DB.
+     *
+     * `null` when there is no subscription for the current service.
+     *
+     * @see {@link EffectiveSubscriptionStatus}
+     */
+    effectiveStatus: EffectiveSubscriptionStatus | null;
+    /**
+     * Whether the subscription is in an access-blocking terminal state
+     * (`blocked` | `expired` | `canceled` | `trial_expired`).
+     */
+    isBlocked: boolean;
+    /**
+     * Whether the subscription is inside the payment-failure grace window
+     * (`past_due_grace`). Access is still granted by `hasAccess`, but UIs
+     * should surface a recovery banner.
+     */
+    isGrace: boolean;
     /** Check if user has specific plan */
     hasPlan: (plans: string | string[]) => boolean;
-    /** Check if user has access (active or trialing subscription) */
+    /**
+     * Whether the user currently has access.
+     *
+     * Post Chain-of-Pacts (Issue #2444): `true` when
+     * `effectiveStatus === 'active' || effectiveStatus === 'past_due_grace'`.
+     * Legacy consumers that need the pre-2444 semantics
+     * (`status === 'active' || status === 'trialing'`) can use
+     * `hasAccessLegacy()`.
+     */
     hasAccess: () => boolean;
+    /**
+     * Pre-2444 `hasAccess` semantics: `true` when the raw DB status is
+     * `active` or `trialing` (and, for trialing, the trial is not runtime-
+     * expired). Kept as a backwards-compatibility escape hatch so services
+     * that have not yet migrated to the effective-status model keep working.
+     *
+     * @deprecated Prefer `hasAccess()` or branch on `effectiveStatus` directly.
+     */
+    hasAccessLegacy: () => boolean;
 }
 /**
  * Logger interface for SDK debug output
@@ -537,17 +622,36 @@ interface FFIDUpdateUserProfileRequest {
     /** Arbitrary user preferences bag (null clears the column; reads return {}) */
     preferences?: Record<string, unknown> | null;
 }
+/**
+ * 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).
+ *
+ * SDK 2.18.0 only ships `'redirect_loop_detected'`. Other failure paths
+ * (SSR environment, PKCE generation failure, empty organizationId) currently
+ * return `error` without a `code`. New codes will be added in future minor
+ * versions — 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';
 /**
  * Result of a redirect operation (redirectToLogin / redirectToAuthorize / redirectToLogout)
  *
  * Structured return type so callers can inspect failure reasons
- * instead of receiving a bare `false`.
+ * instead of receiving a bare `false`. When `code` is set, branch on it
+ * for programmatic handling; otherwise log `error` for humans.
  */
 type FFIDRedirectResult = {
     success: true;
 } | {
     success: false;
     error: string;
+    code?: FFIDRedirectErrorCode;
 };
 /**
  * OAuth 2.0 token response from FFID token endpoint
@@ -1282,4 +1386,4 @@ interface FFIDInquiryFormPlaceholderContext {
 }
 declare function FFIDInquiryForm({ mode, prefill, organizations, preselectedOrganizationId, categories, termsVersion, privacyVersion, termsHref, privacyHref, turnstileToken, turnstileSlot, onSubmit, onChange, separateLegalCheckboxes, messagePlaceholder, requireCategorySelection, unstyled, classNames, locale, className, }: FFIDInquiryFormProps): react_jsx_runtime.JSX.Element;
 
-export { type FFIDInquiryFormSubmitData as $, type FFIDSubscription as A, type FFIDSubscriptionContextValue as B, type FFIDAnnouncementsClientConfig as C, type FFIDAnnouncementsApiResponse as D, type AnnouncementListResponse as E, type FFIDSubscriptionStatus as F, type FFIDAnnouncementsLogger as G, type Announcement as H, type AnnouncementStatus as I, type AnnouncementType as J, FFIDAnnouncementBadge as K, type ListAnnouncementsOptions as L, FFIDAnnouncementList as M, type FFIDAnnouncementsError as N, type FFIDAnnouncementsErrorCode as O, type FFIDAnnouncementsServerResponse as P, type FFIDCacheConfig as Q, type FFIDContextValue as R, type FFIDInquiryCategory as S, type FFIDInquiryCategorySite2026 as T, FFIDInquiryForm as U, type FFIDInquiryFormCategoryItem as V, type FFIDInquiryFormClassNames as W, type FFIDInquiryFormOrganization as X, type FFIDInquiryFormPlaceholderContext as Y, type FFIDInquiryFormPrefill as Z, type FFIDInquiryFormProps as _, type FFIDConfig as a, type FFIDInquiryFormSubmitResult as a0, type FFIDJwtClaims as a1, FFIDLoginButton as a2, type FFIDMemberStatus as a3, type FFIDOAuthTokenResponse as a4, type FFIDOAuthUserInfoMemberRole as a5, type FFIDOAuthUserInfoSubscription as a6, type FFIDOrganizationMember as a7, FFIDOrganizationSwitcher as a8, type FFIDSeatModel as a9, FFIDSubscriptionBadge as aa, type FFIDTokenIntrospectionResponse as ab, FFIDUserMenu as ac, FFID_INQUIRY_CATEGORIES as ad, FFID_INQUIRY_CATEGORIES_SITE_2026 as ae, type UseFFIDAnnouncementsOptions as af, type UseFFIDAnnouncementsReturn as ag, isFFIDInquiryCategorySite2026 as ah, useFFIDAnnouncements as ai, type FFIDAnnouncementBadgeClassNames as aj, type FFIDAnnouncementBadgeProps as ak, type FFIDAnnouncementListClassNames as al, type FFIDAnnouncementListProps as am, type FFIDLoginButtonProps as an, type FFIDOrganizationSwitcherClassNames as ao, type FFIDOrganizationSwitcherProps as ap, type FFIDSubscriptionBadgeClassNames as aq, type FFIDSubscriptionBadgeProps as ar, type FFIDUserMenuClassNames as as, type FFIDUserMenuProps as at, type FFIDApiResponse as b, type FFIDSessionResponse as c, type FFIDRedirectResult as d, type FFIDError as e, type FFIDSubscriptionCheckResponse as f, type FFIDListMembersResponse as g, type FFIDMemberRole as h, type FFIDUpdateMemberRoleResponse as i, type FFIDRemoveMemberResponse as j, type FFIDProfileCallOptions as k, type FFIDUserProfile as l, type FFIDUpdateUserProfileRequest as m, type FFIDCreateCheckoutParams as n, type FFIDCheckoutSessionResponse as o, type FFIDCreatePortalParams as p, type FFIDPortalSessionResponse as q, type FFIDVerifyAccessTokenOptions as r, type FFIDOAuthUserInfo as s, type FFIDInquiryCreateParams as t, type FFIDInquiryCreateResponse as u, type FFIDAuthMode as v, type FFIDLogger as w, type FFIDCacheAdapter as x, type FFIDUser as y, type FFIDOrganization as z };
+export { type FFIDInquiryFormProps as $, type FFIDSubscription as A, type FFIDSubscriptionContextValue as B, type FFIDAnnouncementsClientConfig as C, type FFIDAnnouncementsApiResponse as D, type EffectiveSubscriptionStatus as E, type FFIDSubscriptionStatus as F, type AnnouncementListResponse as G, type FFIDAnnouncementsLogger as H, type Announcement as I, type AnnouncementStatus as J, type AnnouncementType as K, type ListAnnouncementsOptions as L, FFIDAnnouncementBadge as M, FFIDAnnouncementList as N, type FFIDAnnouncementsError as O, type FFIDAnnouncementsErrorCode as P, type FFIDAnnouncementsServerResponse as Q, type FFIDCacheConfig as R, type FFIDContextValue as S, type FFIDInquiryCategory as T, type FFIDInquiryCategorySite2026 as U, FFIDInquiryForm as V, type FFIDInquiryFormCategoryItem as W, type FFIDInquiryFormClassNames as X, type FFIDInquiryFormOrganization as Y, type FFIDInquiryFormPlaceholderContext as Z, type FFIDInquiryFormPrefill as _, type FFIDConfig as a, type FFIDInquiryFormSubmitData as a0, type FFIDInquiryFormSubmitResult as a1, type FFIDJwtClaims as a2, FFIDLoginButton as a3, type FFIDMemberStatus as a4, type FFIDOAuthTokenResponse as a5, type FFIDOAuthUserInfoMemberRole as a6, type FFIDOAuthUserInfoSubscription as a7, type FFIDOrganizationMember as a8, FFIDOrganizationSwitcher as a9, type FFIDRedirectErrorCode as aa, type FFIDSeatModel as ab, FFIDSubscriptionBadge as ac, type FFIDTokenIntrospectionResponse as ad, FFIDUserMenu as ae, FFID_INQUIRY_CATEGORIES as af, FFID_INQUIRY_CATEGORIES_SITE_2026 as ag, type UseFFIDAnnouncementsOptions as ah, type UseFFIDAnnouncementsReturn as ai, isFFIDInquiryCategorySite2026 as aj, useFFIDAnnouncements as ak, type FFIDAnnouncementBadgeClassNames as al, type FFIDAnnouncementBadgeProps as am, type FFIDAnnouncementListClassNames as an, type FFIDAnnouncementListProps as ao, type FFIDLoginButtonProps as ap, type FFIDOrganizationSwitcherClassNames as aq, type FFIDOrganizationSwitcherProps as ar, type FFIDSubscriptionBadgeClassNames as as, type FFIDSubscriptionBadgeProps as at, type FFIDUserMenuClassNames as au, type FFIDUserMenuProps as av, type FFIDApiResponse as b, type FFIDSessionResponse as c, type FFIDRedirectResult as d, type FFIDError as e, type FFIDSubscriptionCheckResponse as f, type FFIDListMembersResponse as g, type FFIDMemberRole as h, type FFIDUpdateMemberRoleResponse as i, type FFIDRemoveMemberResponse as j, type FFIDProfileCallOptions as k, type FFIDUserProfile as l, type FFIDUpdateUserProfileRequest as m, type FFIDCreateCheckoutParams as n, type FFIDCheckoutSessionResponse as o, type FFIDCreatePortalParams as p, type FFIDPortalSessionResponse as q, type FFIDVerifyAccessTokenOptions as r, type FFIDOAuthUserInfo as s, type FFIDInquiryCreateParams as t, type FFIDInquiryCreateResponse as u, type FFIDAuthMode as v, type FFIDLogger as w, type FFIDCacheAdapter as x, type FFIDUser as y, type FFIDOrganization as z };

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkDERFBYBZ_cjs = require('./chunk-DERFBYBZ.cjs');
+var chunkBBXUZS4U_cjs = require('./chunk-BBXUZS4U.cjs');
 var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
@@ -44,9 +44,38 @@ function createKVCacheAdapter(kv) {
     }
   };
 }
+function resolveRedirectUrl(redirectTo, status) {
+  return typeof redirectTo === "function" ? redirectTo(status) : redirectTo;
+}
+function defaultRedirect(url) {
+  if (typeof window === "undefined") return;
+  window.location.href = url;
+}
+function useRequireActiveSubscription(options) {
+  const { redirectTo, allowGrace = true, onRedirect } = options;
+  const { isLoading, error } = chunkBBXUZS4U_cjs.useFFIDContext();
+  const { effectiveStatus, isBlocked, isGrace } = chunkBBXUZS4U_cjs.useSubscription();
+  const hasFetchError = error !== null && effectiveStatus === null;
+  const shouldRedirect = !isLoading && !hasFetchError && (isBlocked || !allowGrace && isGrace || effectiveStatus === null);
+  react.useEffect(() => {
+    if (!shouldRedirect) return;
+    const triggeringStatus = effectiveStatus ?? "blocked";
+    const url = resolveRedirectUrl(redirectTo, triggeringStatus);
+    if (onRedirect) {
+      onRedirect(url);
+    } else {
+      defaultRedirect(url);
+    }
+  }, [shouldRedirect, effectiveStatus]);
+  return {
+    loading: isLoading,
+    effectiveStatus,
+    error
+  };
+}
 function withFFIDAuth(Component, options = {}) {
   const WrappedComponent = (props) => {
-    const { isLoading, isAuthenticated, login } = chunkDERFBYBZ_cjs.useFFIDContext();
+    const { isLoading, isAuthenticated, login } = chunkBBXUZS4U_cjs.useFFIDContext();
     const hasRedirected = react.useRef(false);
     react.useEffect(() => {
       if (!isLoading && !isAuthenticated && options.redirectToLogin && !hasRedirected.current) {
@@ -74,109 +103,114 @@ var FFID_NEWSLETTER_TYPES = ["inquiry_followup", "general"];
 
 Object.defineProperty(exports, "DEFAULT_API_BASE_URL", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.DEFAULT_API_BASE_URL; }
+  get: function () { return chunkBBXUZS4U_cjs.DEFAULT_API_BASE_URL; }
 });
 Object.defineProperty(exports, "FFIDAnnouncementBadge", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFIDAnnouncementBadge; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDAnnouncementBadge; }
 });
 Object.defineProperty(exports, "FFIDAnnouncementList", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFIDAnnouncementList; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDAnnouncementList; }
 });
 Object.defineProperty(exports, "FFIDInquiryForm", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFIDInquiryForm; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDInquiryForm; }
 });
 Object.defineProperty(exports, "FFIDLoginButton", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFIDLoginButton; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDLoginButton; }
 });
 Object.defineProperty(exports, "FFIDOrganizationSwitcher", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFIDOrganizationSwitcher; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDOrganizationSwitcher; }
 });
 Object.defineProperty(exports, "FFIDProvider", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFIDProvider; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDProvider; }
 });
 Object.defineProperty(exports, "FFIDSDKError", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFIDSDKError; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDSDKError; }
 });
 Object.defineProperty(exports, "FFIDSubscriptionBadge", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFIDSubscriptionBadge; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDSubscriptionBadge; }
 });
 Object.defineProperty(exports, "FFIDUserMenu", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFIDUserMenu; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDUserMenu; }
 });
 Object.defineProperty(exports, "FFID_ANNOUNCEMENTS_ERROR_CODES", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFID_ANNOUNCEMENTS_ERROR_CODES; }
+  get: function () { return chunkBBXUZS4U_cjs.FFID_ANNOUNCEMENTS_ERROR_CODES; }
 });
 Object.defineProperty(exports, "FFID_INQUIRY_CATEGORIES", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFID_INQUIRY_CATEGORIES; }
+  get: function () { return chunkBBXUZS4U_cjs.FFID_INQUIRY_CATEGORIES; }
 });
 Object.defineProperty(exports, "FFID_INQUIRY_CATEGORIES_SITE_2026", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.FFID_INQUIRY_CATEGORIES_SITE_2026; }
+  get: function () { return chunkBBXUZS4U_cjs.FFID_INQUIRY_CATEGORIES_SITE_2026; }
+});
+Object.defineProperty(exports, "computeEffectiveStatusFromSession", {
+  enumerable: true,
+  get: function () { return chunkBBXUZS4U_cjs.computeEffectiveStatusFromSession; }
 });
 Object.defineProperty(exports, "createFFIDAnnouncementsClient", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.createFFIDAnnouncementsClient; }
+  get: function () { return chunkBBXUZS4U_cjs.createFFIDAnnouncementsClient; }
 });
 Object.defineProperty(exports, "createFFIDClient", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.createFFIDClient; }
+  get: function () { return chunkBBXUZS4U_cjs.createFFIDClient; }
 });
 Object.defineProperty(exports, "createTokenStore", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.createTokenStore; }
+  get: function () { return chunkBBXUZS4U_cjs.createTokenStore; }
 });
 Object.defineProperty(exports, "generateCodeChallenge", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.generateCodeChallenge; }
+  get: function () { return chunkBBXUZS4U_cjs.generateCodeChallenge; }
 });
 Object.defineProperty(exports, "generateCodeVerifier", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.generateCodeVerifier; }
+  get: function () { return chunkBBXUZS4U_cjs.generateCodeVerifier; }
 });
 Object.defineProperty(exports, "isFFIDInquiryCategorySite2026", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.isFFIDInquiryCategorySite2026; }
+  get: function () { return chunkBBXUZS4U_cjs.isFFIDInquiryCategorySite2026; }
 });
 Object.defineProperty(exports, "normalizeRedirectUri", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.normalizeRedirectUri; }
+  get: function () { return chunkBBXUZS4U_cjs.normalizeRedirectUri; }
 });
 Object.defineProperty(exports, "retrieveCodeVerifier", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.retrieveCodeVerifier; }
+  get: function () { return chunkBBXUZS4U_cjs.retrieveCodeVerifier; }
 });
 Object.defineProperty(exports, "storeCodeVerifier", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.storeCodeVerifier; }
+  get: function () { return chunkBBXUZS4U_cjs.storeCodeVerifier; }
 });
 Object.defineProperty(exports, "useFFID", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.useFFID; }
+  get: function () { return chunkBBXUZS4U_cjs.useFFID; }
 });
 Object.defineProperty(exports, "useFFIDAnnouncements", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.useFFIDAnnouncements; }
+  get: function () { return chunkBBXUZS4U_cjs.useFFIDAnnouncements; }
 });
 Object.defineProperty(exports, "useSubscription", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.useSubscription; }
+  get: function () { return chunkBBXUZS4U_cjs.useSubscription; }
 });
 Object.defineProperty(exports, "withSubscription", {
   enumerable: true,
-  get: function () { return chunkDERFBYBZ_cjs.withSubscription; }
+  get: function () { return chunkBBXUZS4U_cjs.withSubscription; }
 });
 exports.FFID_NEWSLETTER_TYPES = FFID_NEWSLETTER_TYPES;
 exports.createKVCacheAdapter = createKVCacheAdapter;
 exports.createMemoryCacheAdapter = createMemoryCacheAdapter;
+exports.useRequireActiveSubscription = useRequireActiveSubscription;
 exports.withFFIDAuth = withFFIDAuth;