@feelflow/ffid-sdk 2.18.0 → 2.19.0

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--S6rLHjr.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 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.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-IEYXT3LA.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-IEYXT3LA.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 };

package/dist/server/index.cjs

@@ -803,7 +803,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "2.18.0";
+var SDK_VERSION = "2.19.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {

package/dist/server/index.js

@@ -802,7 +802,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "2.18.0";
+var SDK_VERSION = "2.19.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {

package/dist/webhooks/index.d.cts

@@ -59,11 +59,33 @@ interface FFIDSubscriptionUpdatedPayload {
     status?: string;
 }
 interface FFIDSubscriptionCanceledPayload {
+    /** FFID subscription UUID. */
     subscriptionId: string;
-    organizationId?: string;
+    /**
+     * Organization UUID that owned the subscription. Always emitted by the FFID
+     * server (see `src/lib/webhooks/types.ts > SubscriptionCanceledPayload`).
+     */
+    organizationId: string;
+    /**
+     * Stripe subscription id (`sub_...`). `null` when the subscription was
+     * cancelled before Stripe provisioning (e.g. free plans / manual cancels).
+     * Always present on the wire.
+     */
+    stripeSubscriptionId: string | null;
     reason?: string;
     cancelAt?: string;
-    source?: 'user_initiated' | 'stripe_confirmed';
+    /**
+     * Origin of the cancellation. Always emitted by the FFID server — required
+     * by the wire shape in `SubscriptionCanceledPayload`.
+     */
+    source: 'user_initiated' | 'stripe_confirmed' | 'payment_failure_auto_cancel';
+    /** Whether this cancellation can be resumed via resubscribe flow. */
+    reactivatable?: boolean;
+    /**
+     * ISO timestamp at which access was actually lost. May differ from `cancelAt`
+     * when Stripe runs out the paid period before emitting the deletion event.
+     */
+    expiredAt?: string;
 }
 interface FFIDSubscriptionTrialEndingPayload {
     subscriptionId: string;
@@ -71,10 +93,54 @@ interface FFIDSubscriptionTrialEndingPayload {
     trialEndDate: string;
 }
 interface FFIDSubscriptionPaymentFailedPayload {
-    subscriptionId: string;
+    /**
+     * Stripe invoice id (`in_...`) whose payment failed. Always emitted by the
+     * FFID server (see `src/lib/webhooks/types.ts > SubscriptionPaymentFailedPayload`).
+     */
+    stripeInvoiceId: string;
+    /**
+     * Stripe subscription id (`sub_...`) tied to the failed invoice, or `null`
+     * when the invoice was not linked to a subscription. Always emitted by the
+     * FFID server.
+     */
+    stripeSubscriptionId: string | null;
+    /**
+     * FFID subscription UUID resolved from `stripeSubscriptionId`.
+     *
+     * Optional because the server only spreads this field when it could
+     * correlate the Stripe subscription to an FFID row. Consumers should check
+     * {@link correlationUnavailable} before assuming a lookup failure is a
+     * data-quality issue rather than a legitimate unlinked payload.
+     */
+    subscriptionId?: string;
+    /**
+     * Organization UUID that owns the subscription.
+     *
+     * Optional for the same reason as `subscriptionId` (conditionally emitted
+     * when correlation succeeded).
+     */
     organizationId?: string;
-    failureReason?: string;
-    attemptCount?: number;
+    /**
+     * 'warning' during Stripe dunning retries — keep access, surface UI banner.
+     * 'blocking' once retries are exhausted or the grace period has passed — cut off access.
+     */
+    severity?: 'warning' | 'blocking';
+    /**
+     * ISO timestamp at which the grace period ends and severity flips to 'blocking'.
+     * `null` means already blocking.
+     */
+    graceUntil?: string | null;
+    /**
+     * `true` when the FFID server could not resolve `stripeSubscriptionId` to an
+     * FFID subscription row (e.g. race with a not-yet-synced sub, or invoice
+     * without a linked subscription). In that case both `subscriptionId` and
+     * `organizationId` will be absent. Consumers should treat the event as a
+     * best-effort signal and avoid hard failures when this flag is set.
+     *
+     * Added alongside backend change (#2444) so SDK consumers can distinguish
+     * "backend has no mapping yet" from "payload shape regression".
+     */
+    correlationUnavailable?: boolean;
 }
 interface FFIDUserCreatedPayload {
     userId: string;

package/dist/webhooks/index.d.ts

@@ -59,11 +59,33 @@ interface FFIDSubscriptionUpdatedPayload {
     status?: string;
 }
 interface FFIDSubscriptionCanceledPayload {
+    /** FFID subscription UUID. */
     subscriptionId: string;
-    organizationId?: string;
+    /**
+     * Organization UUID that owned the subscription. Always emitted by the FFID
+     * server (see `src/lib/webhooks/types.ts > SubscriptionCanceledPayload`).
+     */
+    organizationId: string;
+    /**
+     * Stripe subscription id (`sub_...`). `null` when the subscription was
+     * cancelled before Stripe provisioning (e.g. free plans / manual cancels).
+     * Always present on the wire.
+     */
+    stripeSubscriptionId: string | null;
     reason?: string;
     cancelAt?: string;
-    source?: 'user_initiated' | 'stripe_confirmed';
+    /**
+     * Origin of the cancellation. Always emitted by the FFID server — required
+     * by the wire shape in `SubscriptionCanceledPayload`.
+     */
+    source: 'user_initiated' | 'stripe_confirmed' | 'payment_failure_auto_cancel';
+    /** Whether this cancellation can be resumed via resubscribe flow. */
+    reactivatable?: boolean;
+    /**
+     * ISO timestamp at which access was actually lost. May differ from `cancelAt`
+     * when Stripe runs out the paid period before emitting the deletion event.
+     */
+    expiredAt?: string;
 }
 interface FFIDSubscriptionTrialEndingPayload {
     subscriptionId: string;
@@ -71,10 +93,54 @@ interface FFIDSubscriptionTrialEndingPayload {
     trialEndDate: string;
 }
 interface FFIDSubscriptionPaymentFailedPayload {
-    subscriptionId: string;
+    /**
+     * Stripe invoice id (`in_...`) whose payment failed. Always emitted by the
+     * FFID server (see `src/lib/webhooks/types.ts > SubscriptionPaymentFailedPayload`).
+     */
+    stripeInvoiceId: string;
+    /**
+     * Stripe subscription id (`sub_...`) tied to the failed invoice, or `null`
+     * when the invoice was not linked to a subscription. Always emitted by the
+     * FFID server.
+     */
+    stripeSubscriptionId: string | null;
+    /**
+     * FFID subscription UUID resolved from `stripeSubscriptionId`.
+     *
+     * Optional because the server only spreads this field when it could
+     * correlate the Stripe subscription to an FFID row. Consumers should check
+     * {@link correlationUnavailable} before assuming a lookup failure is a
+     * data-quality issue rather than a legitimate unlinked payload.
+     */
+    subscriptionId?: string;
+    /**
+     * Organization UUID that owns the subscription.
+     *
+     * Optional for the same reason as `subscriptionId` (conditionally emitted
+     * when correlation succeeded).
+     */
     organizationId?: string;
-    failureReason?: string;
-    attemptCount?: number;
+    /**
+     * 'warning' during Stripe dunning retries — keep access, surface UI banner.
+     * 'blocking' once retries are exhausted or the grace period has passed — cut off access.
+     */
+    severity?: 'warning' | 'blocking';
+    /**
+     * ISO timestamp at which the grace period ends and severity flips to 'blocking'.
+     * `null` means already blocking.
+     */
+    graceUntil?: string | null;
+    /**
+     * `true` when the FFID server could not resolve `stripeSubscriptionId` to an
+     * FFID subscription row (e.g. race with a not-yet-synced sub, or invoice
+     * without a linked subscription). In that case both `subscriptionId` and
+     * `organizationId` will be absent. Consumers should treat the event as a
+     * best-effort signal and avoid hard failures when this flag is set.
+     *
+     * Added alongside backend change (#2444) so SDK consumers can distinguish
+     * "backend has no mapping yet" from "payload shape regression".
+     */
+    correlationUnavailable?: boolean;
 }
 interface FFIDUserCreatedPayload {
     userId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feelflow/ffid-sdk",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "FeelFlow ID Platform SDK for React/Next.js applications",
   "keywords": [
     "feelflow",