@feelflow/ffid-sdk 9.0.0 → 10.0.0

package/dist/server/index.js

@@ -1370,7 +1370,7 @@ var FFID_ORGANIZATION_PROFILE_ERROR_CODES = {
 };
 
 // src/client/version-check.ts
-var SDK_VERSION = "9.0.0";
+var SDK_VERSION = "10.0.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1726,8 +1726,11 @@ function createProvisioningMethods(deps) {
 }
 
 // src/client/seat-methods.ts
+function seatSummaryEndpoint(subscriptionId) {
+  return `/api/v1/subscriptions/ext/${encodeURIComponent(subscriptionId)}/seats`;
+}
 function seatsEndpoint(subscriptionId) {
-  return `/api/v1/subscriptions/ext/${encodeURIComponent(subscriptionId)}/seats/assignments`;
+  return `${seatSummaryEndpoint(subscriptionId)}/assignments`;
 }
 function createSeatMethods(deps) {
   const { fetchWithAuth, createError } = deps;
@@ -1737,6 +1740,12 @@ function createSeatMethods(deps) {
     }
     return fetchWithAuth(seatsEndpoint(params.subscriptionId));
   }
+  async function getSeats(subscriptionId) {
+    if (!subscriptionId || !subscriptionId.trim()) {
+      return { error: createError("VALIDATION_ERROR", "subscriptionId \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    return fetchWithAuth(seatSummaryEndpoint(subscriptionId));
+  }
   async function assignSeats(params) {
     if (!params.subscriptionId) {
       return { error: createError("VALIDATION_ERROR", "subscriptionId \u306F\u5FC5\u9808\u3067\u3059") };
@@ -1761,7 +1770,7 @@ function createSeatMethods(deps) {
       { method: "DELETE" }
     );
   }
-  return { listSeatAssignments, assignSeats, unassignSeat };
+  return { listSeatAssignments, getSeats, assignSeats, unassignSeat };
 }
 
 // src/client/profile-methods.ts
@@ -3488,6 +3497,222 @@ function createInquiryMethods(deps) {
   return { create };
 }
 
+// src/types/credits.ts
+var FFID_CREDITS_CONSUME_MIN_AMOUNT = 1;
+var FFID_CREDITS_CONSUME_MAX_AMOUNT = 1e6;
+var FFID_CREDITS_METADATA_MAX_BYTES = 4096;
+var FFID_CREDITS_HISTORY_MIN_LIMIT = 1;
+var FFID_CREDITS_HISTORY_MAX_LIMIT = 100;
+var FFID_CREDIT_PACK_MIN_QUANTITY = 1;
+var FFID_CREDIT_PACK_MAX_QUANTITY = 10;
+var FFID_CREDITS_IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9._:-]{8,128}$/;
+var FFID_CREDITS_FEATURE_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+var FFID_CREDIT_HISTORY_TYPES = ["grant", "consumption", "revocation"];
+
+// src/client/credits-methods.ts
+var EXT_SUBSCRIPTIONS_PATH = "/api/v1/subscriptions/ext";
+var CREDIT_PACKS_ENDPOINT = `${EXT_SUBSCRIPTIONS_PATH}/credits/packs`;
+var CREDIT_PACK_CHECKOUT_ENDPOINT = `${CREDIT_PACKS_ENDPOINT}/checkout`;
+var PORTAL_SUBSCRIPTION_PATH = "/subscriptions";
+var BUY_CREDITS_QUERY = { key: "purchase", value: "credits" };
+var ORG_QUERY_KEY = "org";
+var FFID_CONTRACT_ID_PREFIX = "ffid:";
+var STRIPE_SUBSCRIPTION_ID_PREFIX = "sub_";
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var VALIDATION_ERROR = "VALIDATION_ERROR";
+var FORBIDDEN = "FORBIDDEN";
+var utf8Encoder = new TextEncoder();
+function creditsEndpoint(subscriptionId, action) {
+  return `${EXT_SUBSCRIPTIONS_PATH}/${encodeURIComponent(subscriptionId)}/credits/${action}`;
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isIntegerInRange(value, min, max) {
+  return typeof value === "number" && Number.isInteger(value) && value >= min && value <= max;
+}
+function createCreditsMethods(deps) {
+  const { fetchWithAuth, createError, authMode, baseUrl, serviceCode, logger } = deps;
+  function validationError(field, message) {
+    return { error: { ...createError(VALIDATION_ERROR, message), details: { field } } };
+  }
+  function forbidden(reason, message) {
+    return { error: { ...createError(FORBIDDEN, message), details: { reason } } };
+  }
+  function missingSubscriptionId(subscriptionId) {
+    return subscriptionId && subscriptionId.trim() ? null : validationError("subscriptionId", "subscriptionId \u306F\u5FC5\u9808\u3067\u3059");
+  }
+  async function getBalance(subscriptionId) {
+    const invalid = missingSubscriptionId(subscriptionId);
+    if (invalid) return invalid;
+    return fetchWithAuth(creditsEndpoint(subscriptionId, "balance"));
+  }
+  async function listHistory(subscriptionId, options = {}) {
+    const invalid = missingSubscriptionId(subscriptionId);
+    if (invalid) return invalid;
+    const query = new URLSearchParams();
+    if (options.cursor !== void 0) query.set("cursor", options.cursor);
+    if (options.limit !== void 0) {
+      if (!isIntegerInRange(options.limit, FFID_CREDITS_HISTORY_MIN_LIMIT, FFID_CREDITS_HISTORY_MAX_LIMIT)) {
+        return validationError(
+          "limit",
+          `limit \u306F ${FFID_CREDITS_HISTORY_MIN_LIMIT}\u301C${FFID_CREDITS_HISTORY_MAX_LIMIT} \u306E\u6574\u6570\u3067\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044`
+        );
+      }
+      query.set("limit", String(options.limit));
+    }
+    if (options.type !== void 0) {
+      if (!FFID_CREDIT_HISTORY_TYPES.includes(options.type)) {
+        return validationError("type", `type \u306F ${FFID_CREDIT_HISTORY_TYPES.join(" / ")} \u306E\u3044\u305A\u308C\u304B\u3067\u3059`);
+      }
+      query.set("type", options.type);
+    }
+    const qs = query.toString();
+    return fetchWithAuth(
+      `${creditsEndpoint(subscriptionId, "history")}${qs ? `?${qs}` : ""}`
+    );
+  }
+  async function listPacks(packServiceCode) {
+    const resolved = packServiceCode ?? (authMode === "service-key" ? void 0 : serviceCode);
+    if (resolved !== void 0 && !resolved.trim()) {
+      return validationError("serviceCode", "serviceCode \u3092\u6307\u5B9A\u3059\u308B\u5834\u5408\u3001\u7A7A\u6587\u5B57\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093");
+    }
+    const qs = resolved === void 0 ? "" : `?${new URLSearchParams({ serviceCode: resolved }).toString()}`;
+    return fetchWithAuth(`${CREDIT_PACKS_ENDPOINT}${qs}`);
+  }
+  async function createPackCheckout(params) {
+    if (authMode !== "token") {
+      return forbidden(
+        "bearer_required",
+        "createPackCheckout \u306F token \u30E2\u30FC\u30C9\uFF08Bearer\uFF09\u3067\u306E\u307F\u5229\u7528\u3067\u304D\u307E\u3059\u3002\u8CFC\u5165\u8005\u306E\u8A18\u9332\u306B\u5B9F\u30E6\u30FC\u30B6\u30FC\u304C\u5FC5\u8981\u306A\u305F\u3081\u3067\u3059"
+      );
+    }
+    const invalid = missingSubscriptionId(params.subscriptionId);
+    if (invalid) return invalid;
+    for (const field of ["packCode", "successUrl", "cancelUrl"]) {
+      if (!params[field] || !params[field].trim()) {
+        return validationError(field, `${field} \u306F\u5FC5\u9808\u3067\u3059`);
+      }
+    }
+    if (params.quantity !== void 0 && !isIntegerInRange(params.quantity, FFID_CREDIT_PACK_MIN_QUANTITY, FFID_CREDIT_PACK_MAX_QUANTITY)) {
+      return validationError(
+        "quantity",
+        `quantity \u306F ${FFID_CREDIT_PACK_MIN_QUANTITY}\u301C${FFID_CREDIT_PACK_MAX_QUANTITY} \u306E\u6574\u6570\u3067\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044`
+      );
+    }
+    const body = {
+      subscriptionId: params.subscriptionId,
+      packCode: params.packCode,
+      successUrl: params.successUrl,
+      cancelUrl: params.cancelUrl
+    };
+    if (params.quantity !== void 0) body.quantity = params.quantity;
+    return fetchWithAuth(CREDIT_PACK_CHECKOUT_ENDPOINT, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  function validateConsume(params) {
+    const invalid = missingSubscriptionId(params.subscriptionId);
+    if (invalid) return invalid;
+    if (!isIntegerInRange(params.amount, FFID_CREDITS_CONSUME_MIN_AMOUNT, FFID_CREDITS_CONSUME_MAX_AMOUNT)) {
+      return validationError(
+        "amount",
+        `amount \u306F ${FFID_CREDITS_CONSUME_MIN_AMOUNT}\u301C${FFID_CREDITS_CONSUME_MAX_AMOUNT} \u306E\u6574\u6570\u3067\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044`
+      );
+    }
+    if (typeof params.idempotencyKey !== "string" || !FFID_CREDITS_IDEMPOTENCY_KEY_PATTERN.test(params.idempotencyKey)) {
+      return validationError(
+        "idempotencyKey",
+        "idempotencyKey \u306E\u5F62\u5F0F\u304C\u4E0D\u6B63\u3067\u3059\uFF08\u82F1\u6570\u5B57\u3068 . _ : - \u306E 8\u301C128 \u6587\u5B57\u3002\u63A8\u5968\u306F feature:requestId\uFF09"
+      );
+    }
+    if (typeof params.feature !== "string" || !FFID_CREDITS_FEATURE_PATTERN.test(params.feature)) {
+      return validationError("feature", "feature \u306E\u5F62\u5F0F\u304C\u4E0D\u6B63\u3067\u3059\uFF08\u5C0F\u6587\u5B57\u82F1\u6570\u5B57\u3067\u59CB\u307E\u308B\u3001\u5C0F\u6587\u5B57\u82F1\u6570\u5B57\u3068 . _ - \u306E 1\u301C64 \u6587\u5B57\uFF09");
+    }
+    if (params.metadata !== void 0) {
+      if (!isPlainObject2(params.metadata)) {
+        return validationError("metadata", "metadata \u306F JSON \u30AA\u30D6\u30B8\u30A7\u30AF\u30C8\u3067\u3042\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059");
+      }
+      let serialized;
+      try {
+        serialized = JSON.stringify(params.metadata);
+      } catch {
+        return validationError("metadata", "metadata \u306F JSON \u306B\u5909\u63DB\u3067\u304D\u308B\u5024\u3067\u3042\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059\uFF08BigInt\u30FB\u5FAA\u74B0\u53C2\u7167\u306F\u4E0D\u53EF\uFF09");
+      }
+      if (utf8Encoder.encode(serialized).byteLength > FFID_CREDITS_METADATA_MAX_BYTES) {
+        return validationError("metadata", `metadata \u306F ${FFID_CREDITS_METADATA_MAX_BYTES} \u30D0\u30A4\u30C8\u4EE5\u4E0B\u3067\u3042\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059`);
+      }
+    }
+    if (params.userId !== void 0 && !UUID_PATTERN.test(params.userId)) {
+      return validationError("userId", "userId \u306F\u6709\u52B9\u306AUUID\u5F62\u5F0F\u3067\u3042\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059");
+    }
+    return null;
+  }
+  async function consume(params) {
+    if (authMode !== "service-key") {
+      return forbidden(
+        "api_key_required",
+        "credits.consume \u306F service-key \u8A8D\u8A3C\uFF08X-Service-Api-Key\uFF09\u3067\u306E\u307F\u5229\u7528\u3067\u304D\u307E\u3059\u3002\u6D88\u8CBB\u306E\u5831\u544A\u306F\u30B5\u30FC\u30D3\u30B9\u306E\u30D0\u30C3\u30AF\u30A8\u30F3\u30C9\u304B\u3089\u884C\u3063\u3066\u304F\u3060\u3055\u3044"
+      );
+    }
+    const invalid = validateConsume(params);
+    if (invalid) return invalid;
+    const body = {
+      amount: params.amount,
+      idempotencyKey: params.idempotencyKey,
+      feature: params.feature
+    };
+    if (params.metadata !== void 0) body.metadata = params.metadata;
+    if (params.userId !== void 0) body.userId = params.userId;
+    return fetchWithAuth(creditsEndpoint(params.subscriptionId, "consume"), {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  function getBuyCreditsUrl(params) {
+    const raw = params.subscriptionId?.trim() ?? "";
+    if (raw.startsWith(STRIPE_SUBSCRIPTION_ID_PREFIX)) {
+      return validationError(
+        "subscriptionId",
+        "getBuyCreditsUrl \u306B\u306F\u5951\u7D04\u306E UUID\uFF08\u307E\u305F\u306F ffid:<uuid>\uFF09\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044\u3002Stripe \u306E sub_... \u306F\u4F7F\u3048\u307E\u305B\u3093"
+      );
+    }
+    const uuid = raw.startsWith(FFID_CONTRACT_ID_PREFIX) ? raw.slice(FFID_CONTRACT_ID_PREFIX.length) : raw;
+    if (!UUID_PATTERN.test(uuid)) {
+      return validationError("subscriptionId", "subscriptionId \u306F\u5951\u7D04\u306E UUID\uFF08\u307E\u305F\u306F ffid:<uuid>\uFF09\u3067\u3042\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059");
+    }
+    const query = new URLSearchParams({ [BUY_CREDITS_QUERY.key]: BUY_CREDITS_QUERY.value });
+    if (params.orgId !== void 0 && params.orgId.trim()) {
+      query.set(ORG_QUERY_KEY, params.orgId);
+    }
+    return { data: `${baseUrl}${PORTAL_SUBSCRIPTION_PATH}/${encodeURIComponent(uuid)}?${query.toString()}` };
+  }
+  function redirectToBuyCredits(params) {
+    const result = getBuyCreditsUrl(params);
+    if (result.error) {
+      logger.warn("redirectToBuyCredits:", result.error.message);
+      return { success: false, error: result.error.message };
+    }
+    if (typeof window === "undefined") {
+      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" };
+    }
+    logger.debug("Redirecting to buy credits:", result.data);
+    window.location.href = result.data;
+    return { success: true };
+  }
+  return {
+    getBalance,
+    listHistory,
+    listPacks,
+    createPackCheckout,
+    consume,
+    getBuyCreditsUrl,
+    redirectToBuyCredits
+  };
+}
+
 // src/subscriptions/userinfo-helpers.ts
 var ACCESS_GRANTING_EFFECTIVE_STATUSES = [
   "active",
@@ -3546,7 +3771,12 @@ function toServiceAccessDecision(response, allowGrace) {
     planCode: response.planCode,
     currentPeriodEnd: response.currentPeriodEnd,
     gracePeriodEndsAt: response.gracePeriodEndsAt ?? null,
-    reactivatable: response.reactivatable ?? false
+    reactivatable: response.reactivatable ?? false,
+    // Informational pass-through (10.0.0). Deliberately not part of hasAccess /
+    // denialReason: credits and the member limit never gate access (CREDITS_API §1-5).
+    ...response.pricingModel !== void 0 ? { pricingModel: response.pricingModel } : {},
+    ...response.credits !== void 0 ? { credits: response.credits } : {},
+    ...response.memberLimitReached !== void 0 ? { memberLimitReached: response.memberLimitReached } : {}
   };
 }
 function failClosedServiceAccessDecision(params, error) {
@@ -3908,7 +4138,7 @@ function createFFIDClient(config) {
     fetchWithAuth,
     createError
   });
-  const { listSeatAssignments, assignSeats, unassignSeat } = createSeatMethods({
+  const { listSeatAssignments, getSeats, assignSeats, unassignSeat } = createSeatMethods({
     fetchWithAuth,
     createError
   });
@@ -4015,6 +4245,14 @@ function createFFIDClient(config) {
     fetchWithAuth,
     createError
   });
+  const credits = createCreditsMethods({
+    fetchWithAuth,
+    createError,
+    authMode,
+    baseUrl,
+    serviceCode: config.serviceCode,
+    logger
+  });
   const verifyAccessToken = createVerifyAccessToken({
     authMode,
     baseUrl,
@@ -4070,6 +4308,7 @@ function createFFIDClient(config) {
     getInvoice,
     retryPayment,
     listSeatAssignments,
+    getSeats,
     assignSeats,
     unassignSeat,
     listPlans,
@@ -4080,13 +4319,16 @@ function createFFIDClient(config) {
     cancelSubscription,
     cancelPendingDowngrade,
     previewPlanChange,
+    /** @deprecated 10.0.0: per_seat (praxis) only; removed in 11.0.0 */
     previewSeatChange,
     verifyAccessToken,
     getSubscribeUrl,
     redirectToSubscribe,
     getChangePlanUrl,
     redirectToChangePlan,
+    /** @deprecated 10.0.0: per_seat (praxis) only; removed in 11.0.0 */
     getChangeSeatsUrl,
+    /** @deprecated 10.0.0: per_seat (praxis) only; removed in 11.0.0 */
     redirectToChangeSeats,
     getRecoverPaymentUrl,
     redirectToRecoverPayment,
@@ -4102,6 +4344,8 @@ function createFFIDClient(config) {
     newsletter,
     /** Inquiry methods (create) */
     inquiry,
+    /** Credits methods for flat plans (consume / balance / history / packs) */
+    credits,
     /** Token store (token mode only) */
     tokenStore,
     /**

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

@@ -1,4 +1,4 @@
-import { r as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-6aLs9Fqc.cjs';
+import { r as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-CumygXXz.cjs';
 import '../../types-Cjb9J0rL.cjs';
 
 /**

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

@@ -1,4 +1,4 @@
-import { r as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-B0cORHac.js';
+import { r as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-5uxXRgIO.js';
 import '../../types-Cjb9J0rL.js';
 
 /**

package/dist/webhooks/index.d.cts

@@ -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;
@@ -453,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 */
@@ -578,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/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;
@@ -453,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 */
@@ -578,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 };