@feelflow/ffid-sdk 2.18.0 → 2.19.0

package/dist/{index--S6rLHjr.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
@@ -1301,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 FFIDRedirectErrorCode as a9, type FFIDSeatModel as aa, FFIDSubscriptionBadge as ab, type FFIDTokenIntrospectionResponse as ac, FFIDUserMenu as ad, FFID_INQUIRY_CATEGORIES as ae, FFID_INQUIRY_CATEGORIES_SITE_2026 as af, type UseFFIDAnnouncementsOptions as ag, type UseFFIDAnnouncementsReturn as ah, isFFIDInquiryCategorySite2026 as ai, useFFIDAnnouncements as aj, type FFIDAnnouncementBadgeClassNames as ak, type FFIDAnnouncementBadgeProps as al, type FFIDAnnouncementListClassNames as am, type FFIDAnnouncementListProps as an, type FFIDLoginButtonProps as ao, type FFIDOrganizationSwitcherClassNames as ap, type FFIDOrganizationSwitcherProps as aq, type FFIDSubscriptionBadgeClassNames as ar, type FFIDSubscriptionBadgeProps as as, type FFIDUserMenuClassNames as at, type FFIDUserMenuProps as au, 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 chunkEK2W67BW_cjs = require('./chunk-EK2W67BW.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 } = chunkEK2W67BW_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 chunkEK2W67BW_cjs.DEFAULT_API_BASE_URL; }
+  get: function () { return chunkBBXUZS4U_cjs.DEFAULT_API_BASE_URL; }
 });
 Object.defineProperty(exports, "FFIDAnnouncementBadge", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.FFIDAnnouncementBadge; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDAnnouncementBadge; }
 });
 Object.defineProperty(exports, "FFIDAnnouncementList", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.FFIDAnnouncementList; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDAnnouncementList; }
 });
 Object.defineProperty(exports, "FFIDInquiryForm", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.FFIDInquiryForm; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDInquiryForm; }
 });
 Object.defineProperty(exports, "FFIDLoginButton", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.FFIDLoginButton; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDLoginButton; }
 });
 Object.defineProperty(exports, "FFIDOrganizationSwitcher", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.FFIDOrganizationSwitcher; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDOrganizationSwitcher; }
 });
 Object.defineProperty(exports, "FFIDProvider", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.FFIDProvider; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDProvider; }
 });
 Object.defineProperty(exports, "FFIDSDKError", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.FFIDSDKError; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDSDKError; }
 });
 Object.defineProperty(exports, "FFIDSubscriptionBadge", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.FFIDSubscriptionBadge; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDSubscriptionBadge; }
 });
 Object.defineProperty(exports, "FFIDUserMenu", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.FFIDUserMenu; }
+  get: function () { return chunkBBXUZS4U_cjs.FFIDUserMenu; }
 });
 Object.defineProperty(exports, "FFID_ANNOUNCEMENTS_ERROR_CODES", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_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 chunkEK2W67BW_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 chunkEK2W67BW_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 chunkEK2W67BW_cjs.createFFIDAnnouncementsClient; }
+  get: function () { return chunkBBXUZS4U_cjs.createFFIDAnnouncementsClient; }
 });
 Object.defineProperty(exports, "createFFIDClient", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.createFFIDClient; }
+  get: function () { return chunkBBXUZS4U_cjs.createFFIDClient; }
 });
 Object.defineProperty(exports, "createTokenStore", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.createTokenStore; }
+  get: function () { return chunkBBXUZS4U_cjs.createTokenStore; }
 });
 Object.defineProperty(exports, "generateCodeChallenge", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.generateCodeChallenge; }
+  get: function () { return chunkBBXUZS4U_cjs.generateCodeChallenge; }
 });
 Object.defineProperty(exports, "generateCodeVerifier", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.generateCodeVerifier; }
+  get: function () { return chunkBBXUZS4U_cjs.generateCodeVerifier; }
 });
 Object.defineProperty(exports, "isFFIDInquiryCategorySite2026", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.isFFIDInquiryCategorySite2026; }
+  get: function () { return chunkBBXUZS4U_cjs.isFFIDInquiryCategorySite2026; }
 });
 Object.defineProperty(exports, "normalizeRedirectUri", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.normalizeRedirectUri; }
+  get: function () { return chunkBBXUZS4U_cjs.normalizeRedirectUri; }
 });
 Object.defineProperty(exports, "retrieveCodeVerifier", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.retrieveCodeVerifier; }
+  get: function () { return chunkBBXUZS4U_cjs.retrieveCodeVerifier; }
 });
 Object.defineProperty(exports, "storeCodeVerifier", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.storeCodeVerifier; }
+  get: function () { return chunkBBXUZS4U_cjs.storeCodeVerifier; }
 });
 Object.defineProperty(exports, "useFFID", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.useFFID; }
+  get: function () { return chunkBBXUZS4U_cjs.useFFID; }
 });
 Object.defineProperty(exports, "useFFIDAnnouncements", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.useFFIDAnnouncements; }
+  get: function () { return chunkBBXUZS4U_cjs.useFFIDAnnouncements; }
 });
 Object.defineProperty(exports, "useSubscription", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_cjs.useSubscription; }
+  get: function () { return chunkBBXUZS4U_cjs.useSubscription; }
 });
 Object.defineProperty(exports, "withSubscription", {
   enumerable: true,
-  get: function () { return chunkEK2W67BW_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;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { F as FFIDSubscriptionStatus, a as FFIDConfig, b as FFIDApiResponse, c as FFIDSessionResponse, d as FFIDRedirectResult, e as FFIDError, f as FFIDSubscriptionCheckResponse, g as FFIDListMembersResponse, h as FFIDMemberRole, i as FFIDUpdateMemberRoleResponse, j as FFIDRemoveMemberResponse, k as FFIDProfileCallOptions, l as FFIDUserProfile, m as FFIDUpdateUserProfileRequest, n as FFIDCreateCheckoutParams, o as FFIDCheckoutSessionResponse, p as FFIDCreatePortalParams, q as FFIDPortalSessionResponse, r as FFIDVerifyAccessTokenOptions, s as FFIDOAuthUserInfo, t as FFIDInquiryCreateParams, u as FFIDInquiryCreateResponse, v as FFIDAuthMode, w as FFIDLogger, x as FFIDCacheAdapter, y as FFIDUser, z as FFIDOrganization, A as FFIDSubscription, B as FFIDSubscriptionContextValue, C as FFIDAnnouncementsClientConfig, L as ListAnnouncementsOptions, D as FFIDAnnouncementsApiResponse, E as AnnouncementListResponse, G as FFIDAnnouncementsLogger } from './index--S6rLHjr.cjs';
-export { H as Announcement, I as AnnouncementStatus, J as AnnouncementType, K as FFIDAnnouncementBadge, M as FFIDAnnouncementList, N as FFIDAnnouncementsError, O as FFIDAnnouncementsErrorCode, P as FFIDAnnouncementsServerResponse, Q as FFIDCacheConfig, R as FFIDContextValue, S as FFIDInquiryCategory, T as FFIDInquiryCategorySite2026, 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, a1 as FFIDJwtClaims, a2 as FFIDLoginButton, a3 as FFIDMemberStatus, a4 as FFIDOAuthTokenResponse, a5 as FFIDOAuthUserInfoMemberRole, a6 as FFIDOAuthUserInfoSubscription, a7 as FFIDOrganizationMember, a8 as FFIDOrganizationSwitcher, a9 as FFIDRedirectErrorCode, aa as FFIDSeatModel, ab as FFIDSubscriptionBadge, ac as FFIDTokenIntrospectionResponse, ad as FFIDUserMenu, ae as FFID_INQUIRY_CATEGORIES, af as FFID_INQUIRY_CATEGORIES_SITE_2026, ag as UseFFIDAnnouncementsOptions, ah as UseFFIDAnnouncementsReturn, ai as isFFIDInquiryCategorySite2026, aj as useFFIDAnnouncements } from './index--S6rLHjr.cjs';
+import { F as FFIDSubscriptionStatus, a as FFIDConfig, b as FFIDApiResponse, c as FFIDSessionResponse, d as FFIDRedirectResult, e as FFIDError, f as FFIDSubscriptionCheckResponse, g as FFIDListMembersResponse, h as FFIDMemberRole, i as FFIDUpdateMemberRoleResponse, j as FFIDRemoveMemberResponse, k as FFIDProfileCallOptions, l as FFIDUserProfile, m as FFIDUpdateUserProfileRequest, n as FFIDCreateCheckoutParams, o as FFIDCheckoutSessionResponse, p as FFIDCreatePortalParams, q as FFIDPortalSessionResponse, r as FFIDVerifyAccessTokenOptions, s as FFIDOAuthUserInfo, t as FFIDInquiryCreateParams, u as FFIDInquiryCreateResponse, v as FFIDAuthMode, w as FFIDLogger, x as FFIDCacheAdapter, y as FFIDUser, z as FFIDOrganization, A as FFIDSubscription, B as FFIDSubscriptionContextValue, E as EffectiveSubscriptionStatus, C as FFIDAnnouncementsClientConfig, L as ListAnnouncementsOptions, D as FFIDAnnouncementsApiResponse, G as AnnouncementListResponse, H as FFIDAnnouncementsLogger } from './index-0D2vYSLq.cjs';
+export { I as Announcement, J as AnnouncementStatus, K as AnnouncementType, M as FFIDAnnouncementBadge, N as FFIDAnnouncementList, O as FFIDAnnouncementsError, P as FFIDAnnouncementsErrorCode, Q as FFIDAnnouncementsServerResponse, R as FFIDCacheConfig, S as FFIDContextValue, T as FFIDInquiryCategory, U as FFIDInquiryCategorySite2026, 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, a2 as FFIDJwtClaims, a3 as FFIDLoginButton, a4 as FFIDMemberStatus, a5 as FFIDOAuthTokenResponse, a6 as FFIDOAuthUserInfoMemberRole, a7 as FFIDOAuthUserInfoSubscription, a8 as FFIDOrganizationMember, a9 as FFIDOrganizationSwitcher, aa as FFIDRedirectErrorCode, ab as FFIDSeatModel, ac as FFIDSubscriptionBadge, ad as FFIDTokenIntrospectionResponse, ae as FFIDUserMenu, af as FFID_INQUIRY_CATEGORIES, ag as FFID_INQUIRY_CATEGORIES_SITE_2026, ah as UseFFIDAnnouncementsOptions, ai as UseFFIDAnnouncementsReturn, aj as isFFIDInquiryCategorySite2026, ak as useFFIDAnnouncements } from './index-0D2vYSLq.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType, FC } from 'react';
 
@@ -698,36 +698,47 @@ declare function useFFID(): UseFFIDReturn;
 /**
  * useSubscription Hook
  *
- * Access subscription/contract information for the current service
+ * Access subscription/contract information for the current service.
+ *
+ * Post Chain-of-Pacts (Issue #2444) the hook exposes a semantic
+ * `effectiveStatus` alongside the raw booleans so callers can branch on a
+ * single access-control value instead of re-deriving `past_due_grace` vs.
+ * `blocked` in every component. See
+ * `docs/03-implementation/EXPIRED_CONTRACT_HANDLING.md` for the full recipe.
  *
  * @example
  * ```tsx
  * import { useSubscription } from '@feelflow/ffid-sdk'
  *
  * function PremiumFeature() {
- *   const { isActive, hasPlan, planCode } = useSubscription()
+ *   const { effectiveStatus, hasAccess, isGrace, hasPlan } = useSubscription()
  *
- *   if (!isActive) {
- *     return <div>契約が必要です</div>
+ *   if (!hasAccess()) {
+ *     return <div>契約が必要です（状態: {effectiveStatus}）</div>
  *   }
  *
  *   if (!hasPlan(['pro', 'enterprise'])) {
  *     return <div>プロプラン以上が必要です</div>
  *   }
  *
- *   return <div>Premium Content</div>
+ *   return (
+ *     <>
+ *       {isGrace && <PaymentFailedBanner />}
+ *       <PremiumContent />
+ *     </>
+ *   )
  * }
  * ```
  */
 
 /**
- * Hook to access subscription information
+ * Hook to access subscription information.
  *
- * Must be used within FFIDProvider
+ * Must be used within `FFIDProvider`.
  */
 declare function useSubscription(): FFIDSubscriptionContextValue;
 /**
- * HOC to require subscription for a component
+ * HOC to require subscription for a component.
  *
  * @example
  * ```tsx
@@ -749,6 +760,89 @@ interface WithSubscriptionOptions {
 }
 declare function withSubscription<P extends object>(Component: ComponentType<P>, options?: WithSubscriptionOptions): FC<P>;
 
+/**
+ * Options accepted by {@link useRequireActiveSubscription}.
+ */
+interface UseRequireActiveSubscriptionOptions {
+    /**
+     * Destination to redirect to when the subscription is blocked.
+     *
+     * - `string` — used verbatim.
+     * - `(status) => string` — invoked with the triggering
+     *   {@link EffectiveSubscriptionStatus} so callers can route
+     *   `canceled` to a different landing page than `blocked`, etc.
+     */
+    redirectTo: string | ((status: EffectiveSubscriptionStatus) => string);
+    /**
+     * Whether to treat `past_due_grace` as "still allowed".
+     * Defaults to `true` — matches the canonical FFID behaviour of showing
+     * a warning banner while Stripe retries the invoice. Flip to `false` to
+     * treat any non-`active` state as a hard block.
+     */
+    allowGrace?: boolean;
+    /**
+     * Side effect that performs the actual navigation. Receives the resolved
+     * URL (after running `redirectTo` against the effective status) and is
+     * only ever called in the browser. When omitted the hook falls back to
+     * `window.location.href = url` — convenient for pages that do not use a
+     * router.
+     */
+    onRedirect?: (url: string) => void;
+}
+/**
+ * Return value of {@link useRequireActiveSubscription}.
+ */
+interface UseRequireActiveSubscriptionReturn {
+    /**
+     * `true` while the FFID session is still being fetched. Consumers should
+     * render a loading state until this turns `false` to avoid rendering
+     * protected UI behind the upcoming redirect.
+     */
+    loading: boolean;
+    /**
+     * The effective subscription status that drove the guard decision.
+     * `null` when there is no subscription for the current service (the hook
+     * will then trigger a redirect on the first non-loading render).
+     */
+    effectiveStatus: EffectiveSubscriptionStatus | null;
+    /**
+     * Surfaces the FFID context error (session fetch failure, token exchange
+     * error, etc.) so callers can render a retry surface instead of redirecting
+     * through the "contract required" flow. When `error` is non-null **and**
+     * `effectiveStatus === null`, the hook intentionally skips the redirect
+     * side effect — the subscription-less state is indistinguishable from a
+     * transient fetch failure, so routing the user to a hard paywall would
+     * punish an intermittent network blip. Callers that want to force a
+     * redirect anyway can invoke `onRedirect` manually after inspecting
+     * `error`.
+     */
+    error: FFIDError | null;
+}
+/**
+ * Guard a React tree against expired / blocked / cancelled subscriptions.
+ *
+ * The hook does nothing while the FFID provider is still loading, then —
+ * on the next render — evaluates `effectiveStatus` and fires the configured
+ * redirect when the subscription is in a blocking state. Returning
+ * `{ loading, effectiveStatus, error }` lets the caller render a skeleton /
+ * null placeholder during the transition rather than flashing protected
+ * content, and surface a retry affordance when the FFID fetch itself failed.
+ *
+ * **Error surface (S-H3)**: when the FFID context is in an error state AND
+ * there is no subscription (`effectiveStatus === null`), the hook
+ * intentionally **does not redirect**. A network blip should not send the
+ * user to the "contract required" page — the consumer is expected to
+ * inspect `error` and render a retry UI, or call `onRedirect` manually if
+ * a forced redirect is still appropriate.
+ *
+ * The redirect effect runs at most once per resolved status (tracked via
+ * React's dependency array) so consumers do not need to memoise
+ * `redirectTo` / `onRedirect` for correctness. Subsequent status changes
+ * (e.g. the user reactivates their contract in another tab and the session
+ * refreshes to `active`) naturally cancel the pending redirect.
+ */
+declare function useRequireActiveSubscription(options: UseRequireActiveSubscriptionOptions): UseRequireActiveSubscriptionReturn;
+
 /**
  * withFFIDAuth HOC
  *
@@ -811,6 +905,82 @@ interface WithFFIDAuthOptions {
  */
 declare function withFFIDAuth<P extends object>(Component: ComponentType<P>, options?: WithFFIDAuthOptions): FC<P>;
 
+/**
+ * Local fallback for `EffectiveSubscriptionStatus`.
+ *
+ * The canonical value is produced by the FFID backend on
+ * `/api/v1/subscriptions/ext/check`. This helper exists to cover cases where
+ * the SDK only has the fields carried by the OAuth session response
+ * (`status`, `currentPeriodEnd`, `trialEnd`) — for example in `useSubscription`
+ * which reads from the React context, not from `/ext/check`.
+ *
+ * The mapping intentionally mirrors `getEffectiveSubscriptionStatus` /
+ * `EffectiveSubscriptionStatus` in `src/lib/common/subscription-helpers.ts`.
+ * When the server ships the authoritative `effectiveStatus`, callers should
+ * prefer it over this local approximation.
+ *
+ * Limitations (documented so callers can reason about accuracy):
+ *
+ * - **`past_due` is resolved via a 7-day grace window** anchored on
+ *   `pastDueSince` (when supplied) or `currentPeriodEnd` (best-effort
+ *   fallback — Stripe flips `past_due` at/around period end). Within the
+ *   window the status is `past_due_grace`; past the window it flips to
+ *   `blocked`. When both timestamps are missing (or unparseable) the
+ *   function fails closed to `blocked`. The grace window length is
+ *   duplicated from the FFID backend constant of the same name — see
+ *   {@link PAST_DUE_GRACE_PERIOD_DAYS} for the sync invariant.
+ * - **`paused` / `incomplete` are mapped to `active` (fail-open).** Matches
+ *   the FFID backend `computeEffectiveStatus` (`src/lib/common/subscription-
+ *   helpers.ts`) which keeps access live for these transient intents — the
+ *   server has richer context (Stripe webhook order, seat assignment state)
+ *   so it fails open, and the SDK aligns to avoid the consumer seeing a
+ *   different verdict than `/ext/check`.
+ * - **`pending_invoice` is mapped to `active`.** This is a transient state
+ *   between invoice finalisation and payment, and FFID keeps access live for
+ *   the organisation during that window.
+ */
+
+/**
+ * Inputs required to approximate `EffectiveSubscriptionStatus` from session
+ * data alone. Kept as a small record so unit tests do not need to build full
+ * `FFIDSubscription` objects.
+ */
+interface ComputeEffectiveStatusInput {
+    /** Raw DB status as reported by FFID. */
+    status: FFIDSubscriptionStatus;
+    /** ISO 8601 timestamp of the current billing period end, or `null` for seatless / free plans. */
+    currentPeriodEnd: string | null;
+    /** ISO 8601 timestamp of the trial end, or `null` if not on a trial. */
+    trialEnd: string | null;
+    /**
+     * ISO 8601 timestamp of when the subscription first entered `past_due`.
+     *
+     * Carried alongside the session response when available (currently not
+     * emitted — see TODO in `useSubscription` that tracks the session API
+     * extension). When absent, the compute helper falls back to
+     * `currentPeriodEnd` as a best-effort proxy (Stripe flips `past_due` at /
+     * near period end, so the proxy is within ~1 dunning retry cycle). When
+     * both timestamps are missing or unparseable the helper fails closed to
+     * `blocked`.
+     */
+    pastDueSince?: string | null | undefined;
+}
+/**
+ * Compute an `EffectiveSubscriptionStatus` from the fields available in the
+ * session response. Designed as a pure function so it can be reused by
+ * `useSubscription` and by any caller that needs a best-effort access-control
+ * decision without waiting for an `/ext/check` round-trip.
+ *
+ * Callers SHOULD prefer the `effectiveStatus` returned by the FFID server
+ * (`/api/v1/subscriptions/ext/check`) when available — it has access to grace
+ * window information (`graceUntil`) that the SDK cannot see.
+ *
+ * @param input - Session-level subscription fields.
+ * @param nowMs - Override for "now", injected for deterministic tests.
+ *                Defaults to `Date.now()`.
+ */
+declare function computeEffectiveStatusFromSession(input: ComputeEffectiveStatusInput, nowMs?: number): EffectiveSubscriptionStatus;
+
 /**
  * FFID Announcements API Client
  *
@@ -937,4 +1107,4 @@ declare function createInquiryMethods(deps: InquiryMethodsDeps): {
 };
 type FFIDInquiryClient = ReturnType<typeof createInquiryMethods>;
 
-export { AnnouncementListResponse, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, FFIDCreateCheckoutParams, FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, FFIDMemberRole, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOrganization, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, type FFIDPreviewSeatChangeParams, FFIDProfileCallOptions, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, FFIDRemoveMemberResponse, type FFIDResetSessionResponse, FFIDSDKError, type FFIDSeatChangeLineItem, type FFIDSeatChangePreview, type FFIDSeatChangePreviewResponse, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, FFIDUpdateMemberRoleResponse, FFIDUpdateUserProfileRequest, FFIDUser, FFIDUserProfile, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_TYPES, type KVNamespaceLike, ListAnnouncementsOptions, type NormalizeRedirectUriResult, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, normalizeRedirectUri, retrieveCodeVerifier, storeCodeVerifier, useFFID, useSubscription, withFFIDAuth, withSubscription };
+export { AnnouncementListResponse, type ComputeEffectiveStatusInput, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, EffectiveSubscriptionStatus, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, FFIDCreateCheckoutParams, FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, FFIDMemberRole, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOrganization, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, type FFIDPreviewSeatChangeParams, FFIDProfileCallOptions, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, FFIDRemoveMemberResponse, type FFIDResetSessionResponse, FFIDSDKError, type FFIDSeatChangeLineItem, type FFIDSeatChangePreview, type FFIDSeatChangePreviewResponse, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, FFIDUpdateMemberRoleResponse, FFIDUpdateUserProfileRequest, FFIDUser, FFIDUserProfile, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_TYPES, type KVNamespaceLike, ListAnnouncementsOptions, type NormalizeRedirectUriResult, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type UseRequireActiveSubscriptionOptions, type UseRequireActiveSubscriptionReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, normalizeRedirectUri, retrieveCodeVerifier, storeCodeVerifier, useFFID, useRequireActiveSubscription, useSubscription, withFFIDAuth, withSubscription };