@feelflow/ffid-sdk 4.0.0 → 4.2.0

package/README.md

@@ -291,6 +291,37 @@ export default function Layout({ children }: { children: React.ReactNode }) {
 
 **詳細な実装レシピ**（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)
 
+### Server-side service access decision
+
+API route / middleware では `checkServiceAccess()` を使う。FFID の `/api/v1/subscriptions/ext/check` が返す canonical decision をそのまま受け取り、外部サービス側で `past_due_since + 7d`、`current_period_end + 7d`、`payment_failed_at + 7d` のような lifecycle date math を再実装しない。
+
+```ts
+import { createFFIDClient } from '@feelflow/ffid-sdk'
+
+const ffid = createFFIDClient({
+  serviceCode: 'flow-board-ai',
+  scope: '',
+  authMode: 'service-key',
+  serviceApiKey: process.env.FFID_SERVICE_API_KEY!,
+})
+
+const { data: access, error } = await ffid.checkServiceAccess({
+  userId,
+  organizationId,
+  allowGrace: true,
+})
+
+if (error || !access?.hasAccess) {
+  return Response.redirect('/contract-required')
+}
+```
+
+- `checkServiceAccess()` は **`data.hasAccess` が唯一の gate**。`result.error` は入力 validation など SDK が decision を作れない場合にだけ返る。
+- `hasAccess`: FFID が決めた canonical access decision。`allowGrace=false` のときだけ SDK 側で `past_due_grace` を deny に変換する。
+- `effectiveStatus`: `active` / `past_due_grace` / `blocked` / `canceled` / `trial_expired` / `expired`。
+- `gracePeriodEndsAt`: `past_due_grace` が `blocked` に変わる時刻。表示・警告用であり、アクセス判定の source of truth にしない。
+- `failPolicy`: 現在は `failClosed` 固定。FFID に到達できない、または canonical decision を取得できない場合は `result.error` ではなく `data.hasAccess=false` / `denialReason='ffid_unreachable'` / `data.error` を返す。呼び出し側は `result.error` だけで通過判定しない。
+
 ### getProfile() / updateProfile()
 
 ログイン中ユーザー自身のプロフィールを取得・更新するメソッド（`createFFIDClient` から呼び出し）。

package/dist/{chunk-XQL4YSTL.cjs → chunk-U4XDH7TI.cjs}

@@ -808,7 +808,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "4.0.0";
+var SDK_VERSION = "4.2.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -2224,6 +2224,73 @@ var FFID_ERROR_CODES = {
   TOKEN_VERIFICATION_ERROR: "TOKEN_VERIFICATION_ERROR"
 };
 var EXT_CHECK_ENDPOINT = "/api/v1/subscriptions/ext/check";
+var DEFAULT_ALLOW_GRACE = true;
+var DEFAULT_SERVICE_ACCESS_FAIL_POLICY = "failClosed";
+var SERVICE_ACCESS_DENIED_CODE = "SERVICE_ACCESS_DENIED";
+var ACCESS_GRANTING_EFFECTIVE_STATUSES = ["active", "past_due_grace"];
+var BLOCKING_EFFECTIVE_STATUSES = [
+  "blocked",
+  "canceled",
+  "expired",
+  "trial_expired"
+];
+function resolveServiceAccessDenialReason(params, allowGrace) {
+  if (params.hasAccess) {
+    return null;
+  }
+  if (params.effectiveStatus === null) {
+    return "no_subscription";
+  }
+  if (params.isGrace && !allowGrace) {
+    return "grace_disallowed";
+  }
+  if (params.effectiveStatus === "active" || params.effectiveStatus === "past_due_grace") {
+    return "blocked";
+  }
+  return params.effectiveStatus;
+}
+function toServiceAccessDecision(response, allowGrace) {
+  const effectiveStatus = response.effectiveStatus ?? null;
+  const serverHasAccess = response.hasAccess ?? (effectiveStatus !== null && ACCESS_GRANTING_EFFECTIVE_STATUSES.includes(effectiveStatus));
+  const isGrace = response.isGrace ?? effectiveStatus === "past_due_grace";
+  const hasAccess = serverHasAccess && (allowGrace || !isGrace);
+  const isBlocked = response.isBlocked ?? (effectiveStatus === null || effectiveStatus !== null && BLOCKING_EFFECTIVE_STATUSES.includes(effectiveStatus));
+  return {
+    hasAccess,
+    effectiveStatus,
+    isGrace,
+    isBlocked: isBlocked || !hasAccess,
+    allowGrace,
+    failPolicy: DEFAULT_SERVICE_ACCESS_FAIL_POLICY,
+    denialReason: resolveServiceAccessDenialReason({ effectiveStatus, hasAccess, isGrace }, allowGrace),
+    organizationId: response.organizationId,
+    subscriptionId: response.subscriptionId,
+    status: response.status,
+    planCode: response.planCode,
+    currentPeriodEnd: response.currentPeriodEnd,
+    gracePeriodEndsAt: response.gracePeriodEndsAt ?? null,
+    reactivatable: response.reactivatable ?? false
+  };
+}
+function failClosedServiceAccessDecision(params, error) {
+  return {
+    hasAccess: false,
+    effectiveStatus: null,
+    isGrace: false,
+    isBlocked: true,
+    allowGrace: params.allowGrace ?? DEFAULT_ALLOW_GRACE,
+    failPolicy: DEFAULT_SERVICE_ACCESS_FAIL_POLICY,
+    denialReason: "ffid_unreachable",
+    organizationId: params.organizationId || null,
+    subscriptionId: null,
+    status: null,
+    planCode: null,
+    currentPeriodEnd: null,
+    gracePeriodEndsAt: null,
+    reactivatable: false,
+    error
+  };
+}
 function resolveRedirectUri(raw, logger) {
   if (raw === null) return null;
   try {
@@ -2462,6 +2529,57 @@ function createFFIDClient(config) {
       `${EXT_CHECK_ENDPOINT}?${query.toString()}`
     );
   }
+  async function checkServiceAccess(params) {
+    const failPolicy = params.failPolicy ?? DEFAULT_SERVICE_ACCESS_FAIL_POLICY;
+    if (failPolicy !== DEFAULT_SERVICE_ACCESS_FAIL_POLICY) {
+      return {
+        error: createError(
+          "VALIDATION_ERROR",
+          `failPolicy \u306F ${DEFAULT_SERVICE_ACCESS_FAIL_POLICY} \u306E\u307F\u6307\u5B9A\u3067\u304D\u307E\u3059`
+        )
+      };
+    }
+    const subscriptionParams = {
+      organizationId: params.organizationId
+    };
+    if (params.userId !== void 0) {
+      subscriptionParams.userId = params.userId;
+    }
+    const subscriptionResult = await checkSubscription(subscriptionParams);
+    if (subscriptionResult.error) {
+      if (subscriptionResult.error.code === "VALIDATION_ERROR") {
+        return { error: subscriptionResult.error };
+      }
+      return {
+        data: failClosedServiceAccessDecision(params, subscriptionResult.error)
+      };
+    }
+    return {
+      data: toServiceAccessDecision(
+        subscriptionResult.data,
+        params.allowGrace ?? DEFAULT_ALLOW_GRACE
+      )
+    };
+  }
+  async function requireServiceAccess(params) {
+    const result = await checkServiceAccess(params);
+    if (result.error) {
+      return result;
+    }
+    if (!result.data.hasAccess) {
+      const error = createError(
+        SERVICE_ACCESS_DENIED_CODE,
+        `FFID service access denied: ${result.data.denialReason ?? "unknown"}`
+      );
+      if (result.data.error) {
+        error.details = { cause: result.data.error };
+      }
+      return {
+        error
+      };
+    }
+    return result;
+  }
   const { createCheckoutSession, createPortalSession } = createBillingMethods({
     fetchWithAuth,
     createError
@@ -2560,6 +2678,8 @@ function createFFIDClient(config) {
     exchangeCodeForTokens,
     refreshAccessToken,
     checkSubscription,
+    checkServiceAccess,
+    requireServiceAccess,
     listMembers,
     updateMemberRole,
     removeMember,

package/dist/{chunk-P35ULJLM.js → chunk-WI645CPU.js}

@@ -806,7 +806,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "4.0.0";
+var SDK_VERSION = "4.2.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -2222,6 +2222,73 @@ var FFID_ERROR_CODES = {
   TOKEN_VERIFICATION_ERROR: "TOKEN_VERIFICATION_ERROR"
 };
 var EXT_CHECK_ENDPOINT = "/api/v1/subscriptions/ext/check";
+var DEFAULT_ALLOW_GRACE = true;
+var DEFAULT_SERVICE_ACCESS_FAIL_POLICY = "failClosed";
+var SERVICE_ACCESS_DENIED_CODE = "SERVICE_ACCESS_DENIED";
+var ACCESS_GRANTING_EFFECTIVE_STATUSES = ["active", "past_due_grace"];
+var BLOCKING_EFFECTIVE_STATUSES = [
+  "blocked",
+  "canceled",
+  "expired",
+  "trial_expired"
+];
+function resolveServiceAccessDenialReason(params, allowGrace) {
+  if (params.hasAccess) {
+    return null;
+  }
+  if (params.effectiveStatus === null) {
+    return "no_subscription";
+  }
+  if (params.isGrace && !allowGrace) {
+    return "grace_disallowed";
+  }
+  if (params.effectiveStatus === "active" || params.effectiveStatus === "past_due_grace") {
+    return "blocked";
+  }
+  return params.effectiveStatus;
+}
+function toServiceAccessDecision(response, allowGrace) {
+  const effectiveStatus = response.effectiveStatus ?? null;
+  const serverHasAccess = response.hasAccess ?? (effectiveStatus !== null && ACCESS_GRANTING_EFFECTIVE_STATUSES.includes(effectiveStatus));
+  const isGrace = response.isGrace ?? effectiveStatus === "past_due_grace";
+  const hasAccess = serverHasAccess && (allowGrace || !isGrace);
+  const isBlocked = response.isBlocked ?? (effectiveStatus === null || effectiveStatus !== null && BLOCKING_EFFECTIVE_STATUSES.includes(effectiveStatus));
+  return {
+    hasAccess,
+    effectiveStatus,
+    isGrace,
+    isBlocked: isBlocked || !hasAccess,
+    allowGrace,
+    failPolicy: DEFAULT_SERVICE_ACCESS_FAIL_POLICY,
+    denialReason: resolveServiceAccessDenialReason({ effectiveStatus, hasAccess, isGrace }, allowGrace),
+    organizationId: response.organizationId,
+    subscriptionId: response.subscriptionId,
+    status: response.status,
+    planCode: response.planCode,
+    currentPeriodEnd: response.currentPeriodEnd,
+    gracePeriodEndsAt: response.gracePeriodEndsAt ?? null,
+    reactivatable: response.reactivatable ?? false
+  };
+}
+function failClosedServiceAccessDecision(params, error) {
+  return {
+    hasAccess: false,
+    effectiveStatus: null,
+    isGrace: false,
+    isBlocked: true,
+    allowGrace: params.allowGrace ?? DEFAULT_ALLOW_GRACE,
+    failPolicy: DEFAULT_SERVICE_ACCESS_FAIL_POLICY,
+    denialReason: "ffid_unreachable",
+    organizationId: params.organizationId || null,
+    subscriptionId: null,
+    status: null,
+    planCode: null,
+    currentPeriodEnd: null,
+    gracePeriodEndsAt: null,
+    reactivatable: false,
+    error
+  };
+}
 function resolveRedirectUri(raw, logger) {
   if (raw === null) return null;
   try {
@@ -2460,6 +2527,57 @@ function createFFIDClient(config) {
       `${EXT_CHECK_ENDPOINT}?${query.toString()}`
     );
   }
+  async function checkServiceAccess(params) {
+    const failPolicy = params.failPolicy ?? DEFAULT_SERVICE_ACCESS_FAIL_POLICY;
+    if (failPolicy !== DEFAULT_SERVICE_ACCESS_FAIL_POLICY) {
+      return {
+        error: createError(
+          "VALIDATION_ERROR",
+          `failPolicy \u306F ${DEFAULT_SERVICE_ACCESS_FAIL_POLICY} \u306E\u307F\u6307\u5B9A\u3067\u304D\u307E\u3059`
+        )
+      };
+    }
+    const subscriptionParams = {
+      organizationId: params.organizationId
+    };
+    if (params.userId !== void 0) {
+      subscriptionParams.userId = params.userId;
+    }
+    const subscriptionResult = await checkSubscription(subscriptionParams);
+    if (subscriptionResult.error) {
+      if (subscriptionResult.error.code === "VALIDATION_ERROR") {
+        return { error: subscriptionResult.error };
+      }
+      return {
+        data: failClosedServiceAccessDecision(params, subscriptionResult.error)
+      };
+    }
+    return {
+      data: toServiceAccessDecision(
+        subscriptionResult.data,
+        params.allowGrace ?? DEFAULT_ALLOW_GRACE
+      )
+    };
+  }
+  async function requireServiceAccess(params) {
+    const result = await checkServiceAccess(params);
+    if (result.error) {
+      return result;
+    }
+    if (!result.data.hasAccess) {
+      const error = createError(
+        SERVICE_ACCESS_DENIED_CODE,
+        `FFID service access denied: ${result.data.denialReason ?? "unknown"}`
+      );
+      if (result.data.error) {
+        error.details = { cause: result.data.error };
+      }
+      return {
+        error
+      };
+    }
+    return result;
+  }
   const { createCheckoutSession, createPortalSession } = createBillingMethods({
     fetchWithAuth,
     createError
@@ -2558,6 +2676,8 @@ function createFFIDClient(config) {
     exchangeCodeForTokens,
     refreshAccessToken,
     checkSubscription,
+    checkServiceAccess,
+    requireServiceAccess,
     listMembers,
     updateMemberRole,
     removeMember,

package/dist/components/index.cjs

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

package/dist/components/index.d.cts

@@ -1,3 +1,3 @@
-export { N as FFIDAnnouncementBadge, an as FFIDAnnouncementBadgeClassNames, ao as FFIDAnnouncementBadgeProps, O as FFIDAnnouncementList, ap as FFIDAnnouncementListClassNames, aq as FFIDAnnouncementListProps, W as FFIDInquiryForm, X as FFIDInquiryFormCategoryItem, Y as FFIDInquiryFormClassNames, Z as FFIDInquiryFormLegalLayout, _ as FFIDInquiryFormOrganization, $ as FFIDInquiryFormPlaceholderContext, a0 as FFIDInquiryFormPrefill, a1 as FFIDInquiryFormProps, a2 as FFIDInquiryFormSubmitData, a3 as FFIDInquiryFormSubmitResult, a5 as FFIDLoginButton, ar as FFIDLoginButtonProps, ab as FFIDOrganizationSwitcher, as as FFIDOrganizationSwitcherClassNames, at as FFIDOrganizationSwitcherProps, ae as FFIDSubscriptionBadge, au as FFIDSubscriptionBadgeClassNames, av as FFIDSubscriptionBadgeProps, ag as FFIDUserMenu, aw as FFIDUserMenuClassNames, ax as FFIDUserMenuProps } from '../index-Cn8-3hgb.cjs';
+export { P as FFIDAnnouncementBadge, ar as FFIDAnnouncementBadgeClassNames, as as FFIDAnnouncementBadgeProps, Q as FFIDAnnouncementList, at as FFIDAnnouncementListClassNames, au as FFIDAnnouncementListProps, Y as FFIDInquiryForm, Z as FFIDInquiryFormCategoryItem, _ as FFIDInquiryFormClassNames, $ as FFIDInquiryFormLegalLayout, a0 as FFIDInquiryFormOrganization, a1 as FFIDInquiryFormPlaceholderContext, a2 as FFIDInquiryFormPrefill, a3 as FFIDInquiryFormProps, a4 as FFIDInquiryFormSubmitData, a5 as FFIDInquiryFormSubmitResult, a7 as FFIDLoginButton, av as FFIDLoginButtonProps, ad as FFIDOrganizationSwitcher, aw as FFIDOrganizationSwitcherClassNames, ax as FFIDOrganizationSwitcherProps, ai as FFIDSubscriptionBadge, ay as FFIDSubscriptionBadgeClassNames, az as FFIDSubscriptionBadgeProps, ak as FFIDUserMenu, aA as FFIDUserMenuClassNames, aB as FFIDUserMenuProps } from '../index-DXgTH5vK.cjs';
 import 'react/jsx-runtime';
 import 'react';

package/dist/components/index.d.ts

@@ -1,3 +1,3 @@
-export { N as FFIDAnnouncementBadge, an as FFIDAnnouncementBadgeClassNames, ao as FFIDAnnouncementBadgeProps, O as FFIDAnnouncementList, ap as FFIDAnnouncementListClassNames, aq as FFIDAnnouncementListProps, W as FFIDInquiryForm, X as FFIDInquiryFormCategoryItem, Y as FFIDInquiryFormClassNames, Z as FFIDInquiryFormLegalLayout, _ as FFIDInquiryFormOrganization, $ as FFIDInquiryFormPlaceholderContext, a0 as FFIDInquiryFormPrefill, a1 as FFIDInquiryFormProps, a2 as FFIDInquiryFormSubmitData, a3 as FFIDInquiryFormSubmitResult, a5 as FFIDLoginButton, ar as FFIDLoginButtonProps, ab as FFIDOrganizationSwitcher, as as FFIDOrganizationSwitcherClassNames, at as FFIDOrganizationSwitcherProps, ae as FFIDSubscriptionBadge, au as FFIDSubscriptionBadgeClassNames, av as FFIDSubscriptionBadgeProps, ag as FFIDUserMenu, aw as FFIDUserMenuClassNames, ax as FFIDUserMenuProps } from '../index-Cn8-3hgb.js';
+export { P as FFIDAnnouncementBadge, ar as FFIDAnnouncementBadgeClassNames, as as FFIDAnnouncementBadgeProps, Q as FFIDAnnouncementList, at as FFIDAnnouncementListClassNames, au as FFIDAnnouncementListProps, Y as FFIDInquiryForm, Z as FFIDInquiryFormCategoryItem, _ as FFIDInquiryFormClassNames, $ as FFIDInquiryFormLegalLayout, a0 as FFIDInquiryFormOrganization, a1 as FFIDInquiryFormPlaceholderContext, a2 as FFIDInquiryFormPrefill, a3 as FFIDInquiryFormProps, a4 as FFIDInquiryFormSubmitData, a5 as FFIDInquiryFormSubmitResult, a7 as FFIDLoginButton, av as FFIDLoginButtonProps, ad as FFIDOrganizationSwitcher, aw as FFIDOrganizationSwitcherClassNames, ax as FFIDOrganizationSwitcherProps, ai as FFIDSubscriptionBadge, ay as FFIDSubscriptionBadgeClassNames, az as FFIDSubscriptionBadgeProps, ak as FFIDUserMenu, aA as FFIDUserMenuClassNames, aB as FFIDUserMenuProps } from '../index-DXgTH5vK.js';
 import 'react/jsx-runtime';
 import 'react';

package/dist/components/index.js

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

package/dist/{ffid-client-ZcJhRbD6.d.ts → ffid-client-CKMGqqPi.d.cts}

@@ -1,3 +1,5 @@
+import { E as EffectiveSubscriptionStatus } from './types-5g_Bg6Ey.cjs';
+
 /**
  * Inquiry types exposed by the FFID SDK.
  *
@@ -183,6 +185,91 @@ interface FFIDCacheConfig {
     ttl: number;
 }
 
+/**
+ * Canonical service-access types for subscription lifecycle decisions.
+ */
+
+/** Subscription status values matching the FFID platform's SubscriptionStatus type */
+type FFIDSubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'pending_invoice' | 'paused' | 'incomplete' | 'incomplete_expired' | 'unpaid';
+interface FFIDSubscriptionCheckResponse {
+    hasActiveSubscription: boolean;
+    /**
+     * Canonical access decision returned by FFID's `/subscriptions/ext/check`.
+     *
+     * This is the server-side source of truth for service gates. Consumers
+     * should not recompute access from `currentPeriodEnd`, `past_due_since`, or
+     * local payment timestamps.
+     */
+    hasAccess?: boolean;
+    /** True when `effectiveStatus === 'past_due_grace'`. */
+    isGrace?: boolean;
+    /** True when FFID's canonical effective status denies service access. */
+    isBlocked?: boolean;
+    organizationId: string | null;
+    subscriptionId: string | null;
+    status: FFIDSubscriptionStatus | null;
+    planCode: string | null;
+    currentPeriodEnd: string | null;
+    /**
+     * Semantic FFID access-control status. `null` means the organization has no
+     * subscription row for this service.
+     */
+    effectiveStatus?: EffectiveSubscriptionStatus | null;
+    /**
+     * ISO timestamp at which `past_due_grace` flips to `blocked`; null outside
+     * the grace window.
+     */
+    gracePeriodEndsAt?: string | null;
+    /** Whether a canceled subscription can be resumed via a re-subscription flow. */
+    reactivatable?: boolean;
+}
+type FFIDServiceAccessFailPolicy = 'failClosed';
+type FFIDServiceAccessDenialReason = 'no_subscription' | 'grace_disallowed' | 'blocked' | 'canceled' | 'expired' | 'trial_expired' | 'ffid_unreachable';
+interface FFIDCheckServiceAccessParams {
+    userId?: string;
+    organizationId: string;
+    /**
+     * Whether `past_due_grace` should keep access open.
+     *
+     * @default true
+     */
+    allowGrace?: boolean;
+    /**
+     * Error policy when FFID cannot return a canonical decision.
+     *
+     * Currently only `failClosed` is supported: network/server/parse failures
+     * become `hasAccess=false` decisions with `denialReason='ffid_unreachable'`
+     * and the root cause in `decision.error`. Treat `hasAccess` as the gate.
+     */
+    failPolicy?: FFIDServiceAccessFailPolicy;
+}
+interface FFIDServiceAccessError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+interface FFIDServiceAccessDecision {
+    hasAccess: boolean;
+    effectiveStatus: EffectiveSubscriptionStatus | null;
+    isGrace: boolean;
+    isBlocked: boolean;
+    allowGrace: boolean;
+    failPolicy: FFIDServiceAccessFailPolicy;
+    denialReason: FFIDServiceAccessDenialReason | null;
+    organizationId: string | null;
+    subscriptionId: string | null;
+    status: FFIDSubscriptionStatus | null;
+    planCode: string | null;
+    currentPeriodEnd: string | null;
+    gracePeriodEndsAt: string | null;
+    reactivatable: boolean;
+    /**
+     * Present when the decision was produced by the SDK fail-closed policy
+     * rather than by a successful FFID response.
+     */
+    error?: FFIDServiceAccessError;
+}
+
 /** Billing interval for subscriptions */
 type FFIDBillingInterval = 'monthly' | 'yearly';
 /**
@@ -736,16 +823,7 @@ type FFIDApiResponse<T> = {
     data?: undefined;
     error: FFIDError;
 };
-/** Subscription status values matching the FFID platform's SubscriptionStatus type */
-type FFIDSubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'pending_invoice' | 'paused' | 'incomplete' | 'incomplete_expired' | 'unpaid';
-interface FFIDSubscriptionCheckResponse {
-    hasActiveSubscription: boolean;
-    organizationId: string | null;
-    subscriptionId: string | null;
-    status: FFIDSubscriptionStatus | null;
-    planCode: string | null;
-    currentPeriodEnd: string | null;
-}
+
 /**
  * Checkout session response from billing checkout endpoint
  */
@@ -1140,6 +1218,8 @@ declare function createFFIDClient(config: FFIDConfig): {
         userId?: string;
         organizationId: string;
     }) => Promise<FFIDApiResponse<FFIDSubscriptionCheckResponse>>;
+    checkServiceAccess: (params: FFIDCheckServiceAccessParams) => Promise<FFIDApiResponse<FFIDServiceAccessDecision>>;
+    requireServiceAccess: (params: FFIDCheckServiceAccessParams) => Promise<FFIDApiResponse<FFIDServiceAccessDecision>>;
     listMembers: (params: {
         organizationId: string;
     }) => Promise<FFIDApiResponse<FFIDListMembersResponse>>;

package/dist/{ffid-client-ZcJhRbD6.d.cts → ffid-client-CUOFknXy.d.ts}

@@ -1,3 +1,5 @@
+import { E as EffectiveSubscriptionStatus } from './types-5g_Bg6Ey.js';
+
 /**
  * Inquiry types exposed by the FFID SDK.
  *
@@ -183,6 +185,91 @@ interface FFIDCacheConfig {
     ttl: number;
 }
 
+/**
+ * Canonical service-access types for subscription lifecycle decisions.
+ */
+
+/** Subscription status values matching the FFID platform's SubscriptionStatus type */
+type FFIDSubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'pending_invoice' | 'paused' | 'incomplete' | 'incomplete_expired' | 'unpaid';
+interface FFIDSubscriptionCheckResponse {
+    hasActiveSubscription: boolean;
+    /**
+     * Canonical access decision returned by FFID's `/subscriptions/ext/check`.
+     *
+     * This is the server-side source of truth for service gates. Consumers
+     * should not recompute access from `currentPeriodEnd`, `past_due_since`, or
+     * local payment timestamps.
+     */
+    hasAccess?: boolean;
+    /** True when `effectiveStatus === 'past_due_grace'`. */
+    isGrace?: boolean;
+    /** True when FFID's canonical effective status denies service access. */
+    isBlocked?: boolean;
+    organizationId: string | null;
+    subscriptionId: string | null;
+    status: FFIDSubscriptionStatus | null;
+    planCode: string | null;
+    currentPeriodEnd: string | null;
+    /**
+     * Semantic FFID access-control status. `null` means the organization has no
+     * subscription row for this service.
+     */
+    effectiveStatus?: EffectiveSubscriptionStatus | null;
+    /**
+     * ISO timestamp at which `past_due_grace` flips to `blocked`; null outside
+     * the grace window.
+     */
+    gracePeriodEndsAt?: string | null;
+    /** Whether a canceled subscription can be resumed via a re-subscription flow. */
+    reactivatable?: boolean;
+}
+type FFIDServiceAccessFailPolicy = 'failClosed';
+type FFIDServiceAccessDenialReason = 'no_subscription' | 'grace_disallowed' | 'blocked' | 'canceled' | 'expired' | 'trial_expired' | 'ffid_unreachable';
+interface FFIDCheckServiceAccessParams {
+    userId?: string;
+    organizationId: string;
+    /**
+     * Whether `past_due_grace` should keep access open.
+     *
+     * @default true
+     */
+    allowGrace?: boolean;
+    /**
+     * Error policy when FFID cannot return a canonical decision.
+     *
+     * Currently only `failClosed` is supported: network/server/parse failures
+     * become `hasAccess=false` decisions with `denialReason='ffid_unreachable'`
+     * and the root cause in `decision.error`. Treat `hasAccess` as the gate.
+     */
+    failPolicy?: FFIDServiceAccessFailPolicy;
+}
+interface FFIDServiceAccessError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+interface FFIDServiceAccessDecision {
+    hasAccess: boolean;
+    effectiveStatus: EffectiveSubscriptionStatus | null;
+    isGrace: boolean;
+    isBlocked: boolean;
+    allowGrace: boolean;
+    failPolicy: FFIDServiceAccessFailPolicy;
+    denialReason: FFIDServiceAccessDenialReason | null;
+    organizationId: string | null;
+    subscriptionId: string | null;
+    status: FFIDSubscriptionStatus | null;
+    planCode: string | null;
+    currentPeriodEnd: string | null;
+    gracePeriodEndsAt: string | null;
+    reactivatable: boolean;
+    /**
+     * Present when the decision was produced by the SDK fail-closed policy
+     * rather than by a successful FFID response.
+     */
+    error?: FFIDServiceAccessError;
+}
+
 /** Billing interval for subscriptions */
 type FFIDBillingInterval = 'monthly' | 'yearly';
 /**
@@ -736,16 +823,7 @@ type FFIDApiResponse<T> = {
     data?: undefined;
     error: FFIDError;
 };
-/** Subscription status values matching the FFID platform's SubscriptionStatus type */
-type FFIDSubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'pending_invoice' | 'paused' | 'incomplete' | 'incomplete_expired' | 'unpaid';
-interface FFIDSubscriptionCheckResponse {
-    hasActiveSubscription: boolean;
-    organizationId: string | null;
-    subscriptionId: string | null;
-    status: FFIDSubscriptionStatus | null;
-    planCode: string | null;
-    currentPeriodEnd: string | null;
-}
+
 /**
  * Checkout session response from billing checkout endpoint
  */
@@ -1140,6 +1218,8 @@ declare function createFFIDClient(config: FFIDConfig): {
         userId?: string;
         organizationId: string;
     }) => Promise<FFIDApiResponse<FFIDSubscriptionCheckResponse>>;
+    checkServiceAccess: (params: FFIDCheckServiceAccessParams) => Promise<FFIDApiResponse<FFIDServiceAccessDecision>>;
+    requireServiceAccess: (params: FFIDCheckServiceAccessParams) => Promise<FFIDApiResponse<FFIDServiceAccessDecision>>;
     listMembers: (params: {
         organizationId: string;
     }) => Promise<FFIDApiResponse<FFIDListMembersResponse>>;