@feelflow/ffid-sdk 8.1.0 → 10.0.0

package/dist/webhooks/index.d.ts

@@ -39,6 +39,74 @@ declare class FFIDWebhookPayloadError extends FFIDWebhookError {
     constructor(message?: string);
 }
 
+/**
+ * `credits.*` webhook payloads (SDK 10.0.0, FFID CREDITS_API §8).
+ *
+ * Separate file to keep `types.ts` small. Mirrors the FFID server's
+ * `src/lib/webhooks/credits-payloads.ts`; the FFID repository type-checks the two
+ * against each other (`sdk-credits-payloads.sync.test.ts`).
+ */
+/**
+ * Fields every `credits.*` payload carries (10.0.0, CREDITS_API §8).
+ *
+ * `credits.*` events are broadcast to every endpoint subscribed to the event type,
+ * so compare `serviceCode` with your own service code before acting. It is absent
+ * only when FFID could not resolve it — do not read absence as "not for this service".
+ */
+interface FFIDCreditsEventBase {
+    subscriptionId: string;
+    organizationId: string;
+    /** Time the event happened (ISO 8601) */
+    occurredAt: string;
+    serviceCode?: string;
+}
+/**
+ * `credits.granted` — a monthly / manual / pack grant was created. Sent once per
+ * grant (`grantId`). A pack purchase also sends `credits.pack_purchased`.
+ */
+interface FFIDCreditsGrantedPayload extends FFIDCreditsEventBase {
+    grantId: string;
+    kind: 'monthly' | 'manual' | 'pack';
+    amount: number;
+    expiresAt: string;
+    /** Only when `kind === 'monthly'` */
+    periodStart?: string;
+    /** Only when `kind === 'monthly'` */
+    periodEnd?: string;
+    /** Balance read after the grant — a reference value; the balance API is authoritative */
+    balanceAfter: number;
+}
+/** `credits.low` — the balance fell below the low threshold (once per period) */
+interface FFIDCreditsLowPayload extends FFIDCreditsEventBase {
+    available: number;
+    monthlyCredits: number;
+    thresholdPercent: number;
+    /** End of the current period; null only when FFID could not read it */
+    periodEnd: string | null;
+}
+/** `credits.exhausted` — the balance reached 0 (once per period) */
+interface FFIDCreditsExhaustedPayload extends FFIDCreditsEventBase {
+    available: number;
+    monthlyCredits: number;
+    /** End of the current period; null only when FFID could not read it */
+    periodEnd: string | null;
+}
+/** `credits.pack_purchased` — a credit pack purchase completed and its credits were granted */
+interface FFIDCreditsPackPurchasedPayload extends FFIDCreditsEventBase {
+    operationId: string;
+    grantId: string;
+    packCode: string;
+    /** Credits granted in total (pack credits × `quantity`) */
+    credits: number;
+    quantity: number;
+    /** Amount paid (tax-inclusive, smallest currency unit) */
+    amount: number;
+    currency: string;
+    expiresAt: string;
+    /** User who bought the pack */
+    purchasedBy: string;
+}
+
 /**
  * FFID Webhook SDK Type Definitions
  *
@@ -47,7 +115,7 @@ declare class FFIDWebhookPayloadError extends FFIDWebhookError {
  */
 
 /** All supported webhook event types */
-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';
+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' | 'credits.granted' | 'credits.low' | 'credits.exhausted' | 'credits.pack_purchased' | 'test.ping';
 interface FFIDSubscriptionCreatedPayload {
     subscriptionId: string;
     organizationId?: string;
@@ -64,12 +132,27 @@ interface FFIDSubscriptionCreatedPayload {
      */
     serviceCode?: string;
 }
+/**
+ * `subscription.updated`.
+ *
+ * 9.0.0 aligned this type with what FFID sends (#6380): `status` is always present, and
+ * `subscriptionId` / `organizationId` are absent when the event comes from a Stripe notice
+ * whose subscription FFID could not match to its own record (check before use).
+ * `previousPlan` was removed — FFID never sent it.
+ */
 interface FFIDSubscriptionUpdatedPayload {
-    subscriptionId: string;
+    /**
+     * Subscription status after the change — the raw status string (FFID's or Stripe's), not a
+     * closed enum. Use `effectiveStatus` for access decisions.
+     */
+    status: string;
+    /** FFID subscription UUID. Absent when FFID could not match the Stripe subscription */
+    subscriptionId?: string;
+    /** Stripe subscription id (`sub_...`). Present on events that come from Stripe notices */
+    stripeSubscriptionId?: string;
     organizationId?: string;
+    /** Plan code after the change */
     plan?: string;
-    previousPlan?: string;
-    status?: string;
     effectiveStatus?: EffectiveSubscriptionStatus;
     gracePeriodEndsAt?: string | null;
     /**
@@ -242,9 +325,27 @@ interface FFIDSubscriptionDowngradeCanceledPayload {
      */
     serviceCode?: string;
 }
+/**
+ * `subscription.trial_ending` — sent when Stripe announces that a trial is about to end.
+ *
+ * 9.0.0 aligned this type with what FFID sends (#6380). FFID does not resolve its own
+ * subscription UUID for this event; identify the subscription by `stripeSubscriptionId`
+ * (and the service by `serviceCode`).
+ */
 interface FFIDSubscriptionTrialEndingPayload {
-    subscriptionId: string;
-    organizationId?: string;
+    /** Stripe subscription id (`sub_...`) */
+    stripeSubscriptionId: string;
+    /**
+     * Days until the trial ends, rounded **up** at the moment FFID processed Stripe's notice
+     * (a trial ending later the same day is `1`). `0` only when the trial had already ended by
+     * then. Fixed when the event is created — a redelivered event carries the same value.
+     */
+    daysRemaining: number;
+    /**
+     * Trial end date **for display**, in Japanese long form in JST (e.g. `2026年10月3日`) — not
+     * an ISO timestamp. `(無効な日時)` when FFID could not read Stripe's timestamp. Use
+     * `daysRemaining` for any calculation.
+     */
     trialEndDate: string;
     /**
      * Code of the service the subscription belongs to (e.g. `chatbot-v2`), resolved by FFID when
@@ -420,6 +521,10 @@ interface FFIDWebhookEventMap {
     'system.maintenance.started': FFIDSystemMaintenancePayload;
     'system.maintenance.completed': FFIDSystemMaintenancePayload;
     'announcement.published': FFIDAnnouncementPublishedPayload;
+    'credits.granted': FFIDCreditsGrantedPayload;
+    'credits.low': FFIDCreditsLowPayload;
+    'credits.exhausted': FFIDCreditsExhaustedPayload;
+    'credits.pack_purchased': FFIDCreditsPackPurchasedPayload;
     'test.ping': FFIDTestPingPayload;
 }
 /** A webhook event envelope with typed payload */
@@ -545,4 +650,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 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 };
+export { DEFAULT_TOLERANCE_SECONDS, type FFIDAnnouncementPublishedPayload, type FFIDCreditsExhaustedPayload, type FFIDCreditsGrantedPayload, type FFIDCreditsLowPayload, type FFIDCreditsPackPurchasedPayload, 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,131 +1,131 @@
-{
-  "name": "@feelflow/ffid-sdk",
-  "version": "8.1.0",
-  "description": "FeelFlow ID Platform SDK for React/Next.js applications",
-  "keywords": [
-    "feelflow",
-    "ffid",
-    "sdk",
-    "react",
-    "nextjs",
-    "authentication"
-  ],
-  "author": "FeelFlow <dev@feelflow.net>",
-  "license": "MIT",
-  "homepage": "https://github.com/feel-flow/feelflow-id-platform/tree/develop/sdk/typescript#readme",
-  "bugs": {
-    "url": "https://github.com/feel-flow/feelflow-id-platform/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/feel-flow/feelflow-id-platform.git",
-    "directory": "sdk/typescript"
-  },
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./components": {
-      "types": "./dist/components/index.d.ts",
-      "import": "./dist/components/index.js",
-      "require": "./dist/components/index.cjs"
-    },
-    "./consent": {
-      "types": "./dist/consent/index.d.ts",
-      "import": "./dist/consent/index.js",
-      "require": "./dist/consent/index.cjs"
-    },
-    "./legal": {
-      "types": "./dist/legal/index.d.ts",
-      "import": "./dist/legal/index.js",
-      "require": "./dist/legal/index.cjs"
-    },
-    "./webhooks": {
-      "types": "./dist/webhooks/index.d.ts",
-      "import": "./dist/webhooks/index.js",
-      "require": "./dist/webhooks/index.cjs"
-    },
-    "./announcements": {
-      "types": "./dist/announcements/index.d.ts",
-      "import": "./dist/announcements/index.js",
-      "require": "./dist/announcements/index.cjs"
-    },
-    "./agency": {
-      "types": "./dist/agency/index.d.ts",
-      "import": "./dist/agency/index.js",
-      "require": "./dist/agency/index.cjs"
-    },
-    "./server": {
-      "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": [
-    "dist",
-    "README.md"
-  ],
-  "sideEffects": false,
-  "scripts": {
-    "build": "rimraf dist && tsup",
-    "dev": "tsup --watch",
-    "type-check": "tsc --noEmit",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "prepublishOnly": "npm run build",
-    "sdk:publish": "./scripts/publish.sh"
-  },
-  "dependencies": {
-    "jose": "^6.0.0",
-    "zod": "^4.4.3"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    },
-    "react-dom": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@testing-library/jest-dom": "^6.0.0",
-    "@testing-library/react": "^16.0.0",
-    "@types/node": "^22.19.17",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.58.0",
-    "@typescript-eslint/parser": "^8.58.0",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "jsdom": "^27.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "rimraf": "^6.1.2",
-    "tsup": "^8.0.0",
-    "typescript": "^5.0.0",
-    "vitest": "^4.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@feelflow/ffid-sdk",
+  "version": "10.0.0",
+  "description": "FeelFlow ID Platform SDK for React/Next.js applications",
+  "keywords": [
+    "feelflow",
+    "ffid",
+    "sdk",
+    "react",
+    "nextjs",
+    "authentication"
+  ],
+  "author": "FeelFlow <dev@feelflow.net>",
+  "license": "MIT",
+  "homepage": "https://github.com/feel-flow/feelflow-id-platform/tree/develop/sdk/typescript#readme",
+  "bugs": {
+    "url": "https://github.com/feel-flow/feelflow-id-platform/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/feel-flow/feelflow-id-platform.git",
+    "directory": "sdk/typescript"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js",
+      "require": "./dist/components/index.cjs"
+    },
+    "./consent": {
+      "types": "./dist/consent/index.d.ts",
+      "import": "./dist/consent/index.js",
+      "require": "./dist/consent/index.cjs"
+    },
+    "./legal": {
+      "types": "./dist/legal/index.d.ts",
+      "import": "./dist/legal/index.js",
+      "require": "./dist/legal/index.cjs"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks/index.d.ts",
+      "import": "./dist/webhooks/index.js",
+      "require": "./dist/webhooks/index.cjs"
+    },
+    "./announcements": {
+      "types": "./dist/announcements/index.d.ts",
+      "import": "./dist/announcements/index.js",
+      "require": "./dist/announcements/index.cjs"
+    },
+    "./agency": {
+      "types": "./dist/agency/index.d.ts",
+      "import": "./dist/agency/index.js",
+      "require": "./dist/agency/index.cjs"
+    },
+    "./server": {
+      "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": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rimraf dist && tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build",
+    "sdk:publish": "./scripts/publish.sh"
+  },
+  "dependencies": {
+    "jose": "^6.0.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.0.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^22.19.17",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "jsdom": "^27.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "rimraf": "^6.1.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}