@feelflow/ffid-sdk 2.18.0 → 2.19.0

package/README.md

@@ -206,16 +206,51 @@ const {
 
 ```tsx
 const {
-  subscription,  // FFIDSubscription | null - 現在のサブスクリプション
-  planCode,      // string | null - プランコード
-  isActive,      // boolean - アクティブ契約
-  isTrialing,    // boolean - トライアル中
-  isCanceled,    // boolean - 解約済み
-  hasPlan,       // (plans: string | string[]) => boolean - プラン確認
-  hasAccess,     // () => boolean - アクセス権確認
+  subscription,     // FFIDSubscription | null - 現在のサブスクリプション
+  planCode,         // string | null - プランコード
+  isActive,         // boolean - DB ステータスが 'active'
+  isTrialing,       // boolean - トライアル中
+  isCanceled,       // boolean - 解約済み
+  isTrialExpired,   // boolean - トライアル期間超過
+  effectiveStatus,  // EffectiveSubscriptionStatus | null - 意味論的アクセス制御値
+  isBlocked,        // boolean - blocked / expired / canceled / trial_expired
+  isGrace,          // boolean - past_due_grace (支払い失敗の猶予期間中)
+  hasPlan,          // (plans: string | string[]) => boolean - プラン確認
+  hasAccess,        // () => boolean - アクセス権確認 (active || past_due_grace)
+  hasAccessLegacy,  // () => boolean - 旧セマンティクス (active || trialing, pre-2.19)
 } = useSubscription()
 ```
 
+`effectiveStatus` は `/api/v1/subscriptions/ext/check` が返す意味論的ステータスと同じ値を取る。詳細は [契約期限切れハンドリング](#契約期限切れハンドリング) を参照。
+
+### useRequireActiveSubscription()
+
+契約が期限切れ/遮断状態のときに自動でリダイレクトするフック。
+
+```tsx
+'use client'
+import { useRouter } from 'next/navigation'
+import { useRequireActiveSubscription } from '@feelflow/ffid-sdk'
+
+function ProtectedShell({ children }: { children: React.ReactNode }) {
+  const router = useRouter()
+  const { loading } = useRequireActiveSubscription({
+    redirectTo: (status) =>
+      status === 'canceled' ? '/contract-ended' : '/contract-required',
+    onRedirect: (url) => router.replace(url),
+  })
+
+  if (loading) return <FullPageSpinner />
+  return <>{children}</>
+}
+```
+
+オプション:
+
+- `redirectTo`: `string` または `(status: EffectiveSubscriptionStatus) => string`
+- `allowGrace` (default: `true`): `past_due_grace` を通過させるか
+- `onRedirect` (optional): 独自のリダイレクト関数（未指定時は `window.location.href`）
+
 ### withSubscription()
 
 サブスクリプション確認HOC。
@@ -228,6 +263,34 @@ const PremiumFeature = withSubscription(MyComponent, {
 })
 ```
 
+## 契約期限切れハンドリング
+
+契約が失効したり解約されたとき、外部サービス側で適切にアクセスを遮断し、ユーザーを再契約動線に案内する必要があります。SDK は 3 層構成（トークン検証 / 契約チェック / Webhook 受信）をサポートしています。
+
+### 最小構成（Next.js App Router）
+
+```tsx
+'use client'
+import { useRouter } from 'next/navigation'
+import { useRequireActiveSubscription } from '@feelflow/ffid-sdk'
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  const router = useRouter()
+  const { loading, effectiveStatus } = useRequireActiveSubscription({
+    redirectTo: '/contract-required',
+    onRedirect: (url) => router.replace(url),
+  })
+
+  if (loading) return <Spinner />
+  if (effectiveStatus !== 'active' && effectiveStatus !== 'past_due_grace') {
+    return null // リダイレクト発火中
+  }
+  return <>{children}</>
+}
+```
+
+**詳細な実装レシピ**（middleware、Express、UI 分岐、Webhook 受信、fixture API を使ったテスト、`EffectiveSubscriptionStatus` 別の UI 推奨動作まで） → [docs/03-implementation/EXPIRED_CONTRACT_HANDLING.md](https://github.com/feel-flow/feelflow-id-platform/blob/develop/docs/03-implementation/EXPIRED_CONTRACT_HANDLING.md)
+
 ### getProfile() / updateProfile()
 
 ログイン中ユーザー自身のプロフィールを取得・更新するメソッド（`createFFIDClient` から呼び出し）。

package/dist/{chunk-EK2W67BW.cjs → chunk-BBXUZS4U.cjs}

@@ -807,7 +807,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() {
@@ -3162,6 +3162,67 @@ function FFIDOrganizationSwitcher({
     ] })
   ] });
 }
+
+// src/subscriptions/types.ts
+var PAST_DUE_GRACE_PERIOD_DAYS = 7;
+var HOURS_PER_DAY = 24;
+var MINUTES_PER_HOUR = 60;
+var SECONDS_PER_MINUTE = 60;
+var MS_PER_SECOND2 = 1e3;
+var MS_PER_DAY = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND2;
+
+// src/subscriptions/compute-effective-status.ts
+function isExpired(isoTimestamp, nowMs) {
+  if (!isoTimestamp) return null;
+  const parsed = Date.parse(isoTimestamp);
+  if (Number.isNaN(parsed)) return null;
+  return parsed < nowMs;
+}
+function computeEffectiveStatusFromSession(input, nowMs = Date.now()) {
+  const { status, currentPeriodEnd, trialEnd, pastDueSince } = input;
+  switch (status) {
+    case "trialing": {
+      const relevantEnd = trialEnd ?? currentPeriodEnd;
+      const expired = isExpired(relevantEnd, nowMs);
+      return expired === true ? "trial_expired" : "active";
+    }
+    case "active": {
+      const expired = isExpired(currentPeriodEnd, nowMs);
+      return expired === true ? "expired" : "active";
+    }
+    case "past_due": {
+      const baselineIso = pastDueSince ?? currentPeriodEnd;
+      if (!baselineIso) return "blocked";
+      const baselineMs = Date.parse(baselineIso);
+      if (Number.isNaN(baselineMs)) return "blocked";
+      const graceEndMs = baselineMs + PAST_DUE_GRACE_PERIOD_DAYS * MS_PER_DAY;
+      return graceEndMs > nowMs ? "past_due_grace" : "blocked";
+    }
+    case "pending_invoice":
+      return "active";
+    case "paused":
+    case "incomplete":
+      return "active";
+    case "canceled":
+      return "canceled";
+    case "unpaid":
+    case "incomplete_expired":
+      return "blocked";
+    default: {
+      return "blocked";
+    }
+  }
+}
+var ACCESS_GRANTING_STATUSES = [
+  "active",
+  "past_due_grace"
+];
+var BLOCKING_STATUSES = [
+  "blocked",
+  "expired",
+  "canceled",
+  "trial_expired"
+];
 function useSubscription() {
   const context = useFFIDContext();
   const client = useFFIDClient();
@@ -3179,12 +3240,23 @@ function useSubscription() {
   const isActive = subscription?.status === "active";
   const isTrialing = subscription?.status === "trialing";
   const isCanceled = subscription?.status === "canceled";
-  const isTrialExpired = react.useMemo(() => {
-    if (!isTrialing) return false;
-    const relevantEnd = subscription?.trialEnd ?? subscription?.currentPeriodEnd;
-    if (!relevantEnd) return false;
-    return new Date(relevantEnd).getTime() < Date.now();
-  }, [isTrialing, subscription?.trialEnd, subscription?.currentPeriodEnd]);
+  const effectiveStatus = react.useMemo(() => {
+    if (!subscription) return null;
+    return computeEffectiveStatusFromSession({
+      status: subscription.status,
+      currentPeriodEnd: subscription.currentPeriodEnd,
+      trialEnd: subscription.trialEnd,
+      // TODO(別Issue): FFID backend の session API (`/api/auth/session`) に
+      //   `pastDueSince` (ISO timestamp) を追加し、ここで渡す。現状は undefined
+      //   のため `computeEffectiveStatusFromSession` 内で currentPeriodEnd を
+      //   fallback に使う (Stripe は period end 近辺で past_due にする)。
+      //   Canonical な verdict が必要な consumer は `/ext/check` を直接呼ぶ。
+      pastDueSince: void 0
+    });
+  }, [subscription]);
+  const isGrace = effectiveStatus === "past_due_grace";
+  const isBlocked = effectiveStatus !== null && BLOCKING_STATUSES.includes(effectiveStatus);
+  const isTrialExpired = effectiveStatus === "trial_expired";
   const hasPlan = react.useCallback(
     (plans) => {
       if (!planCode) return false;
@@ -3194,6 +3266,10 @@ function useSubscription() {
     [planCode]
   );
   const hasAccess = react.useCallback(() => {
+    if (effectiveStatus === null) return false;
+    return ACCESS_GRANTING_STATUSES.includes(effectiveStatus);
+  }, [effectiveStatus]);
+  const hasAccessLegacy = react.useCallback(() => {
     if (isTrialExpired) return false;
     return isActive || isTrialing;
   }, [isActive, isTrialing, isTrialExpired]);
@@ -3204,8 +3280,12 @@ function useSubscription() {
     isTrialing,
     isTrialExpired,
     isCanceled,
+    effectiveStatus,
+    isBlocked,
+    isGrace,
     hasPlan,
-    hasAccess
+    hasAccess,
+    hasAccessLegacy
   };
 }
 function withSubscription(Component, options = {}) {
@@ -4441,6 +4521,7 @@ exports.FFIDUserMenu = FFIDUserMenu;
 exports.FFID_ANNOUNCEMENTS_ERROR_CODES = FFID_ANNOUNCEMENTS_ERROR_CODES;
 exports.FFID_INQUIRY_CATEGORIES = FFID_INQUIRY_CATEGORIES;
 exports.FFID_INQUIRY_CATEGORIES_SITE_2026 = FFID_INQUIRY_CATEGORIES_SITE_2026;
+exports.computeEffectiveStatusFromSession = computeEffectiveStatusFromSession;
 exports.createFFIDAnnouncementsClient = createFFIDAnnouncementsClient;
 exports.createFFIDClient = createFFIDClient;
 exports.createTokenStore = createTokenStore;

package/dist/{chunk-IEYXT3LA.js → chunk-SXYB5QM3.js}

@@ -805,7 +805,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() {
@@ -3160,6 +3160,67 @@ function FFIDOrganizationSwitcher({
     ] })
   ] });
 }
+
+// src/subscriptions/types.ts
+var PAST_DUE_GRACE_PERIOD_DAYS = 7;
+var HOURS_PER_DAY = 24;
+var MINUTES_PER_HOUR = 60;
+var SECONDS_PER_MINUTE = 60;
+var MS_PER_SECOND2 = 1e3;
+var MS_PER_DAY = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND2;
+
+// src/subscriptions/compute-effective-status.ts
+function isExpired(isoTimestamp, nowMs) {
+  if (!isoTimestamp) return null;
+  const parsed = Date.parse(isoTimestamp);
+  if (Number.isNaN(parsed)) return null;
+  return parsed < nowMs;
+}
+function computeEffectiveStatusFromSession(input, nowMs = Date.now()) {
+  const { status, currentPeriodEnd, trialEnd, pastDueSince } = input;
+  switch (status) {
+    case "trialing": {
+      const relevantEnd = trialEnd ?? currentPeriodEnd;
+      const expired = isExpired(relevantEnd, nowMs);
+      return expired === true ? "trial_expired" : "active";
+    }
+    case "active": {
+      const expired = isExpired(currentPeriodEnd, nowMs);
+      return expired === true ? "expired" : "active";
+    }
+    case "past_due": {
+      const baselineIso = pastDueSince ?? currentPeriodEnd;
+      if (!baselineIso) return "blocked";
+      const baselineMs = Date.parse(baselineIso);
+      if (Number.isNaN(baselineMs)) return "blocked";
+      const graceEndMs = baselineMs + PAST_DUE_GRACE_PERIOD_DAYS * MS_PER_DAY;
+      return graceEndMs > nowMs ? "past_due_grace" : "blocked";
+    }
+    case "pending_invoice":
+      return "active";
+    case "paused":
+    case "incomplete":
+      return "active";
+    case "canceled":
+      return "canceled";
+    case "unpaid":
+    case "incomplete_expired":
+      return "blocked";
+    default: {
+      return "blocked";
+    }
+  }
+}
+var ACCESS_GRANTING_STATUSES = [
+  "active",
+  "past_due_grace"
+];
+var BLOCKING_STATUSES = [
+  "blocked",
+  "expired",
+  "canceled",
+  "trial_expired"
+];
 function useSubscription() {
   const context = useFFIDContext();
   const client = useFFIDClient();
@@ -3177,12 +3238,23 @@ function useSubscription() {
   const isActive = subscription?.status === "active";
   const isTrialing = subscription?.status === "trialing";
   const isCanceled = subscription?.status === "canceled";
-  const isTrialExpired = useMemo(() => {
-    if (!isTrialing) return false;
-    const relevantEnd = subscription?.trialEnd ?? subscription?.currentPeriodEnd;
-    if (!relevantEnd) return false;
-    return new Date(relevantEnd).getTime() < Date.now();
-  }, [isTrialing, subscription?.trialEnd, subscription?.currentPeriodEnd]);
+  const effectiveStatus = useMemo(() => {
+    if (!subscription) return null;
+    return computeEffectiveStatusFromSession({
+      status: subscription.status,
+      currentPeriodEnd: subscription.currentPeriodEnd,
+      trialEnd: subscription.trialEnd,
+      // TODO(別Issue): FFID backend の session API (`/api/auth/session`) に
+      //   `pastDueSince` (ISO timestamp) を追加し、ここで渡す。現状は undefined
+      //   のため `computeEffectiveStatusFromSession` 内で currentPeriodEnd を
+      //   fallback に使う (Stripe は period end 近辺で past_due にする)。
+      //   Canonical な verdict が必要な consumer は `/ext/check` を直接呼ぶ。
+      pastDueSince: void 0
+    });
+  }, [subscription]);
+  const isGrace = effectiveStatus === "past_due_grace";
+  const isBlocked = effectiveStatus !== null && BLOCKING_STATUSES.includes(effectiveStatus);
+  const isTrialExpired = effectiveStatus === "trial_expired";
   const hasPlan = useCallback(
     (plans) => {
       if (!planCode) return false;
@@ -3192,6 +3264,10 @@ function useSubscription() {
     [planCode]
   );
   const hasAccess = useCallback(() => {
+    if (effectiveStatus === null) return false;
+    return ACCESS_GRANTING_STATUSES.includes(effectiveStatus);
+  }, [effectiveStatus]);
+  const hasAccessLegacy = useCallback(() => {
     if (isTrialExpired) return false;
     return isActive || isTrialing;
   }, [isActive, isTrialing, isTrialExpired]);
@@ -3202,8 +3278,12 @@ function useSubscription() {
     isTrialing,
     isTrialExpired,
     isCanceled,
+    effectiveStatus,
+    isBlocked,
+    isGrace,
     hasPlan,
-    hasAccess
+    hasAccess,
+    hasAccessLegacy
   };
 }
 function withSubscription(Component, options = {}) {
@@ -4426,4 +4506,4 @@ function FFIDInquiryForm({
   );
 }
 
-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, useFFIDContext, useSubscription, withSubscription };
+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, useFFIDContext, useSubscription, withSubscription };

package/dist/components/index.cjs

@@ -1,34 +1,34 @@
 'use strict';
 
-var chunkEK2W67BW_cjs = require('../chunk-EK2W67BW.cjs');
+var chunkBBXUZS4U_cjs = require('../chunk-BBXUZS4U.cjs');
 
 
 
 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, "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; }
 });

package/dist/components/index.d.cts

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

package/dist/components/index.d.ts

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

package/dist/components/index.js

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

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

@@ -22,6 +22,42 @@ interface FFIDCacheConfig {
     ttl: number;
 }
 
+/**
+ * Subscription access-control types (Chain of Pacts / Issue #2443).
+ *
+ * Defines `EffectiveSubscriptionStatus` — the semantic status surfaced by
+ * `/api/v1/subscriptions/ext/check` for external services that need a single
+ * value to drive access-control decisions. Mirrors the server-side type in
+ * `src/lib/common/subscription-helpers.ts` so the FFID backend, SDK, and
+ * consuming services agree on the same vocabulary.
+ */
+/**
+ * Semantic subscription status used for access-control decisions by external
+ * services.
+ *
+ * Unlike the raw DB `FFIDSubscriptionStatus` (which keeps the Stripe-aligned
+ * status machine, e.g. `past_due` / `incomplete` / `incomplete_expired`), this
+ * narrowed union flattens dunning-window vs. hard-block cases so callers can
+ * branch on a single value:
+ *
+ * - `active` — normal paying subscription; grant full access.
+ * - `past_due_grace` — payment failed but FFID is still retrying. Service
+ *   SHOULD keep access and surface a recovery banner.
+ * - `blocked` — payment dunning exhausted (`past_due` over grace,
+ *   `unpaid`, `incomplete_expired`, `paused`, `incomplete`). Deny access.
+ * - `canceled` — contract ended (voluntary or auto-cancel). Deny access;
+ *   check the accompanying `reactivatable` flag before showing a restart CTA.
+ * - `trial_expired` — `status = 'trialing'` but the trial end is in the past.
+ *   DB row is still `trialing`; deny access and prompt for a paid plan.
+ * - `expired` — `status = 'active'` but `current_period_end` is in the past.
+ *   This is the FFID-internal runtime-expired case (see
+ *   `getEffectiveSubscriptionStatus` on the server). Deny access.
+ *
+ * @see /api/v1/subscriptions/ext/check
+ * @see docs/03-implementation/EXPIRED_CONTRACT_HANDLING.md
+ */
+type EffectiveSubscriptionStatus = 'active' | 'past_due_grace' | 'blocked' | 'canceled' | 'trial_expired' | 'expired';
+
 /**
  * FFID SDK Type Definitions
  *
@@ -284,10 +320,59 @@ interface FFIDSubscriptionContextValue {
     isTrialExpired: boolean;
     /** Whether subscription is canceled */
     isCanceled: boolean;
+    /**
+     * Semantic access-control status for the current subscription.
+     *
+     * Always computed locally from the session response via
+     * `computeEffectiveStatusFromSession` (status + currentPeriodEnd + trialEnd).
+     * The session endpoint does not currently surface an authoritative
+     * effectiveStatus, so this is a best-effort approximation suitable for UI
+     * decisions that tolerate ~1 request worth of staleness.
+     *
+     * For authoritative decisions (e.g., paywall gates on billing-critical UI,
+     * grace-window banners that depend on `gracePeriodEndsAt`, or reactivation
+     * CTAs that depend on `reactivatable`), call the server-side
+     * `/api/v1/subscriptions/ext/check` endpoint directly — it returns a richer
+     * payload (`effectiveStatus`, `gracePeriodEndsAt`, `reactivatable`) computed
+     * against the live DB.
+     *
+     * `null` when there is no subscription for the current service.
+     *
+     * @see {@link EffectiveSubscriptionStatus}
+     */
+    effectiveStatus: EffectiveSubscriptionStatus | null;
+    /**
+     * Whether the subscription is in an access-blocking terminal state
+     * (`blocked` | `expired` | `canceled` | `trial_expired`).
+     */
+    isBlocked: boolean;
+    /**
+     * Whether the subscription is inside the payment-failure grace window
+     * (`past_due_grace`). Access is still granted by `hasAccess`, but UIs
+     * should surface a recovery banner.
+     */
+    isGrace: boolean;
     /** Check if user has specific plan */
     hasPlan: (plans: string | string[]) => boolean;
-    /** Check if user has access (active or trialing subscription) */
+    /**
+     * Whether the user currently has access.
+     *
+     * Post Chain-of-Pacts (Issue #2444): `true` when
+     * `effectiveStatus === 'active' || effectiveStatus === 'past_due_grace'`.
+     * Legacy consumers that need the pre-2444 semantics
+     * (`status === 'active' || status === 'trialing'`) can use
+     * `hasAccessLegacy()`.
+     */
     hasAccess: () => boolean;
+    /**
+     * Pre-2444 `hasAccess` semantics: `true` when the raw DB status is
+     * `active` or `trialing` (and, for trialing, the trial is not runtime-
+     * expired). Kept as a backwards-compatibility escape hatch so services
+     * that have not yet migrated to the effective-status model keep working.
+     *
+     * @deprecated Prefer `hasAccess()` or branch on `effectiveStatus` directly.
+     */
+    hasAccessLegacy: () => boolean;
 }
 /**
  * Logger interface for SDK debug output
@@ -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 };