@feelflow/ffid-sdk 4.0.0 → 4.2.0

package/dist/server/index.cjs

@@ -803,7 +803,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() {
@@ -2180,6 +2180,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 {
@@ -2418,6 +2485,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
@@ -2516,6 +2634,8 @@ function createFFIDClient(config) {
     exchangeCodeForTokens,
     refreshAccessToken,
     checkSubscription,
+    checkServiceAccess,
+    requireServiceAccess,
     listMembers,
     updateMemberRole,
     removeMember,

package/dist/server/index.d.cts

@@ -1,6 +1,7 @@
-import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo } from '../ffid-client-ZcJhRbD6.cjs';
-export { f as FFIDCacheConfig, g as FFIDClient, h as FFIDConfig, i as FFIDOrganization, j as FFIDOtpSendResponse, k as FFIDOtpVerifyResponse, l as FFIDPasswordResetConfirmResponse, m as FFIDPasswordResetResponse, n as FFIDPasswordResetVerifyResponse, o as FFIDProfileCallOptions, p as FFIDResetSessionResponse, q as FFIDSubscription, r as FFIDUpdateUserProfileRequest, s as FFIDUser, t as FFIDUserProfile, T as TokenData, u as TokenStore, v as createFFIDClient, w as createTokenStore } from '../ffid-client-ZcJhRbD6.cjs';
+import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo } from '../ffid-client-CKMGqqPi.cjs';
+export { f as FFIDCacheConfig, g as FFIDClient, h as FFIDConfig, i as FFIDOrganization, j as FFIDOtpSendResponse, k as FFIDOtpVerifyResponse, l as FFIDPasswordResetConfirmResponse, m as FFIDPasswordResetResponse, n as FFIDPasswordResetVerifyResponse, o as FFIDProfileCallOptions, p as FFIDResetSessionResponse, q as FFIDSubscription, r as FFIDUpdateUserProfileRequest, s as FFIDUser, t as FFIDUserProfile, T as TokenData, u as TokenStore, v as createFFIDClient, w as createTokenStore } from '../ffid-client-CKMGqqPi.cjs';
 export { D as DEFAULT_API_BASE_URL, a as DEFAULT_OAUTH_SCOPES } from '../constants-D61jqRIO.cjs';
+import '../types-5g_Bg6Ey.cjs';
 
 /** Token verification - verifyAccessToken() implementation */
 

package/dist/server/index.d.ts

@@ -1,6 +1,7 @@
-import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo } from '../ffid-client-ZcJhRbD6.js';
-export { f as FFIDCacheConfig, g as FFIDClient, h as FFIDConfig, i as FFIDOrganization, j as FFIDOtpSendResponse, k as FFIDOtpVerifyResponse, l as FFIDPasswordResetConfirmResponse, m as FFIDPasswordResetResponse, n as FFIDPasswordResetVerifyResponse, o as FFIDProfileCallOptions, p as FFIDResetSessionResponse, q as FFIDSubscription, r as FFIDUpdateUserProfileRequest, s as FFIDUser, t as FFIDUserProfile, T as TokenData, u as TokenStore, v as createFFIDClient, w as createTokenStore } from '../ffid-client-ZcJhRbD6.js';
+import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo } from '../ffid-client-CUOFknXy.js';
+export { f as FFIDCacheConfig, g as FFIDClient, h as FFIDConfig, i as FFIDOrganization, j as FFIDOtpSendResponse, k as FFIDOtpVerifyResponse, l as FFIDPasswordResetConfirmResponse, m as FFIDPasswordResetResponse, n as FFIDPasswordResetVerifyResponse, o as FFIDProfileCallOptions, p as FFIDResetSessionResponse, q as FFIDSubscription, r as FFIDUpdateUserProfileRequest, s as FFIDUser, t as FFIDUserProfile, T as TokenData, u as TokenStore, v as createFFIDClient, w as createTokenStore } from '../ffid-client-CUOFknXy.js';
 export { D as DEFAULT_API_BASE_URL, a as DEFAULT_OAUTH_SCOPES } from '../constants-D61jqRIO.js';
+import '../types-5g_Bg6Ey.js';
 
 /** Token verification - verifyAccessToken() implementation */
 

package/dist/server/index.js

@@ -802,7 +802,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() {
@@ -2179,6 +2179,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 {
@@ -2417,6 +2484,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
@@ -2515,6 +2633,8 @@ function createFFIDClient(config) {
     exchangeCodeForTokens,
     refreshAccessToken,
     checkSubscription,
+    checkServiceAccess,
+    requireServiceAccess,
     listMembers,
     updateMemberRole,
     removeMember,

package/dist/server/test/index.d.cts

@@ -1,4 +1,5 @@
-import { g as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-ZcJhRbD6.cjs';
+import { g as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-CKMGqqPi.cjs';
+import '../../types-5g_Bg6Ey.cjs';
 
 /**
  * FFID SDK - Test mode client (E2E / integration test bypass)

package/dist/server/test/index.d.ts

@@ -1,4 +1,5 @@
-import { g as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-ZcJhRbD6.js';
+import { g as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-CUOFknXy.js';
+import '../../types-5g_Bg6Ey.js';
 
 /**
  * FFID SDK - Test mode client (E2E / integration test bypass)

package/dist/types-5g_Bg6Ey.d.cts

@@ -0,0 +1,37 @@
+/**
+ * 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';
+
+export type { EffectiveSubscriptionStatus as E };

package/dist/types-5g_Bg6Ey.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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';
+
+export type { EffectiveSubscriptionStatus as E };

package/dist/webhooks/index.d.cts

@@ -1,3 +1,5 @@
+import { E as EffectiveSubscriptionStatus } from '../types-5g_Bg6Ey.cjs';
+
 /**
  * FFID Webhook SDK Constants
  *
@@ -43,13 +45,16 @@ declare class FFIDWebhookPayloadError extends FFIDWebhookError {
  * Types for receiving and verifying FeelFlow ID webhook events.
  * Used by external services to handle real-time event notifications.
  */
+
 /** All supported webhook event types */
-type FFIDWebhookEventType = 'subscription.created' | 'subscription.updated' | 'subscription.canceled' | 'subscription.trial_ending' | 'subscription.payment_failed' | 'user.created' | 'user.updated' | 'user.deleted' | 'user.deletion_requested' | 'organization.created' | 'organization.updated' | 'organization.member.added' | 'organization.member.removed' | 'organization.member.role_changed' | 'legal.document.updated' | 'legal.agreement.required' | 'system.maintenance.scheduled' | 'system.maintenance.started' | 'system.maintenance.completed' | 'announcement.published' | 'test.ping';
+type FFIDWebhookEventType = 'subscription.created' | 'subscription.updated' | 'subscription.canceled' | 'subscription.downgrade_scheduled' | 'subscription.downgrade_applied' | 'subscription.downgrade_canceled' | 'subscription.trial_ending' | 'subscription.payment_failed' | 'user.created' | 'user.updated' | 'user.deleted' | 'user.deletion_requested' | 'organization.created' | 'organization.updated' | 'organization.member.added' | 'organization.member.removed' | 'organization.member.role_changed' | 'legal.document.updated' | 'legal.agreement.required' | 'system.maintenance.scheduled' | 'system.maintenance.started' | 'system.maintenance.completed' | 'announcement.published' | 'test.ping';
 interface FFIDSubscriptionCreatedPayload {
     subscriptionId: string;
     organizationId?: string;
     plan?: string;
     status?: string;
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    gracePeriodEndsAt?: string | null;
 }
 interface FFIDSubscriptionUpdatedPayload {
     subscriptionId: string;
@@ -57,6 +62,8 @@ interface FFIDSubscriptionUpdatedPayload {
     plan?: string;
     previousPlan?: string;
     status?: string;
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    gracePeriodEndsAt?: string | null;
 }
 interface FFIDSubscriptionCanceledPayload {
     /** FFID subscription UUID. */
@@ -86,6 +93,52 @@ interface FFIDSubscriptionCanceledPayload {
      * when Stripe runs out the paid period before emitting the deletion event.
      */
     expiredAt?: string;
+    /** Cancellation always leaves the canonical access-control status as `canceled`. */
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    /** Always null for cancellation events because no grace window remains. */
+    gracePeriodEndsAt?: string | null;
+}
+interface FFIDSubscriptionDowngradeScheduledPayload {
+    /** FFID subscription UUID. */
+    subscriptionId: string;
+    /** Organization UUID that owns the subscription. */
+    organizationId: string;
+    /** Plan UUID currently active on the subscription. */
+    currentPlanId: string;
+    /** Plan UUID scheduled to become active at period end. */
+    newPlanId: string;
+    /** Billing interval carried by the target period, typically 'monthly' or 'yearly'. */
+    billingInterval: string;
+    /** ISO timestamp when the downgrade was scheduled. */
+    scheduledAt: string;
+    /** ISO timestamp when the scheduled downgrade should take effect. */
+    effectiveAt: string;
+}
+interface FFIDSubscriptionDowngradeAppliedPayload {
+    /** FFID subscription UUID. */
+    subscriptionId: string;
+    /** Organization UUID that owns the subscription. */
+    organizationId: string;
+    /** Plan UUID active before the pending downgrade was applied. */
+    previousPlanId: string;
+    /** Plan UUID that became active after the downgrade was applied. */
+    newPlanId: string;
+    /** Billing interval on the applied downgraded plan, typically 'monthly' or 'yearly'. */
+    billingInterval: string;
+    /** ISO timestamp when FFID applied the pending downgrade. */
+    appliedAt: string;
+}
+interface FFIDSubscriptionDowngradeCanceledPayload {
+    /** FFID subscription UUID. */
+    subscriptionId: string;
+    /** Organization UUID that owns the subscription. */
+    organizationId: string;
+    /** Plan UUID that had been pending but was canceled before taking effect. */
+    canceledPlanId: string;
+    /** Plan UUID that remains active after canceling the pending downgrade. */
+    currentPlanId: string;
+    /** ISO timestamp when the pending downgrade was canceled. */
+    canceledAt: string;
 }
 interface FFIDSubscriptionTrialEndingPayload {
     subscriptionId: string;
@@ -130,6 +183,13 @@ interface FFIDSubscriptionPaymentFailedPayload {
      * `null` means already blocking.
      */
     graceUntil?: string | null;
+    /** Canonical FFID access-control status derived from payment-failure severity. */
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    /**
+     * Alias of `graceUntil` for canonical access payloads; services should prefer
+     * this field when sharing code with `/subscriptions/ext/check`.
+     */
+    gracePeriodEndsAt?: 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
@@ -221,6 +281,9 @@ interface FFIDWebhookEventMap {
     'subscription.created': FFIDSubscriptionCreatedPayload;
     'subscription.updated': FFIDSubscriptionUpdatedPayload;
     'subscription.canceled': FFIDSubscriptionCanceledPayload;
+    'subscription.downgrade_scheduled': FFIDSubscriptionDowngradeScheduledPayload;
+    'subscription.downgrade_applied': FFIDSubscriptionDowngradeAppliedPayload;
+    'subscription.downgrade_canceled': FFIDSubscriptionDowngradeCanceledPayload;
     'subscription.trial_ending': FFIDSubscriptionTrialEndingPayload;
     'subscription.payment_failed': FFIDSubscriptionPaymentFailedPayload;
     'user.created': FFIDUserCreatedPayload;
@@ -363,4 +426,4 @@ declare function createFFIDWebhookHandler(config: FFIDWebhookHandlerConfig): {
 /** Type of the FFID Webhook handler */
 type FFIDWebhookHandler = ReturnType<typeof createFFIDWebhookHandler>;
 
-export { DEFAULT_TOLERANCE_SECONDS, type FFIDLegalAgreementRequiredPayload, type FFIDLegalDocumentUpdatedPayload, type FFIDOrganizationCreatedPayload, type FFIDOrganizationMemberAddedPayload, type FFIDOrganizationMemberRemovedPayload, type FFIDOrganizationMemberRoleChangedPayload, type FFIDOrganizationUpdatedPayload, type FFIDSubscriptionCanceledPayload, type FFIDSubscriptionCreatedPayload, type FFIDSubscriptionPaymentFailedPayload, type FFIDSubscriptionTrialEndingPayload, type FFIDSubscriptionUpdatedPayload, type FFIDSystemMaintenancePayload, type FFIDTestPingPayload, type FFIDUserCreatedPayload, type FFIDUserDeletedPayload, type FFIDUserDeletionRequestedPayload, type FFIDUserUpdatedPayload, FFIDWebhookError, type FFIDWebhookEvent, type FFIDWebhookEventHandler, type FFIDWebhookEventMap, type FFIDWebhookEventType, type FFIDWebhookHandler, type FFIDWebhookHandlerConfig, type FFIDWebhookLogger, FFIDWebhookPayloadError, FFIDWebhookSignatureError, FFIDWebhookTimestampError, FFID_WEBHOOK_EVENT_ID_HEADER, FFID_WEBHOOK_SIGNATURE_HEADER, FFID_WEBHOOK_SIGNATURE_VERSION, FFID_WEBHOOK_TIMESTAMP_HEADER, computeSignature, createFFIDWebhookHandler, parseSignatureHeader, verifyWebhookSignature };
+export { DEFAULT_TOLERANCE_SECONDS, type FFIDLegalAgreementRequiredPayload, type FFIDLegalDocumentUpdatedPayload, type FFIDOrganizationCreatedPayload, type FFIDOrganizationMemberAddedPayload, type FFIDOrganizationMemberRemovedPayload, type FFIDOrganizationMemberRoleChangedPayload, type FFIDOrganizationUpdatedPayload, type FFIDSubscriptionCanceledPayload, type FFIDSubscriptionCreatedPayload, type FFIDSubscriptionDowngradeAppliedPayload, type FFIDSubscriptionDowngradeCanceledPayload, type FFIDSubscriptionDowngradeScheduledPayload, type FFIDSubscriptionPaymentFailedPayload, type FFIDSubscriptionTrialEndingPayload, type FFIDSubscriptionUpdatedPayload, type FFIDSystemMaintenancePayload, type FFIDTestPingPayload, type FFIDUserCreatedPayload, type FFIDUserDeletedPayload, type FFIDUserDeletionRequestedPayload, type FFIDUserUpdatedPayload, FFIDWebhookError, type FFIDWebhookEvent, type FFIDWebhookEventHandler, type FFIDWebhookEventMap, type FFIDWebhookEventType, type FFIDWebhookHandler, type FFIDWebhookHandlerConfig, type FFIDWebhookLogger, FFIDWebhookPayloadError, FFIDWebhookSignatureError, FFIDWebhookTimestampError, FFID_WEBHOOK_EVENT_ID_HEADER, FFID_WEBHOOK_SIGNATURE_HEADER, FFID_WEBHOOK_SIGNATURE_VERSION, FFID_WEBHOOK_TIMESTAMP_HEADER, computeSignature, createFFIDWebhookHandler, parseSignatureHeader, verifyWebhookSignature };

package/dist/webhooks/index.d.ts

@@ -1,3 +1,5 @@
+import { E as EffectiveSubscriptionStatus } from '../types-5g_Bg6Ey.js';
+
 /**
  * FFID Webhook SDK Constants
  *
@@ -43,13 +45,16 @@ declare class FFIDWebhookPayloadError extends FFIDWebhookError {
  * Types for receiving and verifying FeelFlow ID webhook events.
  * Used by external services to handle real-time event notifications.
  */
+
 /** All supported webhook event types */
-type FFIDWebhookEventType = 'subscription.created' | 'subscription.updated' | 'subscription.canceled' | 'subscription.trial_ending' | 'subscription.payment_failed' | 'user.created' | 'user.updated' | 'user.deleted' | 'user.deletion_requested' | 'organization.created' | 'organization.updated' | 'organization.member.added' | 'organization.member.removed' | 'organization.member.role_changed' | 'legal.document.updated' | 'legal.agreement.required' | 'system.maintenance.scheduled' | 'system.maintenance.started' | 'system.maintenance.completed' | 'announcement.published' | 'test.ping';
+type FFIDWebhookEventType = 'subscription.created' | 'subscription.updated' | 'subscription.canceled' | 'subscription.downgrade_scheduled' | 'subscription.downgrade_applied' | 'subscription.downgrade_canceled' | 'subscription.trial_ending' | 'subscription.payment_failed' | 'user.created' | 'user.updated' | 'user.deleted' | 'user.deletion_requested' | 'organization.created' | 'organization.updated' | 'organization.member.added' | 'organization.member.removed' | 'organization.member.role_changed' | 'legal.document.updated' | 'legal.agreement.required' | 'system.maintenance.scheduled' | 'system.maintenance.started' | 'system.maintenance.completed' | 'announcement.published' | 'test.ping';
 interface FFIDSubscriptionCreatedPayload {
     subscriptionId: string;
     organizationId?: string;
     plan?: string;
     status?: string;
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    gracePeriodEndsAt?: string | null;
 }
 interface FFIDSubscriptionUpdatedPayload {
     subscriptionId: string;
@@ -57,6 +62,8 @@ interface FFIDSubscriptionUpdatedPayload {
     plan?: string;
     previousPlan?: string;
     status?: string;
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    gracePeriodEndsAt?: string | null;
 }
 interface FFIDSubscriptionCanceledPayload {
     /** FFID subscription UUID. */
@@ -86,6 +93,52 @@ interface FFIDSubscriptionCanceledPayload {
      * when Stripe runs out the paid period before emitting the deletion event.
      */
     expiredAt?: string;
+    /** Cancellation always leaves the canonical access-control status as `canceled`. */
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    /** Always null for cancellation events because no grace window remains. */
+    gracePeriodEndsAt?: string | null;
+}
+interface FFIDSubscriptionDowngradeScheduledPayload {
+    /** FFID subscription UUID. */
+    subscriptionId: string;
+    /** Organization UUID that owns the subscription. */
+    organizationId: string;
+    /** Plan UUID currently active on the subscription. */
+    currentPlanId: string;
+    /** Plan UUID scheduled to become active at period end. */
+    newPlanId: string;
+    /** Billing interval carried by the target period, typically 'monthly' or 'yearly'. */
+    billingInterval: string;
+    /** ISO timestamp when the downgrade was scheduled. */
+    scheduledAt: string;
+    /** ISO timestamp when the scheduled downgrade should take effect. */
+    effectiveAt: string;
+}
+interface FFIDSubscriptionDowngradeAppliedPayload {
+    /** FFID subscription UUID. */
+    subscriptionId: string;
+    /** Organization UUID that owns the subscription. */
+    organizationId: string;
+    /** Plan UUID active before the pending downgrade was applied. */
+    previousPlanId: string;
+    /** Plan UUID that became active after the downgrade was applied. */
+    newPlanId: string;
+    /** Billing interval on the applied downgraded plan, typically 'monthly' or 'yearly'. */
+    billingInterval: string;
+    /** ISO timestamp when FFID applied the pending downgrade. */
+    appliedAt: string;
+}
+interface FFIDSubscriptionDowngradeCanceledPayload {
+    /** FFID subscription UUID. */
+    subscriptionId: string;
+    /** Organization UUID that owns the subscription. */
+    organizationId: string;
+    /** Plan UUID that had been pending but was canceled before taking effect. */
+    canceledPlanId: string;
+    /** Plan UUID that remains active after canceling the pending downgrade. */
+    currentPlanId: string;
+    /** ISO timestamp when the pending downgrade was canceled. */
+    canceledAt: string;
 }
 interface FFIDSubscriptionTrialEndingPayload {
     subscriptionId: string;
@@ -130,6 +183,13 @@ interface FFIDSubscriptionPaymentFailedPayload {
      * `null` means already blocking.
      */
     graceUntil?: string | null;
+    /** Canonical FFID access-control status derived from payment-failure severity. */
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    /**
+     * Alias of `graceUntil` for canonical access payloads; services should prefer
+     * this field when sharing code with `/subscriptions/ext/check`.
+     */
+    gracePeriodEndsAt?: 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
@@ -221,6 +281,9 @@ interface FFIDWebhookEventMap {
     'subscription.created': FFIDSubscriptionCreatedPayload;
     'subscription.updated': FFIDSubscriptionUpdatedPayload;
     'subscription.canceled': FFIDSubscriptionCanceledPayload;
+    'subscription.downgrade_scheduled': FFIDSubscriptionDowngradeScheduledPayload;
+    'subscription.downgrade_applied': FFIDSubscriptionDowngradeAppliedPayload;
+    'subscription.downgrade_canceled': FFIDSubscriptionDowngradeCanceledPayload;
     'subscription.trial_ending': FFIDSubscriptionTrialEndingPayload;
     'subscription.payment_failed': FFIDSubscriptionPaymentFailedPayload;
     'user.created': FFIDUserCreatedPayload;
@@ -363,4 +426,4 @@ declare function createFFIDWebhookHandler(config: FFIDWebhookHandlerConfig): {
 /** Type of the FFID Webhook handler */
 type FFIDWebhookHandler = ReturnType<typeof createFFIDWebhookHandler>;
 
-export { DEFAULT_TOLERANCE_SECONDS, type FFIDLegalAgreementRequiredPayload, type FFIDLegalDocumentUpdatedPayload, type FFIDOrganizationCreatedPayload, type FFIDOrganizationMemberAddedPayload, type FFIDOrganizationMemberRemovedPayload, type FFIDOrganizationMemberRoleChangedPayload, type FFIDOrganizationUpdatedPayload, type FFIDSubscriptionCanceledPayload, type FFIDSubscriptionCreatedPayload, type FFIDSubscriptionPaymentFailedPayload, type FFIDSubscriptionTrialEndingPayload, type FFIDSubscriptionUpdatedPayload, type FFIDSystemMaintenancePayload, type FFIDTestPingPayload, type FFIDUserCreatedPayload, type FFIDUserDeletedPayload, type FFIDUserDeletionRequestedPayload, type FFIDUserUpdatedPayload, FFIDWebhookError, type FFIDWebhookEvent, type FFIDWebhookEventHandler, type FFIDWebhookEventMap, type FFIDWebhookEventType, type FFIDWebhookHandler, type FFIDWebhookHandlerConfig, type FFIDWebhookLogger, FFIDWebhookPayloadError, FFIDWebhookSignatureError, FFIDWebhookTimestampError, FFID_WEBHOOK_EVENT_ID_HEADER, FFID_WEBHOOK_SIGNATURE_HEADER, FFID_WEBHOOK_SIGNATURE_VERSION, FFID_WEBHOOK_TIMESTAMP_HEADER, computeSignature, createFFIDWebhookHandler, parseSignatureHeader, verifyWebhookSignature };
+export { DEFAULT_TOLERANCE_SECONDS, type FFIDLegalAgreementRequiredPayload, type FFIDLegalDocumentUpdatedPayload, type FFIDOrganizationCreatedPayload, type FFIDOrganizationMemberAddedPayload, type FFIDOrganizationMemberRemovedPayload, type FFIDOrganizationMemberRoleChangedPayload, type FFIDOrganizationUpdatedPayload, type FFIDSubscriptionCanceledPayload, type FFIDSubscriptionCreatedPayload, type FFIDSubscriptionDowngradeAppliedPayload, type FFIDSubscriptionDowngradeCanceledPayload, type FFIDSubscriptionDowngradeScheduledPayload, type FFIDSubscriptionPaymentFailedPayload, type FFIDSubscriptionTrialEndingPayload, type FFIDSubscriptionUpdatedPayload, type FFIDSystemMaintenancePayload, type FFIDTestPingPayload, type FFIDUserCreatedPayload, type FFIDUserDeletedPayload, type FFIDUserDeletionRequestedPayload, type FFIDUserUpdatedPayload, FFIDWebhookError, type FFIDWebhookEvent, type FFIDWebhookEventHandler, type FFIDWebhookEventMap, type FFIDWebhookEventType, type FFIDWebhookHandler, type FFIDWebhookHandlerConfig, type FFIDWebhookLogger, FFIDWebhookPayloadError, FFIDWebhookSignatureError, FFIDWebhookTimestampError, FFID_WEBHOOK_EVENT_ID_HEADER, FFID_WEBHOOK_SIGNATURE_HEADER, FFID_WEBHOOK_SIGNATURE_VERSION, FFID_WEBHOOK_TIMESTAMP_HEADER, computeSignature, createFFIDWebhookHandler, parseSignatureHeader, verifyWebhookSignature };

package/package.json

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