@schematichq/schematic-typescript-node 1.6.0 → 1.6.2

package/dist/api/types/PlanVersionMigrationResponseData.d.ts

@@ -5,6 +5,8 @@ export interface PlanVersionMigrationResponseData {
     createdAt: Date;
     error?: string;
     failedCompanies: number;
+    featureId?: string;
+    featurePlanRolloutId?: string;
     id: string;
     nextDueAt?: Date;
     planId: string;

package/dist/api/types/UpdateBillingPlanCreditGrantRequestBody.d.ts

@@ -3,7 +3,7 @@ export interface UpdateBillingPlanCreditGrantRequestBody {
     applyToExisting?: boolean;
     /** Which boundary closes a monthly arrears window: the subscription's own recurrence (billing_period_start) or the calendar month (month_end). Only applies when arrears_cadence is monthly; defaults to billing_period_start. Send null to fall back to the default. */
     arrearsAnchor?: Schematic.BillingArrearsAnchor;
-    /** How often postpaid charges are closed and invoiced: end_of_billing_period (the default) or monthly. Send null to fall back to the default. */
+    /** How often postpaid charges are closed and invoiced: end_of_billing_period (the default) or monthly. Quarterly is not available for postpaid charges. Send null to fall back to the default. */
     arrearsCadence?: Schematic.BillingArrearsCadence;
     autoTopupAmount?: number;
     autoTopupAmountType?: Schematic.CreditAutoTopupAmountType;
@@ -15,6 +15,8 @@ export interface UpdateBillingPlanCreditGrantRequestBody {
     autoTopupSelfService?: boolean;
     autoTopupThresholdCredits?: number;
     autoTopupThresholdPercent?: number;
+    /** Whether the credits are included in the plan price (granted) or billed as their own subscription line at a price per credit (billed). Billed is only available on custom plans. */
+    billingMode?: Schematic.BillingPlanCreditGrantBillingMode;
     /** Deprecated: use compatible_plan_ids on credit bundles instead. Still accepted; writes through to the credit's bundle compatibility. */
     canBuyBundles?: boolean;
     /** Credits granted once per company on top of the per-license amount. Only valid when the grant scales per license. */
@@ -33,6 +35,8 @@ export interface UpdateBillingPlanCreditGrantRequestBody {
     postpaidRatePerUnit?: number;
     /** Decimal string form of postpaid_rate_per_unit, for rates finer than one minor unit (for example 0.0002). Takes precedence over postpaid_rate_per_unit when both are set, matching how the credit's own price_per_unit_decimal behaves. Send null to clear it. */
     postpaidRatePerUnitDecimal?: string;
+    /** Tier table pricing the credits on this grant, cheapest bound first, the last tier unbounded. Sending it moves the grant off one rate per credit. Requires tier_mode. */
+    priceTiers?: Schematic.CreditGrantPriceTierRequestBody[];
     resetCadence: Schematic.BillingPlanCreditGrantResetCadence;
     resetStart: Schematic.BillingPlanCreditGrantResetStart;
     resetType?: Schematic.BillingPlanCreditGrantResetType;
@@ -40,4 +44,10 @@ export interface UpdateBillingPlanCreditGrantRequestBody {
     rolloverPercentage?: number;
     /** Whether the grant is a fixed amount per company, or issued once per license the company holds. Changing this re-issues the credits companies already hold for this grant. */
     scaling?: Schematic.PlanCreditGrantScaling;
+    /** How price_tiers apply: volume prices every credit at the rate of the tier the total lands in, graduated prices each tier's own credits at its own rate. Required with price_tiers. */
+    tierMode?: Schematic.BillingTiersMode;
+    /** Price per credit in the plan currency's smallest unit. Required when billing_mode is billed, unless unit_price_decimal or price_tiers is set. Sending it moves a tiered grant back to one rate per credit. */
+    unitPrice?: number;
+    /** Price per credit as a decimal in the plan currency's smallest unit, for prices below one cent. */
+    unitPriceDecimal?: string;
 }

package/dist/api/types/UsageBasedEntitlementRequestBody.d.ts

@@ -8,7 +8,11 @@ export interface UsageBasedEntitlementRequestBody {
     monthlyPriceTiers?: Schematic.CreatePriceTierRequestBody[];
     monthlyUnitPrice?: number;
     monthlyUnitPriceDecimal?: string;
+    /** How often overage charges are assessed and invoiced. Defaults to end_of_billing_period, where the billing provider aggregates usage over the subscription's own period and bills it at period end. Set to monthly or quarterly to have overage assessed each month or quarter and billed on its own invoice, which is the point of the setting on annual plans. A quarter charges each month's usage against that month's allowance. Only applies to overage price behavior. */
+    overageBillingCadence?: Schematic.BillingArrearsCadence;
     overageBillingProductId?: string;
+    /** Which boundary closes a monthly or quarterly overage window: the subscription's own recurrence (billing_period_start) or the calendar month (month_end). Quarterly windows run in three-month blocks from the billing period start, held to the subscription's own period, or in calendar quarters at month_end. Only applies when overage_billing_cadence is monthly or quarterly, and must match metric_period_month_reset so each window closes when the allowance resets: billing_period_start for billing_cycle, month_end for first_of_month. Defaults to the anchor that matches the reset. */
+    overageInvoiceAnchor?: Schematic.BillingArrearsAnchor;
     priceBehavior?: Schematic.EntitlementPriceBehavior;
     /** Use MonthlyPriceTiers or YearlyPriceTiers instead */
     priceTiers?: Schematic.CreatePriceTierRequestBody[];

package/dist/api/types/index.d.ts

@@ -37,6 +37,8 @@ export * from "./BillingCustomerSubscription";
 export * from "./BillingCustomerWithSubscriptionsResponseData";
 export * from "./BillingLinkedResourceResponseData";
 export * from "./BillingMeterResponseData";
+export * from "./BillingPlanCreditGrantBillingMode";
+export * from "./BillingPlanCreditGrantPriceTierResponseData";
 export * from "./BillingPlanCreditGrantResetCadence";
 export * from "./BillingPlanCreditGrantResetStart";
 export * from "./BillingPlanCreditGrantResetType";
@@ -168,6 +170,7 @@ export * from "./CreditEventLedgerResponseData";
 export * from "./CreditEventType";
 export * from "./CreditGrantDetail";
 export * from "./CreditGrantExpiryRequestBody";
+export * from "./CreditGrantPriceTierRequestBody";
 export * from "./CreditGrantSortOrder";
 export * from "./CreditLeaseResponseData";
 export * from "./CreditReservationResponseData";
@@ -181,6 +184,7 @@ export * from "./CreditsAutoTopupSuccess";
 export * from "./CreditsCreditPurchaseSuccess";
 export * from "./CreditsWebhookCompanySummary";
 export * from "./CreditsWebhookCreditSummary";
+export * from "./CreditTransferReason";
 export * from "./CreditTransferResponseData";
 export * from "./CreditTransferView";
 export * from "./CreditTriggerConfig";

package/dist/cache/redis.d.ts

@@ -39,6 +39,17 @@ export interface RedisClient {
         arguments: string[];
     }): Promise<unknown>;
     pExpireAt(key: string, timestamp: number): Promise<unknown>;
+    multi?(): RedisMulti;
+}
+/**
+ * The queued-command half of MULTI/EXEC, as node-redis v4 returns it from
+ * `multi()`. Only the commands the SDK queues are declared; every one of them
+ * is single-key, so the transaction is safe under Redis Cluster too.
+ */
+export interface RedisMulti {
+    hSet(key: string, field: string | Record<string, string | number>, value?: string | number): RedisMulti;
+    pExpireAt(key: string, timestamp: number): RedisMulti;
+    exec(): Promise<unknown>;
 }
 export interface RedisOptions extends CacheOptions {
     /** Pre-created, connected redis client */

package/dist/credits/check.d.ts

@@ -33,7 +33,7 @@ export interface CreditCheckDeps {
  *      check. Otherwise `creditId` + `consumptionRate` + `eventSubtype` come
  *      straight off the entitlement — no structural flag scan.
  *   2. Acquire (or reuse) a lease for `(company, creditId)`.
- *   3. Try to reserve `quantity × consumptionRate` from the lease.
+ *   3. Try to reserve `ceil(quantity) × consumptionRate` from the lease.
  *   4. Run the WASM rules engine against a substituted company snapshot
  *      (`credit_balances[creditId] = lease.localRemaining` *before* the
  *      reservation we just made was debited), gating with `credit_cost` so the
@@ -45,9 +45,14 @@ export declare function checkWithLease(deps: CreditCheckDeps, key: string, evalC
  * Build the preflight options envelope for a client-side rules evaluation.
  * With an `eventSubtype` the quantity goes out as the `event_usage` pair so
  * the engine matches it to the subtype's condition; without one it goes out
- * as the generic `usage` knob. Exported so `client.check`'s fallback path can
- * thread the same preflight through a plain flag check — any client-side
- * evaluation (datastream, replicator) honors it even when the lease path
- * can't run.
+ * as the generic `usage` knob. Exported so `client.check`'s fallback path and
+ * the server-mode check-and-reserve body can thread the same preflight — any
+ * evaluation path honors it even when the lease path can't run.
+ *
+ * The quantity rounds up here, once, so every consumer of this envelope asks
+ * the same whole-unit question: the engine takes an integer, the REST body
+ * takes an integer, and the settling Track event bills `ceil(actual)`. A
+ * preflight is an upper bound, so rounding up is also the only safe direction
+ * — the check must not pass on less usage than the action is about to record.
  */
 export declare function buildPreflightOptions(options: CheckOptions): CheckFlagOptions | undefined;

package/dist/credits/index.d.ts

@@ -1,7 +1,7 @@
-export { LeaseStore, leaseKey, type LeaseEntry, type ILeaseStore } from "./lease-store";
+export { LeaseStore, leaseKey, type LeaseEntry, type ILeaseStore, type ReserveResult } from "./lease-store";
 export { ReservationStore, type IReservationStore } from "./reservation-store";
-export { CreditLeaseManager } from "./lease-manager";
+export { CreditLeaseManager, settleWithin, unrefTimer } from "./lease-manager";
 export { RedisLeaseStore } from "./redis-lease-store";
 export { RedisReservationStore } from "./redis-reservation-store";
-export { DEFAULT_LEASE_DURATION_MS, DEFAULT_LEASE_SIZE, DEFAULT_LOW_WATER_MARK, DEFAULT_PREWARM_POLL_INTERVAL_MS, DEFAULT_PREWARM_RESOLVE_TIMEOUT_MS, DEFAULT_RESERVATION_TTL_MS, DEFAULT_SWEEP_INTERVAL_MS, } from "./types";
-export type { CreditLeaseConfig, ResolvedLeaseConfig, Reservation, CheckOptions, CheckResult, OnAcquireFailure, TrackWithReservationOptions, } from "./types";
+export { DEFAULT_LEASE_DURATION_MS, DEFAULT_LEASE_SIZE, DEFAULT_LOW_WATER_MARK, DEFAULT_PREWARM_POLL_INTERVAL_MS, DEFAULT_PREWARM_RESOLVE_TIMEOUT_MS, DEFAULT_RESERVATION_TTL_MS, DEFAULT_SWEEP_INTERVAL_MS, MAX_RESERVATION_TTL_MS, RESERVATION_TTL_SKEW_ALLOWANCE_MS, SHUTDOWN_DRAIN_TIMEOUT_MS, } from "./types";
+export type { CreditLeaseConfig, CreditLeaseMode, ResolvedLeaseConfig, Reservation, CheckOptions, CheckResult, OnAcquireFailure, TrackWithReservationOptions, } from "./types";

package/dist/credits/lease-manager.d.ts

@@ -2,6 +2,15 @@ import type { CreditsClient } from "../api/resources/credits/client/Client";
 import type { Logger } from "../logger";
 import { type ILeaseStore, type LeaseEntry } from "./lease-store";
 import { type CreditLeaseConfig, type ResolvedLeaseConfig } from "./types";
+/** Drop a timer's hold on the event loop where the runtime has one (Node). */
+export declare function unrefTimer(timer: ReturnType<typeof setTimeout>): void;
+/**
+ * Await `promises`, giving up after `timeoutMs`. Reports whether everything
+ * landed, so a caller winding down can say what it is abandoning. Abandoned
+ * work is not cancelled — promises have no cancellation — it just stops being
+ * waited on.
+ */
+export declare function settleWithin(promises: Promise<unknown>[], timeoutMs: number): Promise<boolean>;
 /**
  * Owns the lifecycle of `credit_lease` rows for a single client: acquire on
  * first use or after expiry, extend when the local view dips below the low
@@ -20,6 +29,8 @@ export declare class CreditLeaseManager {
     private readonly config;
     private readonly inflightAcquire;
     private readonly inflightExtend;
+    private readonly background;
+    private stopped;
     constructor(opts: {
         creditsClient: CreditsClient;
         leaseStore: ILeaseStore;
@@ -48,12 +59,71 @@ export declare class CreditLeaseManager {
      *     that figure (a single check just failed a reserve for that many
      *     credits — extend opportunistically instead of waiting for the next
      *     sub-watermark check).
+     * A caller arriving while an extend is in flight joins it. If its own
+     * shortfall is larger than what that extend asked for, it waits the flight
+     * out and then issues exactly one follow-up extend for the remaining
+     * difference — otherwise it would inherit a tranche-sized ask and fail its
+     * post-extend retry with credits still sitting on the server. A flight it
+     * finds on the way back is only joined if that one covers the shortfall
+     * too; a smaller one is waited out, never inherited.
      * Returns the in-flight promise so callers can await it or fire-and-forget.
      * Never rejects (it is often fire-and-forget — a rejection would surface
      * as an unhandled promise rejection).
      */
-    maybeExtendInBackground(companyId: string, creditTypeId: string, requiredCredits?: number, requestOptions?: CreditsClient.RequestOptions): Promise<LeaseEntry | undefined>;
+    maybeExtendInBackground(companyId: string, creditTypeId: string, requiredCredits?: number, requestOptions?: CreditsClient.RequestOptions, joinDeadlineMs?: number): Promise<LeaseEntry | undefined>;
+    private extendIfNeeded;
+    /** When a joiner's wait on a shared flight runs out, or undefined for no cap. */
+    private joinDeadline;
+    /**
+     * Await a flight somebody else is running, giving up at `deadline`. Giving
+     * up abandons only our wait: the flight keeps running for the callers still
+     * on it, and whatever it installs is there for our next check to read.
+     */
+    private joinWithin;
+    /**
+     * Read the slot, reporting `undefined` when the read fails or the lease is
+     * absent or expired. An expired lease is never extended: the server treats
+     * it as released (its remainder already refunded to the company balance),
+     * so the right move is a fresh acquire, which the next check's
+     * `acquireIfNeeded` performs. Extending would at best waste a wire call and
+     * at worst resurrect a stale local row.
+     */
+    private readLiveLease;
+    /** Whether `entry` sits low enough to warrant an extend. */
+    private needsExtend;
+    /**
+     * Register and run an extend as the slot's in-flight one. The cleanup is
+     * identity-guarded rather than an unconditional `delete`: a joiner whose
+     * shortfall outran this flight registers a follow-up for the same key, and
+     * this flight's `finally` must not evict it.
+     */
+    private startExtend;
+    /**
+     * Re-read the slot now that this flight owns it, and extend only if the
+     * fresh row still warrants one. The row that decided this extend was read
+     * before the flight was registered, so an extend that landed in that gap,
+     * clearing its own flight on the way out, would otherwise be followed by a
+     * second extend, under a new idempotency key, for a lease it already topped
+     * up. The registered `requestedAdditional` stands: a joiner compares its
+     * shortfall against that figure, so the wire body has to carry it.
+     */
+    private recheckAndExtend;
     private extend;
+    /** Hold a reference to unawaited work so `drain()` can wait it out. */
+    private track;
+    /**
+     * Refuse new lease work. Idempotent, and paired with `drain()`: stopping
+     * first is what makes the drain terminate, since nothing can enqueue
+     * behind it.
+     */
+    stop(): void;
+    /**
+     * Wait out lease work already on the wire, so a close releases what that
+     * work installs instead of orphaning it. Bounded: whatever has not landed
+     * by `timeoutMs` is abandoned rather than stalling the caller's shutdown,
+     * and the credits it holds fall back to server-side expiry.
+     */
+    drain(timeoutMs?: number): Promise<void>;
     /**
      * Release every live lease held in the store. ONLY safe when the store is
      * per-process (in-memory): those leases are exclusively this process's, so
@@ -63,6 +133,8 @@ export declare class CreditLeaseManager {
      * drawing on the same leases — and is excluded by the `list` capability
      * check (only the in-memory store implements it). Best-effort: failures
      * are logged and the lease falls back to server-side expiry.
+     * Bounded by `timeoutMs`, so a store or wire call that never lands cannot
+     * hold a closing client open; whatever is abandoned expires server-side.
      */
-    releaseAllLocalLeases(): Promise<void>;
+    releaseAllLocalLeases(timeoutMs?: number): Promise<void>;
 }

package/dist/credits/lease-store.d.ts

@@ -21,6 +21,14 @@ export interface LeaseEntry {
     localRemainingCredits: number;
     expiresAt: Date;
 }
+/**
+ * Outcome of a successful `tryReserve`: the post-debit balance plus the ID of
+ * the lease the credits actually came out of.
+ */
+export interface ReserveResult {
+    balance: number;
+    leaseId: string;
+}
 /** Backing-store contract shared by `LeaseStore` (in-memory) and `RedisLeaseStore` (shared). */
 export interface ILeaseStore {
     get(companyId: string, creditTypeId: string): Promise<LeaseEntry | undefined> | LeaseEntry | undefined;
@@ -65,15 +73,23 @@ export interface ILeaseStore {
     drop(companyId: string, creditTypeId: string): Promise<void>;
     /**
      * Atomically check-and-debit `credits` from the lease's remaining balance.
-     * Returns the post-debit `localRemainingCredits` on success, or `null` if
-     * there is no live lease, the balance is insufficient, or `credits` is not
-     * a finite non-negative number (NaN must never reach the debit — it slips
-     * through every numeric comparison and would poison the balance into
-     * allowing everything). Returning the balance rather than a boolean lets
-     * the caller derive the pre-debit figure (`returned + credits`) without a
-     * follow-up read.
+     * Returns the post-debit `localRemainingCredits` together with the
+     * `leaseId` the debit landed on, or `null` if there is no live lease, the
+     * balance is insufficient, or `credits` is not a finite non-negative
+     * number (NaN must never reach the debit — it slips through every numeric
+     * comparison and would poison the balance into allowing everything).
+     * Returning the balance rather than a boolean lets the caller derive the
+     * pre-debit figure (`returned + credits`) without a follow-up read.
+     *
+     * The debit is NOT keyed by lease ID: it charges whichever lease occupies
+     * the slot at that moment, which need not be the one the caller's acquire
+     * handed back — the slot's lease can be replaced in between (by the
+     * sweeper, or by a sibling pod on a shared backend). The caller MUST
+     * therefore pin its reservation to the returned `leaseId`, never to the
+     * acquired one: the settle refund, the sweep refund, and the Track event's
+     * `lease_id` all have to name the lease that was actually charged.
      */
-    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | null>;
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<ReserveResult | null>;
     /**
      * Refund credits to the slot's lease balance (clamped at `grantedAmount`).
      * When `leaseId` is supplied, the refund applies ONLY if the slot still
@@ -126,10 +142,10 @@ export declare class LeaseStore implements ILeaseStore {
     drop(companyId: string, creditTypeId: string): Promise<void>;
     /**
      * Attempt to reserve `credits` from the local remaining balance.
-     * Returns the post-debit balance on success, `null` if there isn't enough
-     * remaining (see `ILeaseStore.tryReserve`).
+     * Returns the post-debit balance and the charged lease's ID on success,
+     * `null` if there isn't enough remaining (see `ILeaseStore.tryReserve`).
      */
-    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | null>;
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<ReserveResult | null>;
     /**
      * Refund credits back to the local balance (capped at grantedAmount).
      * When `leaseId` is given, the refund is dropped if the slot now holds a

package/dist/credits/redis-lease-store.d.ts

@@ -1,5 +1,5 @@
 import type { RedisClient } from "../cache/redis";
-import { type ILeaseStore, type LeaseEntry } from "./lease-store";
+import { type ILeaseStore, type LeaseEntry, type ReserveResult } from "./lease-store";
 /**
  * Redis-backed lease store. One hash per `(companyId, creditTypeId)` slot, with
  * atomic mutations via single-key Lua scripts so it stays correct on both
@@ -25,6 +25,6 @@ export declare class RedisLeaseStore implements ILeaseStore {
     replace(entry: Omit<LeaseEntry, "localRemainingCredits">): Promise<boolean>;
     extend(companyId: string, creditTypeId: string, grantedAmount: number, newExpiresAt?: Date, leaseId?: string): Promise<void>;
     drop(companyId: string, creditTypeId: string): Promise<void>;
-    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | null>;
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<ReserveResult | null>;
     refund(companyId: string, creditTypeId: string, credits: number, leaseId?: string): Promise<void>;
 }

package/dist/credits/server-check.d.ts

@@ -0,0 +1,40 @@
+import type * as api from "../api";
+import type { CreditsClient } from "../api/resources/credits/client/Client";
+import type { FeaturesClient } from "../api/resources/features/client/Client";
+import type { Logger } from "../logger";
+import type { CheckOptions, CheckResult } from "./types";
+/** Everything `checkWithServerReservation` needs to satisfy a server-mode check. */
+export interface ServerCheckDeps {
+    features: FeaturesClient;
+    credits: CreditsClient;
+    logger: Logger;
+    /** How far out to set the hold's `expiresAt` (ms). */
+    reservationTTL: number;
+    /**
+     * Resolve the caller's default for this flag — `options.defaultValue` when
+     * set, otherwise the client-level flag default. Used by the fail-open
+     * branch, which has no local engine to re-run.
+     */
+    getDefault: () => boolean;
+}
+/**
+ * Drives a single `client.check` with `usage` set, in server mode.
+ *
+ * One `POST /flags/{key}/check-and-reserve` call does everything the client
+ * path spreads across a lease acquire, a local reserve, and a WASM eval: the
+ * server evaluates the flag against the company's real balance, applies the
+ * preflight cost, and takes the hold — all in the same round-trip. There is no
+ * lease, no local store, and no rules engine involved.
+ *
+ * The failure contract differs from client mode in one place. `fail-open` there
+ * means "re-run the engine with the credit balance assumed sufficient", so plan
+ * targeting and every non-credit condition still apply. Server mode has no
+ * local engine to re-run — the call that would have answered is the one that
+ * failed — so `fail-open` returns the caller's default value
+ * (`options.defaultValue`, else the client's configured flag default) instead.
+ * `fail-closed` denies, same as client mode.
+ *
+ * No `flag_check` event is enqueued here: the server logs the flag check for
+ * check-and-reserve itself, the same way the REST `checkFlag` path does.
+ */
+export declare function checkWithServerReservation(deps: ServerCheckDeps, key: string, evalCtx: api.CheckFlagRequestBody, options: CheckOptions, fallback: () => Promise<CheckResult>): Promise<CheckResult>;

package/dist/credits/track.d.ts

@@ -3,7 +3,7 @@ import type { IReservationStore } from "./reservation-store";
 import type { Reservation, TrackWithReservationOptions } from "./types";
 /** Outcome of consuming a reservation and building its Track event. */
 export interface ReservationConsumeResult {
-    /** The Track event to emit. Always carries the `leaseId`. */
+    /** The Track event to emit. Always carries the `leaseId` (client mode) or the `reservationId` (server mode). */
     track: api.EventBodyTrack;
     /**
      * `true` when the reservation was still live and `consume` debited/refunded

package/dist/credits/types.d.ts

@@ -13,23 +13,47 @@ import type { RedisClient } from "../cache/redis";
 export type OnAcquireFailure = "fail-open" | "fail-closed";
 export declare const DEFAULT_LEASE_DURATION_MS: number;
 export declare const DEFAULT_RESERVATION_TTL_MS: number;
+export declare const MAX_RESERVATION_TTL_MS: number;
+export declare const RESERVATION_TTL_SKEW_ALLOWANCE_MS: number;
 export declare const DEFAULT_LEASE_SIZE: number;
 export declare const DEFAULT_LOW_WATER_MARK: number;
 export declare const DEFAULT_SWEEP_INTERVAL_MS: number;
 export declare const DEFAULT_PREWARM_RESOLVE_TIMEOUT_MS: number;
 export declare const DEFAULT_PREWARM_POLL_INTERVAL_MS: number;
+export declare const SHUTDOWN_DRAIN_TIMEOUT_MS: number;
+/**
+ * Where a credit hold lives for a `check()` that passes `usage`.
+ * - `client`: local leases over DataStream — the SDK acquires a tranche of
+ *   credits up front and carves reservations out of it locally (today's
+ *   behavior). Requires DataStream (or replicator mode), and a shared Redis
+ *   backend to gate across pods.
+ * - `server`: one `check-and-reserve` API call per check — the server
+ *   evaluates the flag and takes the hold in the same round-trip. No
+ *   DataStream, no Redis, no local stores.
+ * - `auto` (default): `client` when DataStream is enabled, `server` otherwise.
+ */
+export type CreditLeaseMode = "client" | "server" | "auto";
 /**
  * Configuration block enabling client-side lease + reservation behavior on
  * `client.check` / `client.trackWithReservation`. Omit to keep the SDK
  * lease-unaware (`check` falls back to a plain flag check).
  */
 export interface CreditLeaseConfig {
+    /**
+     * Where the credit hold lives. Default `auto` — client mode when
+     * DataStream is enabled, server mode otherwise. See `CreditLeaseMode`.
+     */
+    mode?: CreditLeaseMode;
     /** Default lease duration in milliseconds. Default `DEFAULT_LEASE_DURATION_MS` (5 minutes). */
     defaultLeaseDuration?: number;
     /**
      * Default reservation TTL in milliseconds. Default `DEFAULT_RESERVATION_TTL_MS`
-     * (60 seconds). Size this above the longest expected gap between `check()`
-     * and `trackWithReservation()`: a settle arriving after the TTL still bills
+     * (60 seconds). In server mode it is capped at `MAX_RESERVATION_TTL_MS`
+     * (1 hour) less `RESERVATION_TTL_SKEW_ALLOWANCE_MS`, since an hour out is
+     * the furthest the API will hold credits and it measures that against its
+     * own clock. Size this above the
+     * longest expected gap between `check()` and `trackWithReservation()`: a
+     * settle arriving after the TTL still bills
      * the server but doesn't re-debit the local lease (its hold was already
      * swept back), so the local balance reads high until the lease rolls over.
      */
@@ -71,7 +95,7 @@ export interface CreditLeaseConfig {
      */
     redisKeyPrefix?: string;
     /** Per-credit-type overrides (keyed by credit type ID). */
-    overrides?: Record<string, Partial<Omit<CreditLeaseConfig, "overrides" | "sweepIntervalMs" | "redisClient" | "redisKeyPrefix">>>;
+    overrides?: Record<string, Partial<Omit<CreditLeaseConfig, "overrides" | "mode" | "sweepIntervalMs" | "redisClient" | "redisKeyPrefix">>>;
 }
 /** Resolved config for a single credit type after applying defaults + overrides. */
 export interface ResolvedLeaseConfig {
@@ -84,8 +108,17 @@ export interface ResolvedLeaseConfig {
 export interface Reservation {
     /** Opaque reservation ID. */
     id: string;
-    /** Underlying lease ID this reservation draws from. */
+    /**
+     * Underlying lease ID this reservation draws from. In server mode there is
+     * no lease — this mirrors `id` so the field stays populated.
+     */
     leaseId: string;
+    /**
+     * Where the hold lives. `server` means the API holds the credits and the
+     * settling Track event routes by `reservation_id`; absent (or `client`)
+     * means the hold is a local carve-out of a lease.
+     */
+    mode?: "client" | "server";
     /** Company that owns the lease. */
     companyId: string;
     /** Credit type the reservation reserves against. */

package/dist/index.d.ts

@@ -6,5 +6,5 @@ export { ConsoleLogger, LogLevel, type Logger } from "./logger";
 export { SchematicEnvironment } from "./environments";
 export { SchematicError, SchematicTimeoutError } from "./errors";
 export { RulesEngineClient } from "./rules-engine";
-export type { CheckOptions, CheckResult, CreditLeaseConfig, OnAcquireFailure, Reservation, TrackWithReservationOptions, } from "./credits";
+export type { CheckOptions, CheckResult, CreditLeaseConfig, CreditLeaseMode, OnAcquireFailure, Reservation, TrackWithReservationOptions, } from "./credits";
 export { verifyWebhookSignature, verifySignature, computeSignature, computeHexSignature, WebhookSignatureError, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER } from "./webhooks";