@feelflow/ffid-sdk 9.0.0 → 10.1.0

package/dist/{index-BG7g99pK.d.cts → index-CWGoIgYL.d.cts}

@@ -126,6 +126,781 @@ declare const EFFECTIVE_SUBSCRIPTION_STATUSES: readonly ["active", "active_cance
  */
 type EffectiveSubscriptionStatus = (typeof EFFECTIVE_SUBSCRIPTION_STATUSES)[number];
 
+/** Billing interval for subscriptions */
+type FFIDBillingInterval = 'monthly' | 'yearly';
+/**
+ * Supported currencies for billing responses.
+ * Mirrors the platform's `SupportedCurrency` enum (`jpy` = zero-decimal Japanese Yen, `usd` = US Dollar).
+ */
+type FFIDSupportedCurrency = 'jpy' | 'usd';
+/** Service information returned by plans endpoint */
+interface FFIDServiceInfo {
+    id: string;
+    code: string;
+    name: string;
+    description: string | null;
+    isActive: boolean;
+    createdAt: string;
+    plans: FFIDPlanInfo[];
+}
+/** Plan information returned by plans endpoint */
+interface FFIDPlanInfo {
+    id: string;
+    serviceId: string;
+    code: string;
+    name: string;
+    description: string | null;
+    minSeats: number;
+    maxSeats: number | null;
+    seatSelectionEnabled: boolean;
+    trialDays: number;
+    /** flat: period fee; per_seat: multiply by selected quantity. Older servers omit this. */
+    pricingModel?: 'per_seat' | 'flat';
+    /**
+     * flat: member limit of the plan (`null` = unlimited). Absent on per_seat plans
+     * and on FFID servers released before #6392 — do not read absence as unlimited.
+     */
+    maxMembers?: number | null;
+    /** flat: monthly AI credit allowance (0 = none). Absent on older servers. */
+    monthlyCredits?: number;
+    /** Plan tier in the personal / team / enterprise ladder. Absent on older servers. */
+    tier?: 'personal' | 'team' | 'enterprise';
+    /**
+     * Monthly price in the smallest currency unit.
+     *
+     * `null` when the plan is not self-serve priced. Once the FFID #4482 rollout
+     * is enabled, `customPricing: true` (Enterprise / "contact us") plans return
+     * `null` here — branch on `customPricing` to render an inquiry CTA rather than
+     * a price. Standard plans always return a number.
+     */
+    priceMonthly: number | null;
+    priceYearly: number | null;
+    currency: string;
+    isActive: boolean;
+    displayOrder: number;
+    customPricing: boolean;
+    createdAt: string;
+}
+/** Response from list plans endpoint */
+interface FFIDListPlansResponse {
+    services: FFIDServiceInfo[];
+    count: number;
+}
+/** Subscription details returned by ext API (sanitized, no Stripe IDs) */
+interface FFIDSubscriptionDetail {
+    id: string;
+    organizationId: string;
+    organizationName: string;
+    serviceCode: string;
+    serviceName: string;
+    planCode: string;
+    planName: string;
+    status: FFIDSubscriptionStatus;
+    paymentMethod: string | null;
+    billingInterval: FFIDBillingInterval;
+    quantity: number;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    trialStart: string | null;
+    trialEnd: string | null;
+    canceledAt: string | null;
+    /**
+     * `true` while a cancellation is reserved until the period end. `status` stays
+     * `active` until then; the subscription becomes `canceled` at `currentPeriodEnd`.
+     * The reservation can only be withdrawn in the FFID portal (there is no SDK method).
+     */
+    cancelAtPeriodEnd: boolean;
+    /**
+     * Change reserved until the period end (null = nothing reserved).
+     *
+     * Every decrease — a lower plan, paid → free, fewer seats, yearly → monthly — is
+     * reserved instead of applied immediately (FFID #6327). The current plan, seats and
+     * interval stay in effect until `scheduledAt`. Withdraw it with `cancelPendingDowngrade()`.
+     */
+    pendingDowngrade: {
+        /** Plan in effect after the period end. Equals `planCode` for a seat-only or interval-only reservation. */
+        planCode: string;
+        planName: string;
+        /** Billing interval in effect after the period end */
+        billingInterval: FFIDBillingInterval;
+        /**
+         * Seat count in effect after the period end. `null` = the seat count does not change.
+         * Seat reductions are made in the FFID portal; this lets you show them (8.0.0).
+         * FFID servers released before #6327 omit it, so compare with `== null` at runtime.
+         */
+        quantity: number | null;
+        scheduledAt: string;
+        requestedAt: string;
+    } | null;
+    createdAt: string;
+}
+/** Parameters for subscribing to a plan */
+interface FFIDSubscribeParams {
+    /** Organization ID (UUID) */
+    organizationId: string;
+    /** Plan code (e.g., 'free', 'basic', 'pro') */
+    planCode: string;
+    /** Billing interval (default: 'monthly') */
+    billingInterval?: FFIDBillingInterval;
+    /**
+     * Number of seats (default: plan's minSeats). per_seat plans only — a flat plan
+     * answers 400 `VALIDATION_ERROR` (`details.field: 'quantity'`), so omit it there.
+     */
+    quantity?: number;
+    /** User ID for seat auto-assignment (only needed for service-key mode) */
+    userId?: string;
+}
+/** Sanitized subscription fields returned by subscribe/reactivate endpoints (no Stripe IDs) */
+interface FFIDSubscriptionSummary {
+    id: string;
+    organizationId: string;
+    serviceId: string;
+    planId: string;
+    status: FFIDSubscriptionStatus;
+    paymentMethod: string | null;
+    billingInterval: FFIDBillingInterval;
+    quantity: number;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    trialStart: string | null;
+    trialEnd: string | null;
+    canceledAt: string | null;
+    cancelAtPeriodEnd: boolean;
+    createdAt: string;
+}
+/** Response from subscribe endpoint */
+interface FFIDSubscribeResponse {
+    subscription: FFIDSubscriptionSummary;
+    service: {
+        id: string;
+        code: string;
+        name: string;
+    };
+    plan: {
+        id: string;
+        code: string;
+        name: string;
+        priceMonthly: number;
+        priceYearly: number | null;
+        trialDays: number;
+    };
+    /** True if a canceled subscription was reactivated */
+    reactivated?: boolean;
+    /** True if Stripe checkout is needed (canceled paid plan reactivation) */
+    needsCheckout?: boolean;
+}
+/** Parameters for changing plan */
+interface FFIDChangePlanParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New plan code */
+    planCode: string;
+    /** New billing interval (default: keeps current) */
+    billingInterval?: FFIDBillingInterval;
+}
+/**
+ * Response from change plan endpoint.
+ *
+ * - An increase (higher plan / monthly → yearly) applies immediately and the difference up to
+ *   the current period end is charged now. `pendingDowngrade` is absent.
+ * - A decrease (lower plan / paid → free / yearly → monthly) is reserved until the period end:
+ *   `pendingDowngrade` is present and `subscription.planCode` is still the current plan.
+ *   Nothing is charged or refunded. A contract that cannot be reserved still changes
+ *   immediately, without a refund: one with no period end, or a paid → paid decrease on a
+ *   contract without a Stripe subscription.
+ */
+interface FFIDChangePlanResponse {
+    message: string;
+    subscription: {
+        id: string;
+        organizationId: string;
+        serviceCode: string;
+        planCode: string;
+        planName: string;
+        billingInterval: FFIDBillingInterval;
+        status: FFIDSubscriptionStatus;
+        isUpgrade: boolean;
+    };
+    /** Present when the change is a decrease reserved until the period end */
+    pendingDowngrade?: {
+        planCode: string;
+        planName: string;
+        scheduledAt: string;
+    };
+}
+/** Parameters for canceling subscription */
+interface FFIDCancelSubscriptionParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** Cancellation reason code */
+    reason?: 'too_expensive' | 'missing_features' | 'switched_service' | 'rarely_used' | 'customer_service' | 'other';
+    /** Additional cancellation details */
+    reasonDetails?: string;
+}
+/**
+ * Response from cancel subscription endpoint.
+ *
+ * Since 8.0.0 a contract billed through Stripe is **reserved** for cancellation at the period
+ * end (FFID #6327): `status` stays `active`, `cancelAtPeriodEnd` is `true` and `cancelAt` is the
+ * period end. Access continues until then and nothing is refunded. A contract that cannot be
+ * reserved (no Stripe subscription, no period end yet, or Stripe not configured on FFID) is
+ * canceled immediately (`status: 'canceled'`, `cancelAtPeriodEnd: false`, `cancelAt: null`).
+ * Branch on `cancelAtPeriodEnd`, not on whether the contract uses Stripe.
+ *
+ * Do not treat this response as "access revoked". The `subscription.canceled` webhook arrives
+ * at reservation (`source: 'user_initiated'`) and again at the period end
+ * (`source: 'stripe_confirmed'`); see `FFIDSubscriptionCanceledPayload`.
+ */
+interface FFIDCancelSubscriptionResponse {
+    message: string;
+    subscription: {
+        id: string;
+        organizationId: string;
+        /** `active` while the cancellation is reserved; `canceled` only for an immediate cancellation */
+        status: FFIDSubscriptionStatus;
+        canceledAt: string | null;
+        /** `true` when the cancellation is reserved until the period end */
+        cancelAtPeriodEnd: boolean;
+        /** When the reserved cancellation takes effect (the period end). `null` for an immediate cancellation */
+        cancelAt: string | null;
+    };
+}
+/**
+ * Response from cancel pending downgrade endpoint.
+ *
+ * Withdraws the reserved change on the Stripe side as well, so the current plan, seats and
+ * interval simply continue after the period end. It does not withdraw a reserved
+ * cancellation — that is done in the FFID portal.
+ */
+interface FFIDCancelPendingDowngradeResponse {
+    message: string;
+    subscription: {
+        id: string;
+        organizationId: string;
+        serviceCode: string;
+        planCode: string;
+        billingInterval: FFIDBillingInterval;
+        status: FFIDSubscriptionStatus;
+        /** Always null after successful cancellation */
+        pendingDowngradePlanId: null;
+    };
+}
+/** Parameters for previewing plan change */
+interface FFIDPreviewPlanChangeParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New plan code */
+    planCode: string;
+    /** New billing interval (default: keeps current) */
+    billingInterval?: FFIDBillingInterval;
+}
+/** Plan change preview line item */
+interface FFIDPlanChangeLineItem {
+    description: string;
+    amount: number;
+}
+/** Fields shared by every plan-change preview variant (internal; consumers use `FFIDPlanChangePreview`) */
+interface FFIDPlanChangePreviewBase {
+    /** Discriminant for preview response variants (reserved for future unions with e.g. seat-change previews) */
+    type: 'plan-change';
+    /** Current plan display info. `price` is the period total: flat fee, or per-seat price times quantity. */
+    currentPlan: {
+        name: string;
+        price: number;
+    };
+    /** New plan display info. `price` is the period total: flat fee, or per-seat price times quantity. */
+    newPlan: {
+        name: string;
+        price: number;
+    };
+    billingInterval: FFIDBillingInterval;
+    isUpgrade: boolean;
+    /** Full amount of the next billing cycle at the new plan's standard price. Never overwritten by Stripe proration data. */
+    nextInvoiceAmount: number;
+    nextInvoiceDate: string | null;
+    currency: FFIDSupportedCurrency;
+    /** true when amounts are estimated from local prices (no Stripe proration data) */
+    isEstimate: boolean;
+    /** Reason why `isEstimate` is true. Only meaningful when `isEstimate === true`. */
+    estimateReason?: 'no_stripe_data' | 'custom_pricing' | 'stripe_error';
+    lineItems: FFIDPlanChangeLineItem[];
+}
+/**
+ * Plan change proration preview. It is computed with the same rules as `changePlan()`.
+ *
+ * `willApplyAtPeriodEnd` is a discriminant that constrains related fields at the type level:
+ * - `true`: a decrease reserved until the period end. `proratedAmount` is always 0 (nothing is
+ *   charged or refunded now); `effectiveDate` mirrors the subscription's `currentPeriodEnd`
+ *   (may be `null` when the subscription has no active billing cycle yet).
+ * - `false`: immediate change. `effectiveDate` is always `null`. For an increase,
+ *   `proratedAmount` is the difference up to the current period end that is charged now
+ *   (possibly Stripe-refined). A decrease on a contract that cannot be reserved also lands here:
+ *   `0` for a contract without a Stripe subscription (no refund), but Stripe's prorated amount —
+ *   negative, credited on the next invoice — for a Stripe contract with no period end yet
+ *   (e.g. during a trial).
+ */
+type FFIDPlanChangePreview = FFIDPlanChangePreviewBase & ({
+    willApplyAtPeriodEnd: true;
+    effectiveDate: string | null;
+    /** 0 on period-end-deferred changes; charge happens at the next invoice */
+    proratedAmount: 0;
+} | {
+    willApplyAtPeriodEnd: false;
+    effectiveDate: null;
+    /** Difference up to the current period end charged now (see the type doc for the decrease cases) */
+    proratedAmount: number;
+});
+/** Response from plan change preview endpoint */
+interface FFIDPlanChangePreviewResponse {
+    preview: FFIDPlanChangePreview;
+}
+/** Parameters for previewing a seat count change */
+interface FFIDPreviewSeatChangeParams {
+    /** Subscription ID (UUID) */
+    subscriptionId: string;
+    /** New seat quantity. Must be an integer within the plan's allowed range. */
+    quantity: number;
+}
+/** Seat change preview line item */
+interface FFIDSeatChangeLineItem {
+    description: string;
+    amount: number;
+}
+/**
+ * Seat change proration preview.
+ *
+ * Sister type to `FFIDPlanChangePreview`. The shared `type` discriminant lets
+ * consumers narrow a preview payload without inspecting unrelated fields.
+ *
+ * - `willApplyAtPeriodEnd=true`: a seat reduction reserved until the period end.
+ *   `proratedAmount` is 0 and `effectiveDate` is when the new seat count applies.
+ * - Otherwise the change applies immediately. For an increase, `proratedAmount` is the amount
+ *   charged now up to the current period end. A reduction that cannot be reserved is normally
+ *   `0`, but can be negative (a credit on the next invoice) for a Stripe contract with no period
+ *   end yet or when only the contract unit price is known.
+ * - `isEstimate=true` (default when Stripe is not configured or data is unavailable):
+ *   `proratedAmount` is computed locally. `isEstimate=false`: it reflects Stripe's live
+ *   proration calculation.
+ *
+ * `nextInvoiceAmount` is a local estimate: flat period fee, or `unitPrice * newQuantity`.
+ * Flat capacity changes have zero prorated cost.
+ *
+ * `pricingUnavailable=true` means custom pricing or an unverified contracted Stripe
+ * Price. Hide amounts; zero is not a quote. `custom_pricing` permits the existing
+ * unbilled seat-change flow. Require another preview before confirmation only when
+ * pricing is unavailable and the reason is not `custom_pricing`. `stripe_error` also
+ * covers invoice/address failures after the contract price is known; use
+ * `pricingUnavailable`, not the reason alone, to decide whether to hide amounts.
+ * `no_stripe_data` means invoice proration is unavailable even if the contract unit
+ * price is known. Portal seat PUT independently enforces subscription limits;
+ * external consumers should guide users to the FFID portal for seat changes.
+ */
+interface FFIDSeatChangePreview {
+    /** flat: unitPrice is the whole period fee; per_seat: multiply by capacity. */
+    pricingModel?: 'per_seat' | 'flat';
+    /** Discriminant for preview response variants (pairs with `FFIDPlanChangePreview.type`) */
+    type: 'seat-change';
+    currentQuantity: number;
+    newQuantity: number;
+    /** Per-seat price for the current billing interval */
+    unitPrice: number;
+    billingInterval: FFIDBillingInterval;
+    /**
+     * Amount charged now for the rest of the current billing period. A reserved seat reduction
+     * (`willApplyAtPeriodEnd: true`) is always `0`; see the type doc for reductions that cannot
+     * be reserved. Also `0` when `pricingUnavailable === true`; hide it instead of quoting zero.
+     */
+    proratedAmount: number;
+    /** Next invoice full amount — flat period fee or per-seat price times newQuantity */
+    nextInvoiceAmount: number;
+    nextInvoiceDate: string | null;
+    currency: FFIDSupportedCurrency;
+    /** true when proratedAmount is a local estimate rather than Stripe invoice/proration data */
+    isEstimate: boolean;
+    /** Hide amounts: custom pricing or contracted Stripe Price could not be verified. */
+    pricingUnavailable?: boolean;
+    /** Reason why `isEstimate` is true. Only meaningful when `isEstimate === true`. */
+    estimateReason?: 'no_stripe_data' | 'custom_pricing' | 'stripe_error';
+    /**
+     * `true` when the seat reduction would be reserved until the period end (8.0.0).
+     * Absent or `false` = the change applies immediately.
+     */
+    willApplyAtPeriodEnd?: boolean;
+    /** When the reserved seat count applies (present when `willApplyAtPeriodEnd` is `true`) */
+    effectiveDate?: string | null;
+    lineItems: FFIDSeatChangeLineItem[];
+}
+/** Response from seat change preview endpoint */
+interface FFIDSeatChangePreviewResponse {
+    preview: FFIDSeatChangePreview;
+}
+
+/** Deployment environments a catalog publication can apply to (single source) */
+declare const FFID_CATALOG_ENVIRONMENTS: readonly ["staging", "production"];
+/** Deployment environment a catalog publication applies to */
+type FFIDCatalogEnvironment = (typeof FFID_CATALOG_ENVIRONMENTS)[number];
+/**
+ * Tax behavior of a published price.
+ * `inclusive`: displayed price contains Stripe-calculated tax.
+ * `exclusive`: tax is added on top of the base price.
+ */
+type FFIDTaxBehavior = 'inclusive' | 'exclusive';
+/**
+ * Publication lifecycle statuses (single source — the type, the SDK runtime
+ * validator, and consumer sets all derive from this tuple so a new literal
+ * cannot be added to one side only).
+ */
+declare const FFID_CATALOG_PUBLICATION_STATUSES: readonly ["approved", "superseded", "revoking", "revoked"];
+/**
+ * Publication lifecycle status.
+ * - `approved`: sellable — the only status that permits new paid checkout
+ * - `superseded`: replaced by a newer revision (old sessions may sell through
+ *   until `sellThroughUntil`)
+ * - `revoking`: emergency stop in progress — never sellable
+ * - `revoked`: emergency stop completed — never sellable
+ */
+type FFIDCatalogPublicationStatus = (typeof FFID_CATALOG_PUBLICATION_STATUSES)[number];
+/**
+ * Human-approved publication record binding a catalog revision to the
+ * content/config hashes reviewed at approval time.
+ *
+ * All `*Hash` fields are lowercase SHA-256 hex computed with the shared
+ * canonicalization helpers in `shared/catalog-hash` — consumers re-hash the
+ * content they actually render and must refuse new sales on any mismatch.
+ */
+interface FFIDCatalogPublication {
+    serviceCode: string;
+    environment: FFIDCatalogEnvironment;
+    catalogVersion: string;
+    praxisCopyHash: string;
+    ffidCheckoutCopyHash: string;
+    legalDisclosureHash: string;
+    taxConfigurationHash: string;
+    paymentConfigurationHash: string;
+    scopeHash: string;
+    /** Monotonically increasing per (service, environment) publication counter */
+    salesEpoch: number;
+    /** FFID-generated immutable human-review approval ID */
+    approvalId: string;
+    /** ISO 8601 timestamp of the recorded human review */
+    reviewedAt: string;
+    /** ISO 8601 timestamp the publication became effective */
+    effectiveAt: string;
+    /** ISO 8601 timestamp the publication was superseded (null while current) */
+    supersededAt: string | null;
+    /** ISO 8601 upper bound for old-session sell-through (null unless superseded) */
+    sellThroughUntil: string | null;
+    /** ISO 8601 timestamp an emergency revoke took effect (null unless revoking/revoked) */
+    revocationEffectiveAt: string | null;
+    status: FFIDCatalogPublicationStatus;
+}
+/**
+ * A plan inside a published catalog revision (public-safe snapshot).
+ * Never contains Stripe Product/Price identifiers or other secrets.
+ */
+interface FFIDPublishedPlan {
+    /**
+     * Plan code — always a lowercase slug (`^[a-z0-9][a-z0-9_-]*$`).
+     * Per-service open set; see the FFID repo's
+     * `docs/04-api/PLAN_CODE_CONTRACT.md` for the full guarantees.
+     */
+    code: string;
+    name: string;
+    description: string | null;
+    /** Monthly price in the catalog currency; null when monthly is not offered */
+    priceMonthly: number | null;
+    /** Yearly price in the catalog currency; null when yearly is not offered */
+    priceYearly: number | null;
+    currency: string;
+    /** Billing intervals actually purchasable for this plan */
+    billingIntervals: FFIDBillingInterval[];
+    taxBehavior: FFIDTaxBehavior;
+    minSeats: number;
+    maxSeats: number | null;
+    displayOrder: number;
+    /** Billing model (10.0.0). Absent on snapshots published before ADR-008 (e.g. praxis) */
+    pricingModel?: 'per_seat' | 'flat';
+    /** flat: member limit (`null` = unlimited). Absent on older snapshots */
+    maxMembers?: number | null;
+    /** flat: monthly AI credit allowance (0 = none). Absent on older snapshots */
+    monthlyCredits?: number;
+    /** Plan tier. Absent on older snapshots */
+    tier?: 'personal' | 'team' | 'enterprise';
+}
+/**
+ * Response of GET /api/v1/subscriptions/ext/catalog/{serviceCode}.
+ *
+ * `catalogVersion` always equals `publication.catalogVersion`; it is hoisted
+ * to the top level so consumers can pin the version (e.g. as
+ * `expectedCatalogVersion` for checkout) without digging into the publication.
+ */
+interface FFIDPublishedCatalog {
+    service: {
+        code: string;
+        name: string;
+    };
+    catalogVersion: string;
+    publication: FFIDCatalogPublication;
+    plans: FFIDPublishedPlan[];
+}
+
+/**
+ * Credits API types (SDK 10.0.0 / FFID #6395, CREDITS_API.md v1.3.1).
+ *
+ * `pricing_model='flat'` plans (fixed fee + member limit + monthly AI credits)
+ * keep a credit ledger in FFID. These types mirror the FFID server's response
+ * shapes exactly; the FFID repository type-checks them against the server types
+ * (`src/lib/credits/__tests__/sdk-credits-types.sync.test.ts`), so a field changed
+ * on one side only fails FFID's gate.
+ *
+ * Kept out of `types/index.ts` (file-size limit). Exported directly from the
+ * package entry.
+ */
+
+/** Low-balance threshold, in percent of `monthlyCredits` (`credits.low`, `isLow`) */
+declare const FFID_CREDITS_LOW_THRESHOLD_PERCENT = 20;
+/** Smallest `amount` a single `consume` accepts (credits) */
+declare const FFID_CREDITS_CONSUME_MIN_AMOUNT = 1;
+/** Largest `amount` a single `consume` accepts (credits) */
+declare const FFID_CREDITS_CONSUME_MAX_AMOUNT = 1000000;
+/** Max size of `consume` `metadata`, in UTF-8 bytes after `JSON.stringify` */
+declare const FFID_CREDITS_METADATA_MAX_BYTES = 4096;
+/** Smallest `limit` for credit history (items per page) */
+declare const FFID_CREDITS_HISTORY_MIN_LIMIT = 1;
+/** Largest `limit` for credit history (items per page) */
+declare const FFID_CREDITS_HISTORY_MAX_LIMIT = 100;
+/** Server default `limit` for credit history when omitted (items per page) */
+declare const FFID_CREDITS_HISTORY_DEFAULT_LIMIT = 20;
+/** Smallest number of packs per purchase */
+declare const FFID_CREDIT_PACK_MIN_QUANTITY = 1;
+/** Largest number of packs per purchase */
+declare const FFID_CREDIT_PACK_MAX_QUANTITY = 10;
+/**
+ * Format of the `consume` idempotency key (CREDITS_API §7).
+ * Recommended form: `feature:requestId` (e.g. `chat.reply:req_01HZX`).
+ */
+declare const FFID_CREDITS_IDEMPOTENCY_KEY_PATTERN: RegExp;
+/** Format of the `consume` `feature` identifier (CREDITS_API §3) */
+declare const FFID_CREDITS_FEATURE_PATTERN: RegExp;
+/** Values of the history `type` filter / item `type` */
+declare const FFID_CREDIT_HISTORY_TYPES: readonly ["grant", "consumption", "revocation"];
+/** Kinds of credit grant */
+declare const FFID_CREDIT_GRANT_KINDS: readonly ["monthly", "manual", "pack"];
+/**
+ * Billing model of a plan. `flat` = fixed fee + member limit + monthly credits;
+ * `per_seat` = seat billing (praxis). Do not infer it from `planCode`.
+ */
+type FFIDPricingModel = 'per_seat' | 'flat';
+/** History item / filter type */
+type FFIDCreditHistoryType = (typeof FFID_CREDIT_HISTORY_TYPES)[number];
+/** Grant kind: monthly allowance, operator grant, or purchased pack */
+type FFIDCreditGrantKind = (typeof FFID_CREDIT_GRANT_KINDS)[number];
+/** Remaining credits per grant kind */
+interface FFIDCreditBreakdown {
+    monthly: number;
+    manual: number;
+    pack: number;
+}
+/** `GET /ext/{id}/credits/balance` (CREDITS_API §4.2) */
+interface FFIDCreditBalance {
+    subscriptionId: string;
+    organizationId: string;
+    serviceCode: string;
+    pricingModel: 'flat';
+    /** Credits usable now (sum of active grants' remaining) */
+    available: number;
+    /** This period's monthly allowance */
+    monthlyCredits: number;
+    /** Current monthly window; null when there is no monthly grant this period */
+    period: {
+        start: string;
+        end: string;
+    } | null;
+    breakdown: FFIDCreditBreakdown;
+    /** Next manual / pack expiry; null when none is active */
+    nextExpiry: {
+        at: string;
+        amount: number;
+    } | null;
+    lowThresholdPercent: number;
+    /** `available < monthlyCredits * lowThresholdPercent / 100` (always false when monthlyCredits = 0) */
+    isLow: boolean;
+    /** `available === 0` */
+    isExhausted: boolean;
+    /** ISO 8601 time the balance was read */
+    asOf: string;
+}
+/** `POST /ext/{id}/credits/consume` 200 response (CREDITS_API §4.1) */
+interface FFIDCreditConsumeResult {
+    /**
+     * `duplicate` = same idempotency key and amount was already consumed. No side
+     * effect; `consumptionId` / `amount` are the first call's, `balance` is current,
+     * and `crossedLow` / `crossedExhausted` are always false.
+     */
+    status: 'consumed' | 'duplicate';
+    consumptionId: string;
+    amount: number;
+    balance: {
+        available: number;
+        monthlyCredits: number;
+        breakdown: FFIDCreditBreakdown;
+    };
+    /** This consumption crossed the low-balance threshold (once per period) */
+    crossedLow: boolean;
+    /** This consumption brought the balance to 0 (once per period) */
+    crossedExhausted: boolean;
+}
+/** `details` of a `CREDITS_INSUFFICIENT` (409) error from `consume` */
+interface FFIDCreditsInsufficientDetails {
+    requested: number;
+    available: number;
+    monthlyCredits: number;
+    /** End of the current period (ISO 8601); null only when FFID could not read it */
+    periodEnd: string | null;
+}
+/** One row of the credit history (CREDITS_API §4.3) */
+interface FFIDCreditHistoryItem {
+    /** Grant / consumption id. For `revocation` this is the revoked grant's id */
+    id: string;
+    type: FFIDCreditHistoryType;
+    /** Always positive; the direction is given by `type` */
+    amount: number;
+    occurredAt: string;
+    /** Set for `grant` / `revocation` */
+    kind: FFIDCreditGrantKind | null;
+    expiresAt: string | null;
+    /** Set for `consumption` */
+    feature: string | null;
+    /** Set for `consumption` */
+    idempotencyKey: string | null;
+    actorUserId: string | null;
+    reason: string | null;
+    metadata: Record<string, unknown> | null;
+}
+/** `GET /ext/{id}/credits/history` (newest first) */
+interface FFIDCreditHistoryPage {
+    items: FFIDCreditHistoryItem[];
+    /** Opaque cursor for the next page; null on the last page */
+    nextCursor: string | null;
+}
+/** One purchasable credit pack (CREDITS_API §4.4) */
+interface FFIDCreditPack {
+    code: string;
+    name: string;
+    credits: number;
+    /** Tax-inclusive price in the smallest currency unit */
+    price: number;
+    currency: string;
+    taxBehavior: FFIDTaxBehavior;
+    validityMonths: number;
+    displayOrder: number;
+}
+/** `GET /ext/credits/packs` */
+interface FFIDCreditPackList {
+    serviceCode: string;
+    packs: FFIDCreditPack[];
+}
+/**
+ * `POST /ext/credits/packs/checkout` (CREDITS_API §4.5). Credits are **not**
+ * granted yet when this returns — confirm with `credits.pack_purchased` /
+ * `credits.granted` or the balance.
+ */
+interface FFIDCreditPackCheckout {
+    checkoutUrl: string;
+    sessionId: string;
+    operationId: string;
+    /** ISO 8601 */
+    expiresAt: string;
+}
+/**
+ * `credits` field added to `/ext/check` (CREDITS_API §5.1). Null for per_seat,
+ * for no subscription, **and** when FFID could not read the ledger — so null
+ * does not mean "not flat"; use `pricingModel`.
+ */
+interface FFIDSubscriptionCheckCredits {
+    available: number;
+    monthlyCredits: number;
+    isLow: boolean;
+    isExhausted: boolean;
+    periodEnd: string | null;
+}
+/**
+ * `GET /ext/{id}/seats` (CREDITS_API §5.2).
+ *
+ * flat contracts report the member limit: `maxMembers` (null = unlimited),
+ * `assignedMembers`, `availableMembers` (null = unlimited); `quantity` /
+ * `minSeats` / `maxSeats` are always 1 and `availableSeats === availableMembers`.
+ * per_seat contracts keep the seat shape and only add `pricingModel`.
+ * FFID servers released before #6392 omit `pricingModel` and the member fields.
+ */
+interface FFIDSeatsSummary {
+    subscriptionId: string;
+    organizationId: string;
+    pricingModel?: FFIDPricingModel;
+    quantity: number;
+    assignedSeats: number;
+    availableSeats: number | null;
+    minSeats: number;
+    maxSeats: number | null;
+    maxMembers?: number | null;
+    assignedMembers?: number;
+    availableMembers?: number | null;
+}
+/** Input of `client.credits.consume()` (service-key mode only) */
+interface FFIDCreditConsumeParams {
+    /** Contract id: UUID, `ffid:<uuid>` or Stripe `sub_...` */
+    subscriptionId: string;
+    /** Integer, `FFID_CREDITS_CONSUME_MIN_AMOUNT`..`FFID_CREDITS_CONSUME_MAX_AMOUNT` */
+    amount: number;
+    /**
+     * One key per AI execution, reused on retry (`FFID_CREDITS_IDEMPOTENCY_KEY_PATTERN`).
+     * Recommended: `${feature}:${requestId}`.
+     */
+    idempotencyKey: string;
+    /** Service-side feature identifier (`FFID_CREDITS_FEATURE_PATTERN`) */
+    feature: string;
+    /**
+     * Aggregation values only (model name, token counts). **No personal data** —
+     * consumption rows are accounting records and survive user deletion.
+     * JSON object, at most `FFID_CREDITS_METADATA_MAX_BYTES` bytes.
+     */
+    metadata?: Record<string, unknown>;
+    /** End user who ran the AI (UUID). Recorded for audit only */
+    userId?: string;
+}
+/** Options of `client.credits.listHistory()` */
+interface FFIDListCreditHistoryOptions {
+    /** `nextCursor` of the previous page */
+    cursor?: string;
+    /** `FFID_CREDITS_HISTORY_MIN_LIMIT`..`FFID_CREDITS_HISTORY_MAX_LIMIT` (server default 20) */
+    limit?: number;
+    /** Filter by type; omitted = all */
+    type?: FFIDCreditHistoryType;
+}
+/** Input of `client.credits.createPackCheckout()` (token mode only) */
+interface FFIDCreatePackCheckoutParams {
+    /** Contract id: UUID, `ffid:<uuid>` or Stripe `sub_...` */
+    subscriptionId: string;
+    /** `code` from `listPacks()` */
+    packCode: string;
+    /** https URL to return to after payment */
+    successUrl: string;
+    /** https URL to return to on cancel */
+    cancelUrl: string;
+    /** `FFID_CREDIT_PACK_MIN_QUANTITY`..`FFID_CREDIT_PACK_MAX_QUANTITY` (server default 1) */
+    quantity?: number;
+}
+/** Input of `client.credits.getBuyCreditsUrl()` / `redirectToBuyCredits()` */
+interface FFIDBuyCreditsUrlParams {
+    /**
+     * Contract id as a UUID or `ffid:<uuid>`. The FFID portal page takes the UUID
+     * form only, so a Stripe `sub_...` id is rejected with `VALIDATION_ERROR`.
+     */
+    subscriptionId: string;
+    /** Organization ID — passed as `?org=` so FFID selects that organization */
+    orgId?: string;
+}
+
 /**
  * Canonical service-access types for subscription lifecycle decisions.
  */
@@ -163,9 +938,37 @@ interface FFIDSubscriptionCheckResponse {
     gracePeriodEndsAt?: string | null;
     /** Whether a canceled subscription can be resumed via a re-subscription flow. */
     reactivatable?: boolean;
+    /**
+     * Billing model of the subscription's plan (10.0.0; CREDITS_API §5.1). `null` when
+     * there is no subscription. FFID servers released before #6390 omit it.
+     */
+    pricingModel?: FFIDPricingModel | null;
+    /**
+     * Credit balance summary — flat plans only (10.0.0). `null` for per_seat, for no
+     * subscription, **and** when FFID could not read the ledger, so `null` does not
+     * mean "not flat" (use `pricingModel`). Never affects `hasAccess`.
+     */
+    credits?: FFIDSubscriptionCheckCredits | null;
+    /**
+     * The plan's member limit is full (10.0.0). Informational: `hasAccess` is not
+     * affected. A user who cannot get a seat because of it is refused at login with
+     * OAuth `denial_reason: 'member_limit_reached'`.
+     */
+    memberLimitReached?: boolean;
 }
 type FFIDServiceAccessFailPolicy = 'failClosed';
-type FFIDServiceAccessDenialReason = 'no_subscription' | 'grace_disallowed' | 'blocked' | 'canceled' | 'expired' | 'trial_expired' | 'ffid_unreachable';
+/**
+ * Why access was denied.
+ *
+ * `member_limit_reached` (10.0.0) is FFID's denial reason when a flat plan's member
+ * limit is full and the user has no seat. It reaches you through OAuth
+ * (`denial_reason` on the authorize redirect / userinfo 403; see
+ * `FFIDOAuthDenialReason` for that vocabulary); `checkServiceAccess()`
+ * derives its decision from `effectiveStatus` and never returns it, because a full
+ * member limit does not change `hasAccess` (CREDITS_API §1-5). It is in this union so
+ * one exhaustive `switch` over denial reasons covers both paths.
+ */
+type FFIDServiceAccessDenialReason = 'no_subscription' | 'grace_disallowed' | 'blocked' | 'canceled' | 'expired' | 'trial_expired' | 'ffid_unreachable' | 'member_limit_reached';
 interface FFIDCheckServiceAccessParams {
     userId?: string;
     organizationId: string;
@@ -204,6 +1007,15 @@ interface FFIDServiceAccessDecision {
     currentPeriodEnd: string | null;
     gracePeriodEndsAt: string | null;
     reactivatable: boolean;
+    /** Passed through from `/ext/check` when the server sends it (10.0.0). Informational. */
+    pricingModel?: FFIDPricingModel | null;
+    /**
+     * Passed through from `/ext/check` (10.0.0). Gate AI features on this or on
+     * `credits.consume`'s result — not on `hasAccess`.
+     */
+    credits?: FFIDSubscriptionCheckCredits | null;
+    /** Passed through from `/ext/check` (10.0.0). Does not affect `hasAccess`. */
+    memberLimitReached?: boolean;
     /**
      * Present when the decision was produced by the SDK fail-closed policy
      * rather than by a successful FFID response.
@@ -1597,4 +2409,4 @@ interface FFIDInquiryFormPlaceholderContext {
 }
 declare function FFIDInquiryForm({ mode, prefill, organizations, preselectedOrganizationId, categories, termsVersion, privacyVersion, termsHref, privacyHref, turnstileToken, acquisitionSource, turnstileSlot, onSubmit, onChange, legalLayout, messagePlaceholder, requireCategorySelection, unstyled, classNames, locale, className, }: FFIDInquiryFormProps): react_jsx_runtime.JSX.Element;
 
-export { type FFIDInquiryFormProps as $, type AnnouncementListResponse as A, type Announcement as B, type AnnouncementStatus as C, type AnnouncementType as D, type EffectiveSubscriptionStatus as E, type FFIDSubscriptionStatus as F, EFFECTIVE_SUBSCRIPTION_STATUSES as G, FFIDAnnouncementBadge as H, FFIDAnnouncementList as I, type FFIDAnnouncementsError as J, type FFIDAnnouncementsErrorCode as K, type ListAnnouncementsOptions as L, type FFIDAnnouncementsServerResponse as M, type FFIDApiResponseMeta as N, type FFIDCacheConfig as O, type FFIDContextValue as P, type FFIDInquiryAcquisitionSource as Q, type FFIDInquiryCategory as R, type FFIDInquiryCategorySite2026 as S, type TokenStore as T, FFIDInquiryForm as U, type FFIDInquiryFormCategoryItem as V, type FFIDInquiryFormClassNames as W, type FFIDInquiryFormLegalLayout as X, type FFIDInquiryFormOrganization as Y, type FFIDInquiryFormPlaceholderContext as Z, type FFIDInquiryFormPrefill as _, type FFIDOAuthUserInfoSubscription as a, type FFIDInquiryFormSubmitData as a0, type FFIDInquiryFormSubmitResult as a1, type FFIDJwtClaims as a2, FFIDLoginButton as a3, type FFIDOAuthUserInfoMemberRole as a4, FFIDOrganizationSwitcher as a5, type FFIDSeatAssignmentClaim as a6, type FFIDSeatAssignmentStatus as a7, type FFIDSeatModel as a8, type FFIDServiceAccessDenialReason as a9, type FFIDServiceAccessFailPolicy as aa, FFIDSubscriptionBadge as ab, FFIDUserMenu as ac, FFID_INQUIRY_ACQUISITION_SOURCES as ad, FFID_INQUIRY_CATEGORIES as ae, FFID_INQUIRY_CATEGORIES_SITE_2026 as af, type TokenData as ag, type UseFFIDAnnouncementsOptions as ah, type UseFFIDAnnouncementsReturn as ai, createTokenStore as aj, isFFIDInquiryAcquisitionSource as ak, isFFIDInquiryCategorySite2026 as al, useFFIDAnnouncements as am, type FFIDAnnouncementBadgeClassNames as an, type FFIDAnnouncementBadgeProps as ao, type FFIDAnnouncementListClassNames as ap, type FFIDAnnouncementListProps as aq, type FFIDLoginButtonProps as ar, type FFIDOrganizationSwitcherClassNames as as, type FFIDOrganizationSwitcherProps as at, type FFIDSubscriptionBadgeClassNames as au, type FFIDSubscriptionBadgeProps as av, type FFIDUserMenuClassNames as aw, type FFIDUserMenuProps as ax, type FFIDAccountType as b, type FFIDPrompt as c, type FFIDConfig as d, type FFIDApiResponse as e, type FFIDSessionResponse as f, type FFIDSignOutResult as g, type FFIDError as h, type FFIDSubscriptionCheckResponse as i, type FFIDCheckServiceAccessParams as j, type FFIDServiceAccessDecision as k, type FFIDAnalyticsConfig as l, type FFIDVerifyAccessTokenOptions as m, type FFIDOAuthUserInfo as n, type FFIDInquiryCreateParams as o, type FFIDInquiryCreateResponse as p, type FFIDAuthMode as q, type FFIDLogger as r, type FFIDCacheAdapter as s, type FFIDUser as t, type FFIDOrganization as u, type FFIDSubscription as v, type FFIDSubscriptionContextValue as w, type FFIDAnnouncementsClientConfig as x, type FFIDAnnouncementsApiResponse as y, type FFIDAnnouncementsLogger as z };
+export { type FFIDAnnouncementsClientConfig as $, type FFIDVerifyAccessTokenOptions as A, type FFIDOAuthUserInfo as B, type FFIDInquiryCreateParams as C, type FFIDInquiryCreateResponse as D, type FFIDCreditBalance as E, type FFIDOAuthUserInfoSubscription as F, type FFIDListCreditHistoryOptions as G, type FFIDCreditHistoryPage as H, type FFIDCreditPackList as I, type FFIDCreatePackCheckoutParams as J, type FFIDCreditPackCheckout as K, type FFIDCreditConsumeParams as L, type FFIDCreditConsumeResult as M, type FFIDBuyCreditsUrlParams as N, type FFIDAuthMode as O, type FFIDLogger as P, type FFIDCacheAdapter as Q, type FFIDUser as R, type FFIDOrganization as S, type TokenStore as T, type FFIDSubscription as U, type FFIDSubscriptionContextValue as V, type EffectiveSubscriptionStatus as W, type FFIDSubscriptionStatus as X, type FFIDCatalogEnvironment as Y, type FFIDBillingInterval as Z, type FFIDTaxBehavior as _, type FFIDAccountType as a, FFID_CREDITS_FEATURE_PATTERN as a$, type ListAnnouncementsOptions as a0, type FFIDAnnouncementsApiResponse as a1, type AnnouncementListResponse as a2, type FFIDAnnouncementsLogger as a3, type Announcement as a4, type AnnouncementStatus as a5, type AnnouncementType as a6, EFFECTIVE_SUBSCRIPTION_STATUSES as a7, FFIDAnnouncementBadge as a8, FFIDAnnouncementList as a9, type FFIDInquiryFormSubmitResult as aA, type FFIDJwtClaims as aB, FFIDLoginButton as aC, type FFIDOAuthUserInfoMemberRole as aD, FFIDOrganizationSwitcher as aE, type FFIDPlanChangeLineItem as aF, type FFIDPlanChangePreview as aG, type FFIDPlanInfo as aH, type FFIDPricingModel as aI, type FFIDPublishedPlan as aJ, type FFIDSeatAssignmentClaim as aK, type FFIDSeatAssignmentStatus as aL, type FFIDSeatChangeLineItem as aM, type FFIDSeatChangePreview as aN, type FFIDSeatModel as aO, type FFIDServiceAccessDenialReason as aP, type FFIDServiceAccessFailPolicy as aQ, type FFIDServiceInfo as aR, FFIDSubscriptionBadge as aS, type FFIDSubscriptionCheckCredits as aT, type FFIDSubscriptionSummary as aU, type FFIDSupportedCurrency as aV, FFIDUserMenu as aW, FFID_CATALOG_ENVIRONMENTS as aX, FFID_CATALOG_PUBLICATION_STATUSES as aY, FFID_CREDITS_CONSUME_MAX_AMOUNT as aZ, FFID_CREDITS_CONSUME_MIN_AMOUNT as a_, type FFIDAnnouncementsError as aa, type FFIDAnnouncementsErrorCode as ab, type FFIDAnnouncementsServerResponse as ac, type FFIDApiResponseMeta as ad, type FFIDCacheConfig as ae, type FFIDCatalogPublication as af, type FFIDCatalogPublicationStatus as ag, type FFIDContextValue as ah, type FFIDCreditBreakdown as ai, type FFIDCreditGrantKind as aj, type FFIDCreditHistoryItem as ak, type FFIDCreditHistoryType as al, type FFIDCreditPack as am, type FFIDCreditsInsufficientDetails as an, type FFIDInquiryAcquisitionSource as ao, type FFIDInquiryCategory as ap, type FFIDInquiryCategorySite2026 as aq, FFIDInquiryForm as ar, type FFIDInquiryFormCategoryItem as as, type FFIDInquiryFormClassNames as at, type FFIDInquiryFormLegalLayout as au, type FFIDInquiryFormOrganization as av, type FFIDInquiryFormPlaceholderContext as aw, type FFIDInquiryFormPrefill as ax, type FFIDInquiryFormProps as ay, type FFIDInquiryFormSubmitData as az, type FFIDPrompt as b, FFID_CREDITS_HISTORY_DEFAULT_LIMIT as b0, FFID_CREDITS_HISTORY_MAX_LIMIT as b1, FFID_CREDITS_HISTORY_MIN_LIMIT as b2, FFID_CREDITS_IDEMPOTENCY_KEY_PATTERN as b3, FFID_CREDITS_LOW_THRESHOLD_PERCENT as b4, FFID_CREDITS_METADATA_MAX_BYTES as b5, FFID_CREDIT_GRANT_KINDS as b6, FFID_CREDIT_HISTORY_TYPES as b7, FFID_CREDIT_PACK_MAX_QUANTITY as b8, FFID_CREDIT_PACK_MIN_QUANTITY as b9, FFID_INQUIRY_ACQUISITION_SOURCES as ba, FFID_INQUIRY_CATEGORIES as bb, FFID_INQUIRY_CATEGORIES_SITE_2026 as bc, type TokenData as bd, type UseFFIDAnnouncementsOptions as be, type UseFFIDAnnouncementsReturn as bf, createTokenStore as bg, isFFIDInquiryAcquisitionSource as bh, isFFIDInquiryCategorySite2026 as bi, useFFIDAnnouncements as bj, type FFIDAnnouncementBadgeClassNames as bk, type FFIDAnnouncementBadgeProps as bl, type FFIDAnnouncementListClassNames as bm, type FFIDAnnouncementListProps as bn, type FFIDLoginButtonProps as bo, type FFIDOrganizationSwitcherClassNames as bp, type FFIDOrganizationSwitcherProps as bq, type FFIDSubscriptionBadgeClassNames as br, type FFIDSubscriptionBadgeProps as bs, type FFIDUserMenuClassNames as bt, type FFIDUserMenuProps as bu, type FFIDConfig as c, type FFIDApiResponse as d, type FFIDSessionResponse as e, type FFIDSignOutResult as f, type FFIDError as g, type FFIDSubscriptionCheckResponse as h, type FFIDCheckServiceAccessParams as i, type FFIDServiceAccessDecision as j, type FFIDAnalyticsConfig as k, type FFIDSeatsSummary as l, type FFIDListPlansResponse as m, type FFIDPublishedCatalog as n, type FFIDSubscriptionDetail as o, type FFIDSubscribeParams as p, type FFIDSubscribeResponse as q, type FFIDChangePlanParams as r, type FFIDChangePlanResponse as s, type FFIDCancelSubscriptionParams as t, type FFIDCancelSubscriptionResponse as u, type FFIDCancelPendingDowngradeResponse as v, type FFIDPreviewPlanChangeParams as w, type FFIDPlanChangePreviewResponse as x, type FFIDPreviewSeatChangeParams as y, type FFIDSeatChangePreviewResponse as z };