@feelflow/ffid-sdk 2.17.1 → 2.19.0

package/dist/server/index.cjs

@@ -101,10 +101,7 @@ function createTokenStore(storageType) {
 // src/client/oauth-userinfo.ts
 var SESSION_ELIGIBLE_SUBSCRIPTION_STATUSES = [
   "trialing",
-  "active",
-  "past_due",
-  "canceled",
-  "paused"
+  "active"
 ];
 function isSessionEligibleSubscriptionStatus(value) {
   return typeof value === "string" && SESSION_ELIGIBLE_SUBSCRIPTION_STATUSES.includes(value);
@@ -806,7 +803,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "2.17.1";
+var SDK_VERSION = "2.19.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1303,6 +1300,19 @@ function storeCodeVerifier(verifier, logger) {
   }
   return sessionStored || localStored;
 }
+function cleanupVerifierStorage(logger) {
+  try {
+    window.sessionStorage.removeItem(VERIFIER_STORAGE_KEY);
+  } catch (error) {
+    logger?.warn("retrieveCodeVerifier: sessionStorage \u306E\u30AF\u30EA\u30FC\u30F3\u30A2\u30C3\u30D7\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+  try {
+    window.localStorage.removeItem(VERIFIER_FALLBACK_STORAGE_KEY);
+    window.localStorage.removeItem(VERIFIER_FALLBACK_TIMESTAMP_KEY);
+  } catch (error) {
+    logger?.warn("retrieveCodeVerifier: localStorage \u306E\u30AF\u30EA\u30FC\u30F3\u30A2\u30C3\u30D7\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+}
 function base64UrlEncode(buffer) {
   const bytes = new Uint8Array(buffer);
   let binary = "";
@@ -1317,6 +1327,87 @@ var OAUTH_AUTHORIZE_ENDPOINT = "/api/v1/oauth/authorize";
 var AUTH_LOGOUT_ENDPOINT = "/api/v1/auth/logout";
 var STATE_RANDOM_BYTES = 16;
 var HEX_BASE2 = 16;
+var REDIRECT_LOOP_KEY = "ffid_sdk_redirect_loop_history";
+var REDIRECT_LOOP_WINDOW_MS = 6e4;
+var REDIRECT_LOOP_THRESHOLD = 3;
+var storageReadFailureLogged = false;
+var storageWriteFailureLogged = false;
+function logStorageReadFailure(logger, err) {
+  if (storageReadFailureLogged) return;
+  storageReadFailureLogged = true;
+  logger.warn(
+    "[FFID SDK] sessionStorage read failed \u2014 redirect loop detection disabled on this browser (fail-open). iOS WebKit private mode / eviction \u304C\u5178\u578B\u8981\u56E0",
+    err
+  );
+}
+function logStorageWriteFailure(logger, err) {
+  if (storageWriteFailureLogged) return;
+  storageWriteFailureLogged = true;
+  logger.warn(
+    "[FFID SDK] sessionStorage write failed \u2014 redirect loop detection disabled on this browser (fail-open).",
+    err
+  );
+}
+function isRedirectLoopHistory(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.values(value).every(
+    (arr) => Array.isArray(arr) && arr.every((t) => typeof t === "number" && Number.isFinite(t))
+  );
+}
+function readRedirectLoopHistory(logger) {
+  if (typeof window === "undefined") return {};
+  try {
+    const raw = window.sessionStorage.getItem(REDIRECT_LOOP_KEY);
+    if (raw === null) return {};
+    const parsed = JSON.parse(raw);
+    return isRedirectLoopHistory(parsed) ? parsed : {};
+  } catch (err) {
+    logStorageReadFailure(logger, err);
+    return {};
+  }
+}
+function writeRedirectLoopHistory(history, logger) {
+  if (typeof window === "undefined") return;
+  try {
+    window.sessionStorage.setItem(REDIRECT_LOOP_KEY, JSON.stringify(history));
+  } catch (err) {
+    logStorageWriteFailure(logger, err);
+  }
+}
+function pruneRedirectLoopHistory(history, now) {
+  const cutoff = now - REDIRECT_LOOP_WINDOW_MS;
+  const pruned = {};
+  for (const [key, timestamps] of Object.entries(history)) {
+    const fresh = timestamps.filter((t) => t > cutoff);
+    if (fresh.length > 0) pruned[key] = fresh;
+  }
+  return pruned;
+}
+function getRecentRedirectCount(authorizeKey, now, logger) {
+  const pruned = pruneRedirectLoopHistory(readRedirectLoopHistory(logger), now);
+  writeRedirectLoopHistory(pruned, logger);
+  return pruned[authorizeKey]?.length ?? 0;
+}
+function recordRedirectAttempt(authorizeKey, now, logger) {
+  const history = readRedirectLoopHistory(logger);
+  const existing = history[authorizeKey] ?? [];
+  history[authorizeKey] = [...existing, now];
+  writeRedirectLoopHistory(history, logger);
+}
+function rollbackLastRedirectAttempt(authorizeKey, logger) {
+  const history = readRedirectLoopHistory(logger);
+  const existing = history[authorizeKey];
+  if (!Array.isArray(existing) || existing.length === 0) return;
+  history[authorizeKey] = existing.slice(0, -1);
+  if (history[authorizeKey].length === 0) delete history[authorizeKey];
+  writeRedirectLoopHistory(history, logger);
+}
+function buildAuthorizeKey(baseUrl, clientId, organizationId) {
+  const params = new URLSearchParams({ client_id: clientId });
+  const trimmedOrg = organizationId?.trim();
+  if (trimmedOrg) params.set("organization_id", trimmedOrg);
+  return `${baseUrl}${OAUTH_AUTHORIZE_ENDPOINT}?${params.toString()}`;
+}
 function generateRandomState() {
   const array = new Uint8Array(STATE_RANDOM_BYTES);
   crypto.getRandomValues(array);
@@ -1336,6 +1427,23 @@ function createRedirectMethods(deps) {
       logger.warn("SSR \u74B0\u5883\u3067\u306F\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u3067\u304D\u307E\u305B\u3093");
       return { success: false, error: "SSR \u74B0\u5883\u3067\u306F\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u3067\u304D\u307E\u305B\u3093" };
     }
+    const authorizeKey = buildAuthorizeKey(baseUrl, clientId, options?.organizationId);
+    const now = Date.now();
+    const recentCount = getRecentRedirectCount(authorizeKey, now, logger);
+    if (recentCount >= REDIRECT_LOOP_THRESHOLD) {
+      cleanupVerifierStorage(logger);
+      logger.warn("[FFID SDK] redirect loop detected \u2014 \u81EA\u52D5\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u3092\u505C\u6B62\u3057\u307E\u3057\u305F", {
+        authorizeKey,
+        recentCount,
+        windowMs: REDIRECT_LOOP_WINDOW_MS,
+        threshold: REDIRECT_LOOP_THRESHOLD
+      });
+      return {
+        success: false,
+        code: "redirect_loop_detected",
+        error: "\u77ED\u6642\u9593\u306B\u540C\u3058\u8A8D\u53EF\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8\u3078\u306E\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u304C\u7E70\u308A\u8FD4\u3055\u308C\u305F\u305F\u3081\u3001\u30EB\u30FC\u30D7\u691C\u51FA\u306B\u3088\u308A\u81EA\u52D5\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u3092\u505C\u6B62\u3057\u307E\u3057\u305F"
+      };
+    }
     const verifier = generateCodeVerifier();
     storeCodeVerifier(verifier, logger);
     let challenge;
@@ -1366,7 +1474,13 @@ function createRedirectMethods(deps) {
     }
     const authorizeUrl = `${baseUrl}${OAUTH_AUTHORIZE_ENDPOINT}?${params.toString()}`;
     logger.debug("Redirecting to authorize:", authorizeUrl);
-    window.location.href = authorizeUrl;
+    recordRedirectAttempt(authorizeKey, now, logger);
+    try {
+      window.location.href = authorizeUrl;
+    } catch (err) {
+      rollbackLastRedirectAttempt(authorizeKey, logger);
+      throw err;
+    }
     return { success: true };
   }
   async function redirectToLogin() {

package/dist/server/index.d.cts

@@ -891,17 +891,36 @@ interface FFIDUpdateUserProfileRequest {
     /** Arbitrary user preferences bag (null clears the column; reads return {}) */
     preferences?: Record<string, unknown> | null;
 }
+/**
+ * Discriminant for redirect failures that callers need to handle
+ * programmatically (vs. logging the human-readable `error` string).
+ *
+ * - `'redirect_loop_detected'`: `redirectToAuthorize()` detected that the
+ *   same authorize URL (keyed by `baseUrl + client_id + organization_id`)
+ *   has been fired **3 times within 60 seconds**. Caller should surface a
+ *   manual "再度ログインする" UI rather than retry automatically (#2406 / #2411).
+ *
+ * SDK 2.18.0 only ships `'redirect_loop_detected'`. Other failure paths
+ * (SSR environment, PKCE generation failure, empty organizationId) currently
+ * return `error` without a `code`. New codes will be added in future minor
+ * versions — treat this union as forward-extensible and do NOT exhaustively
+ * `switch` over it without a `default` branch for consumer code that must
+ * stay compatible across SDK upgrades.
+ */
+type FFIDRedirectErrorCode = 'redirect_loop_detected';
 /**
  * Result of a redirect operation (redirectToLogin / redirectToAuthorize / redirectToLogout)
  *
  * Structured return type so callers can inspect failure reasons
- * instead of receiving a bare `false`.
+ * instead of receiving a bare `false`. When `code` is set, branch on it
+ * for programmatic handling; otherwise log `error` for humans.
  */
 type FFIDRedirectResult = {
     success: true;
 } | {
     success: false;
     error: string;
+    code?: FFIDRedirectErrorCode;
 };
 
 /** OTP / magic link methods - sendOtp / verifyOtp */

package/dist/server/index.d.ts

@@ -891,17 +891,36 @@ interface FFIDUpdateUserProfileRequest {
     /** Arbitrary user preferences bag (null clears the column; reads return {}) */
     preferences?: Record<string, unknown> | null;
 }
+/**
+ * Discriminant for redirect failures that callers need to handle
+ * programmatically (vs. logging the human-readable `error` string).
+ *
+ * - `'redirect_loop_detected'`: `redirectToAuthorize()` detected that the
+ *   same authorize URL (keyed by `baseUrl + client_id + organization_id`)
+ *   has been fired **3 times within 60 seconds**. Caller should surface a
+ *   manual "再度ログインする" UI rather than retry automatically (#2406 / #2411).
+ *
+ * SDK 2.18.0 only ships `'redirect_loop_detected'`. Other failure paths
+ * (SSR environment, PKCE generation failure, empty organizationId) currently
+ * return `error` without a `code`. New codes will be added in future minor
+ * versions — treat this union as forward-extensible and do NOT exhaustively
+ * `switch` over it without a `default` branch for consumer code that must
+ * stay compatible across SDK upgrades.
+ */
+type FFIDRedirectErrorCode = 'redirect_loop_detected';
 /**
  * Result of a redirect operation (redirectToLogin / redirectToAuthorize / redirectToLogout)
  *
  * Structured return type so callers can inspect failure reasons
- * instead of receiving a bare `false`.
+ * instead of receiving a bare `false`. When `code` is set, branch on it
+ * for programmatic handling; otherwise log `error` for humans.
  */
 type FFIDRedirectResult = {
     success: true;
 } | {
     success: false;
     error: string;
+    code?: FFIDRedirectErrorCode;
 };
 
 /** OTP / magic link methods - sendOtp / verifyOtp */

package/dist/server/index.js

@@ -100,10 +100,7 @@ function createTokenStore(storageType) {
 // src/client/oauth-userinfo.ts
 var SESSION_ELIGIBLE_SUBSCRIPTION_STATUSES = [
   "trialing",
-  "active",
-  "past_due",
-  "canceled",
-  "paused"
+  "active"
 ];
 function isSessionEligibleSubscriptionStatus(value) {
   return typeof value === "string" && SESSION_ELIGIBLE_SUBSCRIPTION_STATUSES.includes(value);
@@ -805,7 +802,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "2.17.1";
+var SDK_VERSION = "2.19.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1302,6 +1299,19 @@ function storeCodeVerifier(verifier, logger) {
   }
   return sessionStored || localStored;
 }
+function cleanupVerifierStorage(logger) {
+  try {
+    window.sessionStorage.removeItem(VERIFIER_STORAGE_KEY);
+  } catch (error) {
+    logger?.warn("retrieveCodeVerifier: sessionStorage \u306E\u30AF\u30EA\u30FC\u30F3\u30A2\u30C3\u30D7\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+  try {
+    window.localStorage.removeItem(VERIFIER_FALLBACK_STORAGE_KEY);
+    window.localStorage.removeItem(VERIFIER_FALLBACK_TIMESTAMP_KEY);
+  } catch (error) {
+    logger?.warn("retrieveCodeVerifier: localStorage \u306E\u30AF\u30EA\u30FC\u30F3\u30A2\u30C3\u30D7\u306B\u5931\u6557\u3057\u307E\u3057\u305F:", error);
+  }
+}
 function base64UrlEncode(buffer) {
   const bytes = new Uint8Array(buffer);
   let binary = "";
@@ -1316,6 +1326,87 @@ var OAUTH_AUTHORIZE_ENDPOINT = "/api/v1/oauth/authorize";
 var AUTH_LOGOUT_ENDPOINT = "/api/v1/auth/logout";
 var STATE_RANDOM_BYTES = 16;
 var HEX_BASE2 = 16;
+var REDIRECT_LOOP_KEY = "ffid_sdk_redirect_loop_history";
+var REDIRECT_LOOP_WINDOW_MS = 6e4;
+var REDIRECT_LOOP_THRESHOLD = 3;
+var storageReadFailureLogged = false;
+var storageWriteFailureLogged = false;
+function logStorageReadFailure(logger, err) {
+  if (storageReadFailureLogged) return;
+  storageReadFailureLogged = true;
+  logger.warn(
+    "[FFID SDK] sessionStorage read failed \u2014 redirect loop detection disabled on this browser (fail-open). iOS WebKit private mode / eviction \u304C\u5178\u578B\u8981\u56E0",
+    err
+  );
+}
+function logStorageWriteFailure(logger, err) {
+  if (storageWriteFailureLogged) return;
+  storageWriteFailureLogged = true;
+  logger.warn(
+    "[FFID SDK] sessionStorage write failed \u2014 redirect loop detection disabled on this browser (fail-open).",
+    err
+  );
+}
+function isRedirectLoopHistory(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.values(value).every(
+    (arr) => Array.isArray(arr) && arr.every((t) => typeof t === "number" && Number.isFinite(t))
+  );
+}
+function readRedirectLoopHistory(logger) {
+  if (typeof window === "undefined") return {};
+  try {
+    const raw = window.sessionStorage.getItem(REDIRECT_LOOP_KEY);
+    if (raw === null) return {};
+    const parsed = JSON.parse(raw);
+    return isRedirectLoopHistory(parsed) ? parsed : {};
+  } catch (err) {
+    logStorageReadFailure(logger, err);
+    return {};
+  }
+}
+function writeRedirectLoopHistory(history, logger) {
+  if (typeof window === "undefined") return;
+  try {
+    window.sessionStorage.setItem(REDIRECT_LOOP_KEY, JSON.stringify(history));
+  } catch (err) {
+    logStorageWriteFailure(logger, err);
+  }
+}
+function pruneRedirectLoopHistory(history, now) {
+  const cutoff = now - REDIRECT_LOOP_WINDOW_MS;
+  const pruned = {};
+  for (const [key, timestamps] of Object.entries(history)) {
+    const fresh = timestamps.filter((t) => t > cutoff);
+    if (fresh.length > 0) pruned[key] = fresh;
+  }
+  return pruned;
+}
+function getRecentRedirectCount(authorizeKey, now, logger) {
+  const pruned = pruneRedirectLoopHistory(readRedirectLoopHistory(logger), now);
+  writeRedirectLoopHistory(pruned, logger);
+  return pruned[authorizeKey]?.length ?? 0;
+}
+function recordRedirectAttempt(authorizeKey, now, logger) {
+  const history = readRedirectLoopHistory(logger);
+  const existing = history[authorizeKey] ?? [];
+  history[authorizeKey] = [...existing, now];
+  writeRedirectLoopHistory(history, logger);
+}
+function rollbackLastRedirectAttempt(authorizeKey, logger) {
+  const history = readRedirectLoopHistory(logger);
+  const existing = history[authorizeKey];
+  if (!Array.isArray(existing) || existing.length === 0) return;
+  history[authorizeKey] = existing.slice(0, -1);
+  if (history[authorizeKey].length === 0) delete history[authorizeKey];
+  writeRedirectLoopHistory(history, logger);
+}
+function buildAuthorizeKey(baseUrl, clientId, organizationId) {
+  const params = new URLSearchParams({ client_id: clientId });
+  const trimmedOrg = organizationId?.trim();
+  if (trimmedOrg) params.set("organization_id", trimmedOrg);
+  return `${baseUrl}${OAUTH_AUTHORIZE_ENDPOINT}?${params.toString()}`;
+}
 function generateRandomState() {
   const array = new Uint8Array(STATE_RANDOM_BYTES);
   crypto.getRandomValues(array);
@@ -1335,6 +1426,23 @@ function createRedirectMethods(deps) {
       logger.warn("SSR \u74B0\u5883\u3067\u306F\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u3067\u304D\u307E\u305B\u3093");
       return { success: false, error: "SSR \u74B0\u5883\u3067\u306F\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u3067\u304D\u307E\u305B\u3093" };
     }
+    const authorizeKey = buildAuthorizeKey(baseUrl, clientId, options?.organizationId);
+    const now = Date.now();
+    const recentCount = getRecentRedirectCount(authorizeKey, now, logger);
+    if (recentCount >= REDIRECT_LOOP_THRESHOLD) {
+      cleanupVerifierStorage(logger);
+      logger.warn("[FFID SDK] redirect loop detected \u2014 \u81EA\u52D5\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u3092\u505C\u6B62\u3057\u307E\u3057\u305F", {
+        authorizeKey,
+        recentCount,
+        windowMs: REDIRECT_LOOP_WINDOW_MS,
+        threshold: REDIRECT_LOOP_THRESHOLD
+      });
+      return {
+        success: false,
+        code: "redirect_loop_detected",
+        error: "\u77ED\u6642\u9593\u306B\u540C\u3058\u8A8D\u53EF\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8\u3078\u306E\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u304C\u7E70\u308A\u8FD4\u3055\u308C\u305F\u305F\u3081\u3001\u30EB\u30FC\u30D7\u691C\u51FA\u306B\u3088\u308A\u81EA\u52D5\u30EA\u30C0\u30A4\u30EC\u30AF\u30C8\u3092\u505C\u6B62\u3057\u307E\u3057\u305F"
+      };
+    }
     const verifier = generateCodeVerifier();
     storeCodeVerifier(verifier, logger);
     let challenge;
@@ -1365,7 +1473,13 @@ function createRedirectMethods(deps) {
     }
     const authorizeUrl = `${baseUrl}${OAUTH_AUTHORIZE_ENDPOINT}?${params.toString()}`;
     logger.debug("Redirecting to authorize:", authorizeUrl);
-    window.location.href = authorizeUrl;
+    recordRedirectAttempt(authorizeKey, now, logger);
+    try {
+      window.location.href = authorizeUrl;
+    } catch (err) {
+      rollbackLastRedirectAttempt(authorizeKey, logger);
+      throw err;
+    }
     return { success: true };
   }
   async function redirectToLogin() {

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.17.1",
+  "version": "2.19.0",
   "description": "FeelFlow ID Platform SDK for React/Next.js applications",
   "keywords": [
     "feelflow",