@schematichq/schematic-typescript-node 1.6.0 → 1.6.1

package/README.md

@@ -800,13 +800,12 @@ const client = new SchematicClient({
 
 ## Credit Leases and Reservations
 
-For features metered by credit burndown (e.g. inference tokens), the SDK can enforce credit balances locally — without a Schematic API call on every check — using a lease-and-reservation system:
+For features metered by credit burndown (e.g. inference tokens), `check()` holds credits for the work about to run and `trackWithReservation()` settles the hold with actual usage. The SDK gates in one of two modes:
 
-- A **lease** is a tranche of credits acquired transactionally from Schematic's API. It functions as a hold against the company's credit balance until it is consumed, released, or expires.
-- A **reservation** is a client-side hold carved out of the lease at check time, sized to the upper bound of the operation's usage. This protects against races and over-spend between the check and the eventual usage report.
-- When the work completes, a track call reports actual usage; the difference between reserved and actual usage is refunded to the lease.
+- **Client mode** acquires a **lease**, a tranche of credits held against the company's balance, and carves a per-request **reservation** out of it locally, so a check needs no API call. It requires [DataStream](#datastream) (or [Replicator Mode](#replicator-mode)) and, across multiple processes, a shared Redis so every instance gates against the same lease.
+- **Server mode** makes one `check-and-reserve` API call per check. No lease, no Redis, no local state.
 
-> **Requirements:** Credit leases require [DataStream](#datastream) (or [Replicator Mode](#replicator-mode)) — lease-bearing checks are evaluated locally against cached flag and company state. In a horizontally-scaled deployment, a shared Redis backend is also required so that all SDK instances gate against the same lease balance; without one, lease state is per-process.
+`creditLeases.mode` defaults to `auto`: client when DataStream is enabled, server otherwise. Client mode suits high-throughput gating; server mode suits low-volume checks and operations that run for seconds.
 
 ### Setup
 
@@ -821,25 +820,35 @@ const client = new SchematicClient({
     apiKey: process.env.SCHEMATIC_API_KEY,
     useDataStream: true,
     dataStream: {
-        redisClient, // also backs lease + reservation state automatically
+        redisClient, // also backs lease + reservation state
     },
     creditLeases: {
-        defaultLeaseDuration: 5 * 60 * 1000, // lease lifetime (ms)
-        defaultReservationTTL: 60 * 1000, // how long a reservation is held if not settled by a track (ms)
         defaultLeaseSize: 10_000, // credits requested per lease
-        lowWaterMark: 0.25, // extend the lease in the background when its balance dips below this fraction
+        defaultLeaseDuration: 5 * 60 * 1000, // lease lifetime (ms)
+        defaultReservationTTL: 60 * 1000, // how long a reservation is held if no track settles it (ms)
     },
 });
 ```
 
-When `dataStream.redisClient` is configured, lease and reservation state automatically lives in the same Redis, with atomic reservations driven by Lua scripts — no additional configuration needed. To point lease state at a *different* Redis, set `creditLeases.redisClient` explicitly.
+Set `creditLeases.redisClient` to keep lease state in a different Redis than the DataStream cache.
 
-### Checking and tracking
+Server mode needs only a TTL:
 
-`check()` reserves the operation's upper-bound usage against the lease and returns a reservation handle; `trackWithReservation()` settles it with actual usage:
+```ts
+const client = new SchematicClient({
+    apiKey: process.env.SCHEMATIC_API_KEY,
+    creditLeases: {
+        defaultReservationTTL: 60 * 1000, // how long the server holds the credits if no track settles them (ms, max 1 hour)
+    },
+});
+```
+
+Only `mode` and `defaultReservationTTL` apply in server mode; the SDK warns at startup if a client-only option is set.
+
+### Checking and tracking
 
 ```ts
-// Per-request: reserve up to maxTokens against the lease.
+// Reserve up to maxTokens for this operation.
 const result = await client.check(
     { company: { id: "your-company-id" } },
     "inference",
@@ -854,15 +863,25 @@ if (!result.allowed) {
 
 const inference = await runInference(/* ... */);
 
-// Report actual usage; the unused slice of the reservation is refunded to the lease.
-await client.trackWithReservation(result.reservation!, inference.tokensUsed);
+// Report actual usage; the unused slice of the reservation is refunded.
+if (result.reservation) {
+    await client.trackWithReservation(result.reservation, inference.tokensUsed);
+} else {
+    await client.track({
+        event: "inference_tokens",
+        company: { id: "your-company-id" },
+        quantity: inference.tokensUsed,
+    });
+}
 ```
 
-If the caller never settles a reservation, it expires after `defaultReservationTTL` and its credits are returned to the lease. If the work outlives the reservation's TTL, `trackWithReservation` still bills the usage — the track event carries a deterministic idempotency key, so duplicate or recovery emits never double-bill. However, the local lease balance is not re-debited on that late settle (the expired reservation's hold was already swept back to the lease), so it reads high until the lease rolls over. **Set `defaultReservationTTL` above the longest expected gap between `check()` and `trackWithReservation()`** to keep the local balance accurate.
+A check can allow without taking a hold (the feature is not credit-metered, `usage` is 0, or the check failed open), and that usage still has to be tracked.
+
+An unsettled reservation expires after `defaultReservationTTL` and its credits return to the lease. A late settle still bills the usage (the track event carries a deterministic idempotency key, so it never double-bills) but does not re-debit the local lease, so set `defaultReservationTTL` above the longest expected gap between `check()` and `trackWithReservation()`.
 
 ### Pre-warming
 
-To avoid paying the lease-acquire round trip on a session's first check, pre-warm leases when the user is identified:
+Pre-warm leases when the user is identified, so a session's first check does not wait on a lease acquire:
 
 ```ts
 await client.identify(
@@ -874,11 +893,11 @@ await client.identify(
 );
 ```
 
-Or call `client.prewarm(evalCtx, creditTypeIds)` directly.
+Or call `client.prewarm(evalCtx, creditTypeIds)` directly. Both are no-ops in server mode.
 
 ### Failure behavior
 
-By default, a check that cannot be gated (API unreachable, Redis down, lease exhausted) **fails closed** (`allowed: false`). Override per check for callers where letting traffic through is preferable to a denial:
+A check that cannot be gated (API unreachable, Redis down, lease exhausted) fails closed by default. Override per check:
 
 ```ts
 const result = await client.check(evalCtx, "inference", {
@@ -888,20 +907,22 @@ const result = await client.check(evalCtx, "inference", {
 });
 ```
 
-`fail-open` does not skip evaluation: the flag's rules still run with the credit balance assumed sufficient, so plan targeting, overrides, and all non-credit conditions still apply — only the credit gate is bypassed.
+In client mode, `fail-open` still evaluates the flag's rules with the credit balance assumed sufficient, so plan targeting and all non-credit conditions apply and only the credit gate is bypassed. In server mode it returns the flag's default value, which is `false` unless you pass `defaultValue` or configure a `flagDefaults` entry.
 
 ### Configuration options
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `defaultLeaseDuration` | `number` | 5 minutes | Lease lifetime in milliseconds |
-| `defaultReservationTTL` | `number` | 60 seconds | How long an unsettled reservation is held (ms); set above your longest expected work duration |
-| `defaultLeaseSize` | `number` | 10000 | Credits requested per lease acquire/extend |
-| `lowWaterMark` | `number` | 0.25 | Extend in the background when the lease balance dips below this fraction |
-| `sweepIntervalMs` | `number` | 1000 | Sweep interval for expired reservations (ms) |
-| `redisClient` | `RedisClient` | `dataStream.redisClient` | Redis client for lease + reservation state |
-| `redisKeyPrefix` | `string` | `dataStream.redisKeyPrefix` | Key prefix for lease + reservation keys |
-| `overrides` | `object` | — | Per-credit-type overrides of the above (keyed by credit type ID) |
+| `mode` | `"client" \| "server" \| "auto"` | `auto` | Where the credit hold lives; `auto` picks client when DataStream is enabled, server otherwise |
+| `defaultReservationTTL` | `number` | 60 seconds | How long an unsettled reservation is held (ms) |
+| `defaultLeaseDuration` | `number` | 5 minutes | (client mode) Lease lifetime (ms) |
+| `defaultLeaseSize` | `number` | 10000 | (client mode) Credits requested per lease acquire or extend |
+| `lowWaterMark` | `number` | 0.25 | (client mode) Extend in the background when the lease balance dips below this fraction |
+| `sweepIntervalMs` | `number` | 1000 | (client mode) Sweep interval for expired reservations (ms) |
+| `prewarmResolveTimeoutMs` | `number` | 5000 | (client mode) How long `prewarm()` waits for a freshly identified company to surface (ms) |
+| `redisClient` | `RedisClient` | `dataStream.redisClient` | (client mode) Redis client for lease and reservation state |
+| `redisKeyPrefix` | `string` | `dataStream.redisKeyPrefix` | (client mode) Key prefix for lease and reservation keys |
+| `overrides` | `object` | — | (client mode) Per-credit-type overrides of the above, keyed by credit type ID |
 
 ## Testing
 

package/dist/api/resources/planmigrations/client/Client.d.ts

@@ -87,13 +87,14 @@ export declare class PlanmigrationsClient {
      *
      * @example
      *     await client.planmigrations.listMigrations({
+     *         featureId: "feature_id",
      *         planVersionId: "plan_version_id",
      *         status: "cancelled",
      *         limit: 1000000,
      *         offset: 1000000
      *     })
      */
-    listMigrations(request: Schematic.ListMigrationsRequest, requestOptions?: PlanmigrationsClient.RequestOptions): core.HttpResponsePromise<Schematic.ListMigrationsResponse>;
+    listMigrations(request?: Schematic.ListMigrationsRequest, requestOptions?: PlanmigrationsClient.RequestOptions): core.HttpResponsePromise<Schematic.ListMigrationsResponse>;
     private __listMigrations;
     /**
      * @param {Schematic.CreateMigrationInput} request
@@ -202,13 +203,14 @@ export declare class PlanmigrationsClient {
      *
      * @example
      *     await client.planmigrations.countMigrations({
+     *         featureId: "feature_id",
      *         planVersionId: "plan_version_id",
      *         status: "cancelled",
      *         limit: 1000000,
      *         offset: 1000000
      *     })
      */
-    countMigrations(request: Schematic.CountMigrationsRequest, requestOptions?: PlanmigrationsClient.RequestOptions): core.HttpResponsePromise<Schematic.CountMigrationsResponse>;
+    countMigrations(request?: Schematic.CountMigrationsRequest, requestOptions?: PlanmigrationsClient.RequestOptions): core.HttpResponsePromise<Schematic.CountMigrationsResponse>;
     private __countMigrations;
     /**
      * @param {Schematic.PreviewMigrationRequestBody} request

package/dist/api/resources/planmigrations/client/requests/CountMigrationsRequest.d.ts

@@ -2,6 +2,7 @@ import type * as Schematic from "../../../../index";
 /**
  * @example
  *     {
+ *         featureId: "feature_id",
  *         planVersionId: "plan_version_id",
  *         status: "cancelled",
  *         limit: 1000000,
@@ -9,7 +10,8 @@ import type * as Schematic from "../../../../index";
  *     }
  */
 export interface CountMigrationsRequest {
-    planVersionId: string;
+    featureId?: string;
+    planVersionId?: string;
     status?: Schematic.PlanVersionMigrationStatus;
     /** Page limit (default 100) */
     limit?: number;

package/dist/api/resources/planmigrations/client/requests/ListMigrationsRequest.d.ts

@@ -2,6 +2,7 @@ import type * as Schematic from "../../../../index";
 /**
  * @example
  *     {
+ *         featureId: "feature_id",
  *         planVersionId: "plan_version_id",
  *         status: "cancelled",
  *         limit: 1000000,
@@ -9,7 +10,8 @@ import type * as Schematic from "../../../../index";
  *     }
  */
 export interface ListMigrationsRequest {
-    planVersionId: string;
+    featureId?: string;
+    planVersionId?: string;
     status?: Schematic.PlanVersionMigrationStatus;
     /** Page limit (default 100) */
     limit?: number;

package/dist/api/resources/planmigrations/types/CountMigrationsParams.d.ts

@@ -3,6 +3,7 @@ import type * as Schematic from "../../../index";
  * Input parameters
  */
 export interface CountMigrationsParams {
+    featureId?: string;
     /** Page limit (default 100) */
     limit?: number;
     /** Page offset (default 0) */

package/dist/api/resources/planmigrations/types/ListMigrationsParams.d.ts

@@ -3,6 +3,7 @@ import type * as Schematic from "../../../index";
  * Input parameters
  */
 export interface ListMigrationsParams {
+    featureId?: string;
     /** Page limit (default 100) */
     limit?: number;
     /** Page offset (default 0) */

package/dist/api/resources/plans/client/Client.d.ts

@@ -143,6 +143,8 @@ export declare class PlansClient {
      *         q: "q",
      *         scopedToCompanyId: "scoped_to_company_id",
      *         withEntitlements: true,
+     *         withPublishedVersion: true,
+     *         withoutEntitlementForIncludeDrafts: true,
      *         withoutEntitlementFor: "without_entitlement_for",
      *         withoutPaidProductId: true,
      *         limit: 1000000,
@@ -342,6 +344,8 @@ export declare class PlansClient {
      *         q: "q",
      *         scopedToCompanyId: "scoped_to_company_id",
      *         withEntitlements: true,
+     *         withPublishedVersion: true,
+     *         withoutEntitlementForIncludeDrafts: true,
      *         withoutEntitlementFor: "without_entitlement_for",
      *         withoutPaidProductId: true,
      *         limit: 1000000,

package/dist/api/resources/plans/client/requests/CountPlansRequest.d.ts

@@ -16,6 +16,8 @@ import type * as Schematic from "../../../../index";
  *         q: "q",
  *         scopedToCompanyId: "scoped_to_company_id",
  *         withEntitlements: true,
+ *         withPublishedVersion: true,
+ *         withoutEntitlementForIncludeDrafts: true,
  *         withoutEntitlementFor: "without_entitlement_for",
  *         withoutPaidProductId: true,
  *         limit: 1000000,
@@ -48,6 +50,10 @@ export interface CountPlansRequest {
     scopedToCompanyId?: string;
     /** Include each plan's entitlements in the response */
     withEntitlements?: boolean;
+    /** Only return plans that have a published version */
+    withPublishedVersion?: boolean;
+    /** With without_entitlement_for, also treat an entitlement on a plan's draft version as existing */
+    withoutEntitlementForIncludeDrafts?: boolean;
     /** Filter out plans that already have a plan entitlement for the specified feature ID */
     withoutEntitlementFor?: string;
     /** Filter out plans that have a paid billing product ID */

package/dist/api/resources/plans/client/requests/ListPlansRequest.d.ts

@@ -16,6 +16,8 @@ import type * as Schematic from "../../../../index";
  *         q: "q",
  *         scopedToCompanyId: "scoped_to_company_id",
  *         withEntitlements: true,
+ *         withPublishedVersion: true,
+ *         withoutEntitlementForIncludeDrafts: true,
  *         withoutEntitlementFor: "without_entitlement_for",
  *         withoutPaidProductId: true,
  *         limit: 1000000,
@@ -48,6 +50,10 @@ export interface ListPlansRequest {
     scopedToCompanyId?: string;
     /** Include each plan's entitlements in the response */
     withEntitlements?: boolean;
+    /** Only return plans that have a published version */
+    withPublishedVersion?: boolean;
+    /** With without_entitlement_for, also treat an entitlement on a plan's draft version as existing */
+    withoutEntitlementForIncludeDrafts?: boolean;
     /** Filter out plans that already have a plan entitlement for the specified feature ID */
     withoutEntitlementFor?: string;
     /** Filter out plans that have a paid billing product ID */

package/dist/api/resources/plans/types/CountPlansParams.d.ts

@@ -32,8 +32,12 @@ export interface CountPlansParams {
     scopedToCompanyId?: string;
     /** Include each plan's entitlements in the response */
     withEntitlements?: boolean;
+    /** Only return plans that have a published version */
+    withPublishedVersion?: boolean;
     /** Filter out plans that already have a plan entitlement for the specified feature ID */
     withoutEntitlementFor?: string;
+    /** With without_entitlement_for, also treat an entitlement on a plan's draft version as existing */
+    withoutEntitlementForIncludeDrafts?: boolean;
     /** Filter out plans that have a paid billing product ID */
     withoutPaidProductId?: boolean;
 }

package/dist/api/resources/plans/types/ListPlansParams.d.ts

@@ -32,8 +32,12 @@ export interface ListPlansParams {
     scopedToCompanyId?: string;
     /** Include each plan's entitlements in the response */
     withEntitlements?: boolean;
+    /** Only return plans that have a published version */
+    withPublishedVersion?: boolean;
     /** Filter out plans that already have a plan entitlement for the specified feature ID */
     withoutEntitlementFor?: string;
+    /** With without_entitlement_for, also treat an entitlement on a plan's draft version as existing */
+    withoutEntitlementForIncludeDrafts?: boolean;
     /** Filter out plans that have a paid billing product ID */
     withoutPaidProductId?: boolean;
 }

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/credits/index.d.ts

@@ -3,5 +3,5 @@ export { ReservationStore, type IReservationStore } from "./reservation-store";
 export { CreditLeaseManager } 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, } from "./types";
+export type { CreditLeaseConfig, CreditLeaseMode, ResolvedLeaseConfig, Reservation, CheckOptions, CheckResult, OnAcquireFailure, TrackWithReservationOptions, } from "./types";

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,46 @@ 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;
+/**
+ * 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 +94,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 +107,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";