@feelflow/ffid-sdk 2.17.1 → 2.19.0

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-Cv1qXIl1.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 FFIDSeatModel, aa as FFIDSubscriptionBadge, ab as FFIDTokenIntrospectionResponse, ac as FFIDUserMenu, ad as FFID_INQUIRY_CATEGORIES, ae as FFID_INQUIRY_CATEGORIES_SITE_2026, af as UseFFIDAnnouncementsOptions, ag as UseFFIDAnnouncementsReturn, ah as isFFIDInquiryCategorySite2026, ai as useFFIDAnnouncements } from './index-Cv1qXIl1.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 };

package/dist/index.d.ts

@@ -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-Cv1qXIl1.js';
-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 FFIDSeatModel, aa as FFIDSubscriptionBadge, ab as FFIDTokenIntrospectionResponse, ac as FFIDUserMenu, ad as FFID_INQUIRY_CATEGORIES, ae as FFID_INQUIRY_CATEGORIES_SITE_2026, af as UseFFIDAnnouncementsOptions, ag as UseFFIDAnnouncementsReturn, ah as isFFIDInquiryCategorySite2026, ai as useFFIDAnnouncements } from './index-Cv1qXIl1.js';
+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.js';
+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.js';
 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 };

package/dist/index.js

@@ -1,6 +1,6 @@
-import { useFFIDContext } from './chunk-FGTRPNSW.js';
-export { DEFAULT_API_BASE_URL, FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDProvider, FFIDSDKError, FFIDSubscriptionBadge, FFIDUserMenu, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_INQUIRY_CATEGORIES, FFID_INQUIRY_CATEGORIES_SITE_2026, createFFIDAnnouncementsClient, createFFIDClient, createTokenStore, generateCodeChallenge, generateCodeVerifier, isFFIDInquiryCategorySite2026, normalizeRedirectUri, retrieveCodeVerifier, storeCodeVerifier, useFFID, useFFIDAnnouncements, useSubscription, withSubscription } from './chunk-FGTRPNSW.js';
-import { useRef, useEffect } from 'react';
+import { useFFIDContext, useSubscription } from './chunk-SXYB5QM3.js';
+export { DEFAULT_API_BASE_URL, FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDProvider, FFIDSDKError, FFIDSubscriptionBadge, FFIDUserMenu, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_INQUIRY_CATEGORIES, FFID_INQUIRY_CATEGORIES_SITE_2026, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createTokenStore, generateCodeChallenge, generateCodeVerifier, isFFIDInquiryCategorySite2026, normalizeRedirectUri, retrieveCodeVerifier, storeCodeVerifier, useFFID, useFFIDAnnouncements, useSubscription, withSubscription } from './chunk-SXYB5QM3.js';
+import { useEffect, useRef } from 'react';
 import { jsx, Fragment } from 'react/jsx-runtime';
 
 // src/client/cache/memory-cache-adapter.ts
@@ -43,6 +43,35 @@ 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 } = useFFIDContext();
+  const { effectiveStatus, isBlocked, isGrace } = useSubscription();
+  const hasFetchError = error !== null && effectiveStatus === null;
+  const shouldRedirect = !isLoading && !hasFetchError && (isBlocked || !allowGrace && isGrace || effectiveStatus === null);
+  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 } = useFFIDContext();
@@ -71,4 +100,4 @@ function withFFIDAuth(Component, options = {}) {
 // src/newsletter/types.ts
 var FFID_NEWSLETTER_TYPES = ["inquiry_followup", "general"];
 
-export { FFID_NEWSLETTER_TYPES, createKVCacheAdapter, createMemoryCacheAdapter, withFFIDAuth };
+export { FFID_NEWSLETTER_TYPES, createKVCacheAdapter, createMemoryCacheAdapter, useRequireActiveSubscription, withFFIDAuth };