@feelflow/ffid-sdk 2.18.0 → 2.20.0

package/dist/server/index.js

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

package/dist/server/test/index.cjs

@@ -0,0 +1,105 @@
+'use strict';
+
+// src/server/test-client.ts
+var TEST_CLIENT_BRAND = /* @__PURE__ */ Symbol("@feelflow/ffid-sdk/test-client");
+var TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK = "I-acknowledge-this-bypasses-real-auth";
+function isTestFFIDClient(client) {
+  return typeof client === "object" && client !== null && TEST_CLIENT_BRAND in client && client[TEST_CLIENT_BRAND] === true;
+}
+var ERROR_CODE_TOKEN_VERIFICATION = "TOKEN_VERIFICATION_ERROR";
+var PRODUCTION_REFUSAL_HINT = "If this is intentional (staging that mirrors production env), pass `allowInProduction: TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK` and ensure the bypass tokens are not reachable from customer traffic.";
+function readNormalizedNodeEnv() {
+  if (typeof process === "undefined" || typeof process.env === "undefined") {
+    return void 0;
+  }
+  const raw = process.env.NODE_ENV;
+  return typeof raw === "string" ? raw.trim().toLowerCase() : void 0;
+}
+function emitProductionAcknowledgmentWarning() {
+  const msg = "[FFID] createTestFFIDClient: allowInProduction is set with NODE_ENV=production. Bypass tokens authenticate real requests in this process. Confirm this is staging.";
+  if (typeof process !== "undefined" && typeof process.emitWarning === "function") {
+    process.emitWarning(msg, "FFIDTestModeInProduction");
+  } else {
+    console.warn(msg);
+  }
+}
+function assertSafeEnvironment(acknowledged) {
+  const hasProcessEnv = typeof process !== "undefined" && typeof process.env !== "undefined";
+  const nodeEnv = readNormalizedNodeEnv();
+  const isProduction = nodeEnv === "production";
+  if (acknowledged) {
+    if (isProduction) emitProductionAcknowledgmentWarning();
+    return;
+  }
+  if (!hasProcessEnv) {
+    throw new Error(
+      "createTestFFIDClient: refused to start because the runtime does not expose process.env (likely an Edge / Cloudflare Workers / browser runtime). NODE_ENV cannot be verified here. " + PRODUCTION_REFUSAL_HINT
+    );
+  }
+  if (isProduction) {
+    throw new Error(
+      "createTestFFIDClient: refused to start because NODE_ENV=production. " + PRODUCTION_REFUSAL_HINT
+    );
+  }
+}
+function assertValidConfig(config) {
+  if (!config.users || config.users.length === 0) {
+    throw new Error("createTestFFIDClient: `users` must contain at least one entry");
+  }
+  const seenTokens = /* @__PURE__ */ new Set();
+  for (const user of config.users) {
+    if (!user.bypassToken || !user.bypassToken.trim()) {
+      throw new Error("createTestFFIDClient: every user requires a non-empty bypassToken");
+    }
+    if (!user.userInfo || !user.userInfo.sub) {
+      throw new Error("createTestFFIDClient: every user requires userInfo.sub");
+    }
+    if (seenTokens.has(user.bypassToken)) {
+      throw new Error(
+        "createTestFFIDClient: duplicate bypassToken detected (each token must map to exactly one user)"
+      );
+    }
+    seenTokens.add(user.bypassToken);
+  }
+}
+function createTestVerifyAccessToken(config) {
+  const acknowledged = config.allowInProduction === TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK;
+  assertSafeEnvironment(acknowledged);
+  assertValidConfig(config);
+  const lookup = /* @__PURE__ */ new Map();
+  for (const user of config.users) {
+    lookup.set(user.bypassToken, { ...user.userInfo });
+  }
+  return async function verifyAccessToken(accessToken) {
+    if (!accessToken || !accessToken.trim()) {
+      return {
+        error: {
+          code: ERROR_CODE_TOKEN_VERIFICATION,
+          message: "\u30A2\u30AF\u30BB\u30B9\u30C8\u30FC\u30AF\u30F3\u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093"
+        }
+      };
+    }
+    const matched = lookup.get(accessToken);
+    if (!matched) {
+      return {
+        error: {
+          code: ERROR_CODE_TOKEN_VERIFICATION,
+          message: "Test mode: bearer token did not match any registered bypass token"
+        }
+      };
+    }
+    return { data: { ...matched } };
+  };
+}
+function createTestFFIDClient(config) {
+  const verifyAccessToken = createTestVerifyAccessToken(config);
+  return {
+    verifyAccessToken,
+    [TEST_CLIENT_BRAND]: true
+  };
+}
+
+exports.TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK = TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK;
+exports.createTestFFIDClient = createTestFFIDClient;
+exports.createTestVerifyAccessToken = createTestVerifyAccessToken;
+exports.isTestFFIDClient = isTestFFIDClient;

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

@@ -0,0 +1,125 @@
+import { g as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-Cjm_TKUc.cjs';
+
+/**
+ * FFID SDK - Test mode client (E2E / integration test bypass)
+ *
+ * Provides a synthetic `verifyAccessToken` implementation that returns
+ * predetermined user info for known bypass tokens, **without ever calling
+ * the real FFID introspect endpoint**. Intended for consumer-side E2E
+ * tests where exercising the full OAuth flow is impractical (e.g.,
+ * automated browser tests against a staging environment).
+ *
+ * ⚠️  SECURITY: Construction is **refused** when `NODE_ENV` resolves to
+ * `production` (after trim + case-fold) or when the runtime does not
+ * expose `process.env` at all (e.g., Edge / Cloudflare Workers). The
+ * single escape hatch is the `allowInProduction` literal acknowledgment
+ * string. This is a defense-in-depth measure — never enable in
+ * customer-facing production.
+ *
+ * Recommended import path (sub-path keeps this out of production bundles):
+ *
+ *   import { createTestFFIDClient } from '@feelflow/ffid-sdk/server/test'
+ */
+
+/**
+ * Module-private symbol used to brand `TestFFIDClient` instances. Because
+ * the symbol is created here (not via `Symbol.for`), it cannot be obtained
+ * outside this module — which makes the brand unforgeable from foreign
+ * code. The brand still exists only for runtime narrowing convenience and
+ * is **not a security boundary**: enforcement of test-only behavior comes
+ * from the production guard, not from this brand.
+ */
+declare const TEST_CLIENT_BRAND: unique symbol;
+/**
+ * Acknowledgment string a caller must pass to `allowInProduction` when
+ * intentionally constructing the test client in a `NODE_ENV=production`
+ * runtime (typical for staging that mirrors production env). The literal
+ * value is grep-able so audits can find every legitimate use.
+ */
+declare const TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK: "I-acknowledge-this-bypasses-real-auth";
+type AllowInProductionAck = typeof TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK;
+/**
+ * A synthetic user that the test client recognises.
+ *
+ * `bypassToken` is the Bearer token a test caller sends in `Authorization`;
+ * the remaining fields populate the `FFIDOAuthUserInfo` returned by
+ * `verifyAccessToken`. Use distinct, non-trivial bypass tokens (≥ 32 chars
+ * recommended) — they grant full session impersonation when leaked.
+ */
+interface TestFFIDUser {
+    /** Bearer token value that resolves to this user */
+    bypassToken: string;
+    /** Synthetic FFID OAuth userinfo returned for matching bypass tokens */
+    userInfo: FFIDOAuthUserInfo;
+}
+/**
+ * Configuration accepted by `createTestFFIDClient` / `createTestVerifyAccessToken`.
+ */
+interface TestFFIDClientConfig {
+    /**
+     * Synthetic users keyed by `bypassToken`. Must contain at least one
+     * entry — the type encodes the non-empty rule via tuple syntax.
+     */
+    users: readonly [TestFFIDUser, ...TestFFIDUser[]];
+    /**
+     * Escape hatch to allow test-mode usage when `NODE_ENV` resolves to
+     * `production` (or when the runtime does not expose `process.env`).
+     *
+     * Must be set to the exact literal {@link TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK}
+     * — a `boolean` is intentionally rejected at the type level so a stray
+     * `allowInProduction: someFlag` cannot slip through code review. When
+     * honored in a production runtime, a runtime warning is emitted via
+     * `process.emitWarning('...', 'FFIDTestModeInProduction')`.
+     */
+    allowInProduction?: AllowInProductionAck;
+}
+/**
+ * Narrow client surface returned by `createTestFFIDClient`.
+ *
+ * Only `verifyAccessToken` is implemented — other `FFIDClient` methods
+ * would either need network access or have no meaningful test stub. The
+ * `verifyAccessToken` signature is bound to `FFIDClient['verifyAccessToken']`
+ * so any future production change (e.g., new options) becomes a TypeScript
+ * error here, surfacing drift instead of letting the test client silently
+ * lag the real client.
+ */
+interface TestFFIDClient {
+    verifyAccessToken: FFIDClient['verifyAccessToken'];
+    /** Module-private symbol used by {@link isTestFFIDClient} for runtime narrowing */
+    readonly [TEST_CLIENT_BRAND]: true;
+}
+/**
+ * Returns true when the given client was produced by `createTestFFIDClient`.
+ *
+ * Intended as a **runtime-narrowing** helper for code holding a
+ * `FFIDClient | TestFFIDClient` union. The brand symbol is module-private
+ * and unforgeable from outside this module, but `isTestFFIDClient` is not
+ * a trust boundary — production code paths should rely on the construction-
+ * time `NODE_ENV` guard, not on this check.
+ */
+declare function isTestFFIDClient(client: unknown): client is TestFFIDClient;
+/**
+ * Build a `verifyAccessToken` function that bypasses the real FFID
+ * introspect call and returns synthetic user info for known tokens.
+ *
+ * @throws {Error} when `NODE_ENV` resolves to `production` and
+ *   `allowInProduction` is not set, when `process.env` is unavailable
+ *   (Edge / Workers) and `allowInProduction` is not set, or when
+ *   `config` fails validation (empty users / blank or duplicate
+ *   bypassToken / missing userInfo.sub).
+ */
+declare function createTestVerifyAccessToken(config: TestFFIDClientConfig): TestFFIDClient['verifyAccessToken'];
+/**
+ * Create a minimal FFID client suitable for E2E tests.
+ *
+ * Returns an object exposing only `verifyAccessToken`; other methods that
+ * would normally call the real FFID API are intentionally **not** stubbed
+ * to avoid silent fallbacks. Callers that need additional methods should
+ * mock those at the test boundary (e.g., MSW for HTTP) rather than
+ * extending this client.
+ *
+ * @throws {Error} same conditions as {@link createTestVerifyAccessToken}.
+ */
+declare function createTestFFIDClient(config: TestFFIDClientConfig): TestFFIDClient;
+
+export { TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK, type TestFFIDClient, type TestFFIDClientConfig, type TestFFIDUser, createTestFFIDClient, createTestVerifyAccessToken, isTestFFIDClient };

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

@@ -0,0 +1,125 @@
+import { g as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-Cjm_TKUc.js';
+
+/**
+ * FFID SDK - Test mode client (E2E / integration test bypass)
+ *
+ * Provides a synthetic `verifyAccessToken` implementation that returns
+ * predetermined user info for known bypass tokens, **without ever calling
+ * the real FFID introspect endpoint**. Intended for consumer-side E2E
+ * tests where exercising the full OAuth flow is impractical (e.g.,
+ * automated browser tests against a staging environment).
+ *
+ * ⚠️  SECURITY: Construction is **refused** when `NODE_ENV` resolves to
+ * `production` (after trim + case-fold) or when the runtime does not
+ * expose `process.env` at all (e.g., Edge / Cloudflare Workers). The
+ * single escape hatch is the `allowInProduction` literal acknowledgment
+ * string. This is a defense-in-depth measure — never enable in
+ * customer-facing production.
+ *
+ * Recommended import path (sub-path keeps this out of production bundles):
+ *
+ *   import { createTestFFIDClient } from '@feelflow/ffid-sdk/server/test'
+ */
+
+/**
+ * Module-private symbol used to brand `TestFFIDClient` instances. Because
+ * the symbol is created here (not via `Symbol.for`), it cannot be obtained
+ * outside this module — which makes the brand unforgeable from foreign
+ * code. The brand still exists only for runtime narrowing convenience and
+ * is **not a security boundary**: enforcement of test-only behavior comes
+ * from the production guard, not from this brand.
+ */
+declare const TEST_CLIENT_BRAND: unique symbol;
+/**
+ * Acknowledgment string a caller must pass to `allowInProduction` when
+ * intentionally constructing the test client in a `NODE_ENV=production`
+ * runtime (typical for staging that mirrors production env). The literal
+ * value is grep-able so audits can find every legitimate use.
+ */
+declare const TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK: "I-acknowledge-this-bypasses-real-auth";
+type AllowInProductionAck = typeof TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK;
+/**
+ * A synthetic user that the test client recognises.
+ *
+ * `bypassToken` is the Bearer token a test caller sends in `Authorization`;
+ * the remaining fields populate the `FFIDOAuthUserInfo` returned by
+ * `verifyAccessToken`. Use distinct, non-trivial bypass tokens (≥ 32 chars
+ * recommended) — they grant full session impersonation when leaked.
+ */
+interface TestFFIDUser {
+    /** Bearer token value that resolves to this user */
+    bypassToken: string;
+    /** Synthetic FFID OAuth userinfo returned for matching bypass tokens */
+    userInfo: FFIDOAuthUserInfo;
+}
+/**
+ * Configuration accepted by `createTestFFIDClient` / `createTestVerifyAccessToken`.
+ */
+interface TestFFIDClientConfig {
+    /**
+     * Synthetic users keyed by `bypassToken`. Must contain at least one
+     * entry — the type encodes the non-empty rule via tuple syntax.
+     */
+    users: readonly [TestFFIDUser, ...TestFFIDUser[]];
+    /**
+     * Escape hatch to allow test-mode usage when `NODE_ENV` resolves to
+     * `production` (or when the runtime does not expose `process.env`).
+     *
+     * Must be set to the exact literal {@link TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK}
+     * — a `boolean` is intentionally rejected at the type level so a stray
+     * `allowInProduction: someFlag` cannot slip through code review. When
+     * honored in a production runtime, a runtime warning is emitted via
+     * `process.emitWarning('...', 'FFIDTestModeInProduction')`.
+     */
+    allowInProduction?: AllowInProductionAck;
+}
+/**
+ * Narrow client surface returned by `createTestFFIDClient`.
+ *
+ * Only `verifyAccessToken` is implemented — other `FFIDClient` methods
+ * would either need network access or have no meaningful test stub. The
+ * `verifyAccessToken` signature is bound to `FFIDClient['verifyAccessToken']`
+ * so any future production change (e.g., new options) becomes a TypeScript
+ * error here, surfacing drift instead of letting the test client silently
+ * lag the real client.
+ */
+interface TestFFIDClient {
+    verifyAccessToken: FFIDClient['verifyAccessToken'];
+    /** Module-private symbol used by {@link isTestFFIDClient} for runtime narrowing */
+    readonly [TEST_CLIENT_BRAND]: true;
+}
+/**
+ * Returns true when the given client was produced by `createTestFFIDClient`.
+ *
+ * Intended as a **runtime-narrowing** helper for code holding a
+ * `FFIDClient | TestFFIDClient` union. The brand symbol is module-private
+ * and unforgeable from outside this module, but `isTestFFIDClient` is not
+ * a trust boundary — production code paths should rely on the construction-
+ * time `NODE_ENV` guard, not on this check.
+ */
+declare function isTestFFIDClient(client: unknown): client is TestFFIDClient;
+/**
+ * Build a `verifyAccessToken` function that bypasses the real FFID
+ * introspect call and returns synthetic user info for known tokens.
+ *
+ * @throws {Error} when `NODE_ENV` resolves to `production` and
+ *   `allowInProduction` is not set, when `process.env` is unavailable
+ *   (Edge / Workers) and `allowInProduction` is not set, or when
+ *   `config` fails validation (empty users / blank or duplicate
+ *   bypassToken / missing userInfo.sub).
+ */
+declare function createTestVerifyAccessToken(config: TestFFIDClientConfig): TestFFIDClient['verifyAccessToken'];
+/**
+ * Create a minimal FFID client suitable for E2E tests.
+ *
+ * Returns an object exposing only `verifyAccessToken`; other methods that
+ * would normally call the real FFID API are intentionally **not** stubbed
+ * to avoid silent fallbacks. Callers that need additional methods should
+ * mock those at the test boundary (e.g., MSW for HTTP) rather than
+ * extending this client.
+ *
+ * @throws {Error} same conditions as {@link createTestVerifyAccessToken}.
+ */
+declare function createTestFFIDClient(config: TestFFIDClientConfig): TestFFIDClient;
+
+export { TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK, type TestFFIDClient, type TestFFIDClientConfig, type TestFFIDUser, createTestFFIDClient, createTestVerifyAccessToken, isTestFFIDClient };

package/dist/server/test/index.js

@@ -0,0 +1,100 @@
+// src/server/test-client.ts
+var TEST_CLIENT_BRAND = /* @__PURE__ */ Symbol("@feelflow/ffid-sdk/test-client");
+var TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK = "I-acknowledge-this-bypasses-real-auth";
+function isTestFFIDClient(client) {
+  return typeof client === "object" && client !== null && TEST_CLIENT_BRAND in client && client[TEST_CLIENT_BRAND] === true;
+}
+var ERROR_CODE_TOKEN_VERIFICATION = "TOKEN_VERIFICATION_ERROR";
+var PRODUCTION_REFUSAL_HINT = "If this is intentional (staging that mirrors production env), pass `allowInProduction: TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK` and ensure the bypass tokens are not reachable from customer traffic.";
+function readNormalizedNodeEnv() {
+  if (typeof process === "undefined" || typeof process.env === "undefined") {
+    return void 0;
+  }
+  const raw = process.env.NODE_ENV;
+  return typeof raw === "string" ? raw.trim().toLowerCase() : void 0;
+}
+function emitProductionAcknowledgmentWarning() {
+  const msg = "[FFID] createTestFFIDClient: allowInProduction is set with NODE_ENV=production. Bypass tokens authenticate real requests in this process. Confirm this is staging.";
+  if (typeof process !== "undefined" && typeof process.emitWarning === "function") {
+    process.emitWarning(msg, "FFIDTestModeInProduction");
+  } else {
+    console.warn(msg);
+  }
+}
+function assertSafeEnvironment(acknowledged) {
+  const hasProcessEnv = typeof process !== "undefined" && typeof process.env !== "undefined";
+  const nodeEnv = readNormalizedNodeEnv();
+  const isProduction = nodeEnv === "production";
+  if (acknowledged) {
+    if (isProduction) emitProductionAcknowledgmentWarning();
+    return;
+  }
+  if (!hasProcessEnv) {
+    throw new Error(
+      "createTestFFIDClient: refused to start because the runtime does not expose process.env (likely an Edge / Cloudflare Workers / browser runtime). NODE_ENV cannot be verified here. " + PRODUCTION_REFUSAL_HINT
+    );
+  }
+  if (isProduction) {
+    throw new Error(
+      "createTestFFIDClient: refused to start because NODE_ENV=production. " + PRODUCTION_REFUSAL_HINT
+    );
+  }
+}
+function assertValidConfig(config) {
+  if (!config.users || config.users.length === 0) {
+    throw new Error("createTestFFIDClient: `users` must contain at least one entry");
+  }
+  const seenTokens = /* @__PURE__ */ new Set();
+  for (const user of config.users) {
+    if (!user.bypassToken || !user.bypassToken.trim()) {
+      throw new Error("createTestFFIDClient: every user requires a non-empty bypassToken");
+    }
+    if (!user.userInfo || !user.userInfo.sub) {
+      throw new Error("createTestFFIDClient: every user requires userInfo.sub");
+    }
+    if (seenTokens.has(user.bypassToken)) {
+      throw new Error(
+        "createTestFFIDClient: duplicate bypassToken detected (each token must map to exactly one user)"
+      );
+    }
+    seenTokens.add(user.bypassToken);
+  }
+}
+function createTestVerifyAccessToken(config) {
+  const acknowledged = config.allowInProduction === TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK;
+  assertSafeEnvironment(acknowledged);
+  assertValidConfig(config);
+  const lookup = /* @__PURE__ */ new Map();
+  for (const user of config.users) {
+    lookup.set(user.bypassToken, { ...user.userInfo });
+  }
+  return async function verifyAccessToken(accessToken) {
+    if (!accessToken || !accessToken.trim()) {
+      return {
+        error: {
+          code: ERROR_CODE_TOKEN_VERIFICATION,
+          message: "\u30A2\u30AF\u30BB\u30B9\u30C8\u30FC\u30AF\u30F3\u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093"
+        }
+      };
+    }
+    const matched = lookup.get(accessToken);
+    if (!matched) {
+      return {
+        error: {
+          code: ERROR_CODE_TOKEN_VERIFICATION,
+          message: "Test mode: bearer token did not match any registered bypass token"
+        }
+      };
+    }
+    return { data: { ...matched } };
+  };
+}
+function createTestFFIDClient(config) {
+  const verifyAccessToken = createTestVerifyAccessToken(config);
+  return {
+    verifyAccessToken,
+    [TEST_CLIENT_BRAND]: true
+  };
+}
+
+export { TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK, createTestFFIDClient, createTestVerifyAccessToken, isTestFFIDClient };

package/dist/webhooks/index.d.cts

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

package/dist/webhooks/index.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feelflow/ffid-sdk",
-  "version": "2.18.0",
+  "version": "2.20.0",
   "description": "FeelFlow ID Platform SDK for React/Next.js applications",
   "keywords": [
     "feelflow",
@@ -60,6 +60,11 @@
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js",
       "require": "./dist/server/index.cjs"
+    },
+    "./server/test": {
+      "types": "./dist/server/test/index.d.ts",
+      "import": "./dist/server/test/index.js",
+      "require": "./dist/server/test/index.cjs"
     }
   },
   "files": [