@feelflow/ffid-sdk 7.2.0 → 8.0.0

package/dist/webhooks/index.d.ts

@@ -47,7 +47,7 @@ declare class FFIDWebhookPayloadError extends FFIDWebhookError {
  */
 
 /** All supported webhook event types */
-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';
+type FFIDWebhookEventType = 'subscription.created' | 'subscription.reactivated' | '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;
@@ -65,6 +65,46 @@ interface FFIDSubscriptionUpdatedPayload {
     effectiveStatus?: EffectiveSubscriptionStatus;
     gracePeriodEndsAt?: string | null;
 }
+/**
+ * `subscription.reactivated` (8.0.0): a cancellation reserved until the period end was
+ * withdrawn in the FFID portal, so the subscription continues. It pairs with the
+ * reservation-time `subscription.canceled` (`source: 'user_initiated'`,
+ * `reactivatable: true`). Sent only for contracts billed through Stripe.
+ */
+interface FFIDSubscriptionReactivatedPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    /** Plan code */
+    plan?: string;
+    status?: string;
+    effectiveStatus?: EffectiveSubscriptionStatus;
+    gracePeriodEndsAt?: string | null;
+    stripeSubscriptionId: string;
+    stripeCustomerId: string;
+    /** Code of the service the subscription belongs to (resolved by FFID when the event is sent) */
+    serviceCode?: string;
+}
+/**
+ * `subscription.canceled`.
+ *
+ * A contract billed through Stripe is canceled in two steps (FFID #6327), so **two events
+ * arrive per cancellation**:
+ *
+ * 1. At the reservation — `source: 'user_initiated'`, `reactivatable: true`, `cancelAt` /
+ *    `expiredAt` = the period end, no `effectiveStatus`. **Access continues until `cancelAt`**;
+ *    do not revoke it here. The reservation may still be withdrawn
+ *    (`subscription.reactivated`).
+ * 2. At the period end — `source: 'stripe_confirmed'`, `effectiveStatus: 'canceled'`. Revoke
+ *    access on this one.
+ *
+ * **Rule for consumers:** only an event with `source === 'user_initiated'` **and** a
+ * `cancelAt` is a reservation (keep access until `cancelAt`). Every other
+ * `subscription.canceled` ends access: the final `stripe_confirmed`, an immediate
+ * cancellation (`user_initiated` without `cancelAt` — a contract that cannot be reserved,
+ * e.g. no Stripe subscription or no period end yet; `expiredAt` is the cancellation time),
+ * and `payment_failure_auto_cancel` (automatic cancellation after unpaid invoices).
+ * Do not key the decision on `effectiveStatus`: it is set only on Stripe's deletion notice.
+ */
 interface FFIDSubscriptionCanceledPayload {
     /** FFID subscription UUID. */
     subscriptionId: string;
@@ -80,20 +120,28 @@ interface FFIDSubscriptionCanceledPayload {
      */
     stripeSubscriptionId: string | null;
     reason?: string;
+    /** When a reserved cancellation takes effect (the period end) */
     cancelAt?: string;
     /**
      * Origin of the cancellation. Always emitted by the FFID server — required
-     * by the wire shape in `SubscriptionCanceledPayload`.
+     * by the wire shape in `SubscriptionCanceledPayload`. Distinguishes the reservation
+     * (`user_initiated`) from the final event (`stripe_confirmed`); see the interface doc.
      */
     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.
+     * ISO timestamp at which access is (or was) lost. On the reservation event this is the
+     * future period end. May differ from `cancelAt` when Stripe runs out the paid period
+     * before emitting the deletion event.
      */
     expiredAt?: string;
-    /** Cancellation always leaves the canonical access-control status as `canceled`. */
+    /**
+     * `canceled` only on Stripe's deletion notice (e.g. the final `stripe_confirmed`). Absent on
+     * the reservation event, on immediate cancellations and on the cron's
+     * `payment_failure_auto_cancel` — so its absence does not mean "still usable"; decide by
+     * `source` + `cancelAt` (see the interface doc).
+     */
     effectiveStatus?: EffectiveSubscriptionStatus;
     /** Always null for cancellation events because no grace window remains. */
     gracePeriodEndsAt?: string | null;
@@ -279,6 +327,7 @@ interface FFIDTestPingPayload {
 /** Maps event type strings to their typed payloads */
 interface FFIDWebhookEventMap {
     'subscription.created': FFIDSubscriptionCreatedPayload;
+    'subscription.reactivated': FFIDSubscriptionReactivatedPayload;
     'subscription.updated': FFIDSubscriptionUpdatedPayload;
     'subscription.canceled': FFIDSubscriptionCanceledPayload;
     'subscription.downgrade_scheduled': FFIDSubscriptionDowngradeScheduledPayload;
@@ -426,4 +475,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 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 };
+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 FFIDSubscriptionReactivatedPayload, 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": "7.2.0",
+  "version": "8.0.0",
   "description": "FeelFlow ID Platform SDK for React/Next.js applications",
   "keywords": [
     "feelflow",