@schematichq/schematic-typescript-node 1.4.8 → 1.5.0

package/README.md

@@ -96,17 +96,17 @@ class CustomLogger implements Logger {
         // Your custom error logging logic
         console.error(`[ERROR] ${message}`, ...args);
     }
-    
+
     warn(message: string, ...args: any[]): void {
         // Your custom warning logging logic
         console.warn(`[WARN] ${message}`, ...args);
     }
-    
+
     info(message: string, ...args: any[]): void {
         // Your custom info logging logic
         console.info(`[INFO] ${message}`, ...args);
     }
-    
+
     debug(message: string, ...args: any[]): void {
         // Your custom debug logging logic
         console.debug(`[DEBUG] ${message}`, ...args);
@@ -683,7 +683,7 @@ export default {
       ttl: 1000 * 60 * 60, // 1 hour cache TTL
       keyPrefix: 'schematic:', // Optional prefix for KV keys
     });
-    
+
     // Initialize Schematic with the KV cache
     const schematic = new SchematicClient({
       apiKey: env.SCHEMATIC_API_KEY,
@@ -691,10 +691,10 @@ export default {
         flagChecks: [cache],
       }
     });
-    
+
     // Your application logic...
     // ...
-    
+
     // Don't forget to close the client when done
     schematic.close();
   }
@@ -798,6 +798,111 @@ const client = new SchematicClient({
 | `replicatorHealthCheck` | `number` | 30000 | Health check polling interval in milliseconds |
 | `cacheTTL` | `number` | 24 hours | Cache TTL in milliseconds |
 
+## 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:
+
+- 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.
+
+> **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.
+
+### Setup
+
+```ts
+import { createClient } from "redis";
+import { SchematicClient } from "@schematichq/schematic-typescript-node";
+
+const redisClient = createClient({ url: "redis://localhost:6379" });
+await redisClient.connect();
+
+const client = new SchematicClient({
+    apiKey: process.env.SCHEMATIC_API_KEY,
+    useDataStream: true,
+    dataStream: {
+        redisClient, // also backs lease + reservation state automatically
+    },
+    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
+    },
+});
+```
+
+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.
+
+### Checking and tracking
+
+`check()` reserves the operation's upper-bound usage against the lease and returns a reservation handle; `trackWithReservation()` settles it with actual usage:
+
+```ts
+// Per-request: reserve up to maxTokens against the lease.
+const result = await client.check(
+    { company: { id: "your-company-id" } },
+    "inference",
+    {
+        usage: maxTokens, // upper bound for this operation
+        eventSubtype: "inference_tokens", // the metered event
+    },
+);
+if (!result.allowed) {
+    throw new Error("credit balance exceeded");
+}
+
+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);
+```
+
+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.
+
+### Pre-warming
+
+To avoid paying the lease-acquire round trip on a session's first check, pre-warm leases when the user is identified:
+
+```ts
+await client.identify(
+    {
+        keys: { userId: "your-user-id" },
+        company: { keys: { id: "your-company-id" } },
+    },
+    { prewarm: ["credit-type-id"] }, // credit type IDs to acquire leases for
+);
+```
+
+Or call `client.prewarm(evalCtx, creditTypeIds)` directly.
+
+### 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:
+
+```ts
+const result = await client.check(evalCtx, "inference", {
+    usage: maxTokens,
+    eventSubtype: "inference_tokens",
+    onAcquireFailure: "fail-open",
+});
+```
+
+`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.
+
+### 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) |
+
 ## Testing
 
 ### Offline mode

package/dist/cache/redis.d.ts

@@ -1,7 +1,10 @@
 import { CacheProvider, CacheOptions } from "./types";
 /**
- * Minimal interface describing the redis client methods used by RedisCacheProvider.
- * Compatible with the 'redis' package's RedisClientType.
+ * Minimal interface describing the redis client methods used by the SDK.
+ * Compatible with the 'redis' package's RedisClientType (node-redis v4).
+ *
+ * Includes hash + sorted-set + eval surface used by the credit-lease and
+ * reservation stores to coordinate state across multiple SDK pods.
  */
 export interface RedisClient {
     get(key: string): Promise<string | null>;
@@ -12,6 +15,30 @@ export interface RedisClient {
         MATCH: string;
         COUNT: number;
     }): AsyncIterable<string>;
+    hSet(key: string, field: string | Record<string, string | number>, value?: string | number): Promise<unknown>;
+    hGet(key: string, field: string): Promise<string | null | undefined>;
+    hGetAll(key: string): Promise<Record<string, string>>;
+    hDel(key: string, field: string | string[]): Promise<unknown>;
+    zAdd(key: string, members: {
+        score: number;
+        value: string;
+    } | {
+        score: number;
+        value: string;
+    }[]): Promise<unknown>;
+    zRangeByScore(key: string, min: number | string, max: number | string, options?: {
+        LIMIT: {
+            offset: number;
+            count: number;
+        };
+    }): Promise<string[]>;
+    zRem(key: string, member: string | string[]): Promise<unknown>;
+    zCard(key: string): Promise<number>;
+    eval(script: string, options: {
+        keys: string[];
+        arguments: string[];
+    }): Promise<unknown>;
+    pExpireAt(key: string, timestamp: number): Promise<unknown>;
 }
 export interface RedisOptions extends CacheOptions {
     /** Pre-created, connected redis client */

package/dist/credits/check.d.ts

@@ -0,0 +1,49 @@
+import type * as api from "../api";
+import type { DataStreamClient } from "../datastream";
+import type { Logger } from "../logger";
+import type { CheckFlagOptions } from "../wrapper";
+import { CreditLeaseManager } from "./lease-manager";
+import type { ILeaseStore } from "./lease-store";
+import type { IReservationStore } from "./reservation-store";
+import type { CheckOptions, CheckResult } from "./types";
+/** Internal helper bundling everything needed to satisfy a lease-bearing check. */
+export interface CreditCheckDeps {
+    leaseStore: ILeaseStore;
+    reservations: IReservationStore;
+    manager: CreditLeaseManager;
+    datastream: DataStreamClient | undefined;
+    logger: Logger;
+    /**
+     * Report a `flag_check` event for a check the lease path resolved itself.
+     * Mirrors the plain `checkFlag` paths (which enqueue one per check) so
+     * lease-gated checks stay visible to flag-check analytics and company
+     * last-seen. Fallback exits don't call this — the plain check they
+     * delegate to enqueues its own.
+     */
+    enqueueFlagCheckEvent: (body: api.EventBodyFlagCheck) => void;
+}
+/**
+ * Drives a single `client.check` with `usage` set.
+ *
+ * Steps:
+ *   1. Resolve the matching credit-balance condition on the flag to get
+ *      `creditId` + `consumptionRate`.
+ *   2. Acquire (or reuse) a lease for `(company, creditId)`.
+ *   3. Try to reserve `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), plus `event_usage` options so
+ *      the engine evaluates the post-call balance. The reservation we made
+ *      in step 3 only sticks if the engine says allowed.
+ */
+export declare function checkWithLease(deps: CreditCheckDeps, key: string, evalCtx: api.CheckFlagRequestBody, options: CheckOptions, fallback: () => Promise<CheckResult>): Promise<CheckResult>;
+/**
+ * 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.
+ */
+export declare function buildPreflightOptions(options: CheckOptions): CheckFlagOptions | undefined;

package/dist/credits/index.d.ts

@@ -0,0 +1,7 @@
+export { LeaseStore, leaseKey, type LeaseEntry, type ILeaseStore } from "./lease-store";
+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";

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

@@ -0,0 +1,68 @@
+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";
+/**
+ * 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
+ * water mark, release on `client.close()`.
+ *
+ * Concurrency: each operation (acquire, extend) has its own best-effort
+ * single-flight map keyed by `(company, creditType)`. It's best-effort —
+ * callers racing ahead of the registration can still issue duplicate wire
+ * calls — which is safe because the server is idempotent for an active slot
+ * and `replace` keeps the first live lease.
+ */
+export declare class CreditLeaseManager {
+    private readonly creditsClient;
+    private readonly leaseStore;
+    private readonly logger;
+    private readonly config;
+    private readonly inflightAcquire;
+    private readonly inflightExtend;
+    constructor(opts: {
+        creditsClient: CreditsClient;
+        leaseStore: ILeaseStore;
+        logger: Logger;
+        config: CreditLeaseConfig;
+    });
+    resolveConfig(creditTypeId: string): ResolvedLeaseConfig;
+    /**
+     * Return the current lease entry, acquiring one (or replacing an expired
+     * one) if none is live. Best-effort single-flight: callers arriving after
+     * a request is registered share it (the first caller's `requestOptions`
+     * win); callers racing ahead of registration may duplicate the wire call,
+     * which the server's idempotent acquire absorbs.
+     * Never rejects: a store (Redis) failure is logged and reported as
+     * `undefined`, the same as a wire failure, so callers route it through
+     * their fail-open/fail-closed handling instead of an unhandled rejection.
+     */
+    acquireIfNeeded(companyId: string, creditTypeId: string, requestOptions?: CreditsClient.RequestOptions): Promise<LeaseEntry | undefined>;
+    private acquire;
+    /**
+     * Single-flight: kick off a background extend when one is warranted.
+     * An extend is triggered if EITHER:
+     *   - the local remaining is below the low-water-mark ratio (steady-state
+     *     refresh), or
+     *   - the caller passes `requiredCredits` and the local remaining is below
+     *     that figure (a single check just failed a reserve for that many
+     *     credits — extend opportunistically instead of waiting for the next
+     *     sub-watermark check).
+     * 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>;
+    private extend;
+    /**
+     * 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
+     * releasing them on `close()` returns their unspent remainder to the
+     * company balance immediately instead of waiting out the lease expiry. A
+     * shared (Redis) store must never do this — sibling pods are still
+     * 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.
+     */
+    releaseAllLocalLeases(): Promise<void>;
+}

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

@@ -0,0 +1,133 @@
+/**
+ * In-memory lease store, keyed by `${companyId}:${creditTypeId}`.
+ *
+ * Holds the lease ID, original granted amount, expiry, and the SDK's local
+ * view of `localRemainingCredits` — the portion of the lease not yet reserved
+ * by an outstanding reservation. Per-key serialization (Promise chain) keeps
+ * reserve / refund / replace atomic without external locking.
+ *
+ * The store doesn't talk to the API directly; `CreditLeaseManager` drives
+ * acquire/extend/release through the wire client and uses these methods to
+ * mirror remote state locally.
+ *
+ * For cross-pod deployments, swap this for `RedisLeaseStore` — both
+ * implement `ILeaseStore`.
+ */
+export interface LeaseEntry {
+    leaseId: string;
+    companyId: string;
+    creditTypeId: string;
+    grantedAmount: number;
+    localRemainingCredits: number;
+    expiresAt: Date;
+}
+/** Backing-store contract shared by `LeaseStore` (in-memory) and `RedisLeaseStore` (shared). */
+export interface ILeaseStore {
+    get(companyId: string, creditTypeId: string): Promise<LeaseEntry | undefined> | LeaseEntry | undefined;
+    /**
+     * Install a fresh lease for the slot, but only if no live lease already
+     * occupies it. Implementations must be safe against concurrent writers
+     * sharing the backend: if a live (unexpired) lease is already present —
+     * even one with a different `leaseId`, e.g. acquired by a sibling pod that
+     * raced this one — leave it untouched so its already-debited
+     * `localRemainingCredits` wins. Returns `true` if it wrote a fresh row,
+     * `false` if it kept an existing live lease (the caller should release the
+     * lease it acquired ONLY if its ID differs from the installed one — the
+     * server hands a racing acquire the same active lease back, and releasing
+     * that would pull the shared lease out from under every sibling).
+     */
+    replace(entry: Omit<LeaseEntry, "localRemainingCredits">): Promise<boolean>;
+    /**
+     * Reconcile the slot's lease to the server-authoritative `grantedAmount`
+     * total (after a remote extend), crediting the difference to
+     * `localRemainingCredits`. The delta MUST be computed atomically inside
+     * the store against the *current* stored total — never by the caller from
+     * a pre-wire-call read: with a shared backend, two pods extending the same
+     * lease concurrently would each apply a delta against the same stale read
+     * and mint phantom credits. Reconciling to the absolute total converges
+     * regardless of arrival order (a total a sibling already applied lands as
+     * a no-op). `newExpiresAt` only ever moves the expiry forward, so an
+     * out-of-order apply can't shorten a lease a sibling just extended. When
+     * `leaseId` is supplied, the extend applies ONLY if the slot still holds
+     * that lease: the server extended lease A, so its credits must not land on
+     * a successor lease B that replaced A after it expired mid-extend —
+     * crediting B would mint credits locally that the server granted to A
+     * (whose remainder it refunds at A's expiry). Mirrors the pin on `refund`.
+     */
+    extend(companyId: string, creditTypeId: string, grantedAmount: number, newExpiresAt?: Date, leaseId?: string): Promise<void>;
+    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.
+     */
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | null>;
+    /**
+     * Refund credits to the slot's lease balance (clamped at `grantedAmount`).
+     * When `leaseId` is supplied, the refund applies ONLY if the slot still
+     * holds that lease: a reservation carved out of lease A must never inflate
+     * a successor lease B that replaced it after A expired — A's unspent
+     * remainder (including this slice) was already refunded to the company
+     * balance server-side when A expired, so crediting B would double-count.
+     */
+    refund(companyId: string, creditTypeId: string, credits: number, leaseId?: string): Promise<void>;
+    /**
+     * Snapshot of all current entries. Only meaningful (and only implemented)
+     * for the per-process in-memory store, where `close()` releases this
+     * process's exclusively-held leases; a shared backend must NOT enumerate —
+     * sibling pods may still be drawing on those leases.
+     */
+    list?(): LeaseEntry[];
+}
+export declare function leaseKey(companyId: string, creditTypeId: string): string;
+export declare class LeaseStore implements ILeaseStore {
+    private leases;
+    /**
+     * Per-key serializer chain. Each `withLock` appends to the tail so
+     * reserve / refund / replace see consistent intermediate state.
+     */
+    private locks;
+    /** Snapshot of the current entry, or undefined if no active lease. */
+    get(companyId: string, creditTypeId: string): LeaseEntry | undefined;
+    /**
+     * Replace (or insert) the lease for the given (company, creditType).
+     * Resets `localRemainingCredits` to `grantedAmount` for a new lease.
+     * If a live lease already occupies the slot — regardless of `leaseId` — it
+     * is left alone so any already-debited `localRemainingCredits` wins.
+     * Returns `true` if a fresh row was written, `false` if an existing live
+     * lease was kept.
+     */
+    replace(entry: Omit<LeaseEntry, "localRemainingCredits">): Promise<boolean>;
+    /**
+     * Reconcile an existing lease to the server-authoritative `grantedAmount`
+     * total (after a remote extend), crediting the difference to
+     * `localRemainingCredits`. The delta is computed against the CURRENT
+     * stored total under the key lock, so concurrent extends converge instead
+     * of double-counting (see `ILeaseStore.extend`). If no lease exists for
+     * the key, this is a no-op (caller should have replaced). When `leaseId`
+     * is given, the extend is dropped if the slot now holds a different lease.
+     */
+    extend(companyId: string, creditTypeId: string, grantedAmount: number, newExpiresAt?: Date, leaseId?: string): Promise<void>;
+    /** Drop the lease entry (after a remote release or lazy expiry). */
+    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`).
+     */
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | 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
+     * different lease (see `ILeaseStore.refund`).
+     */
+    refund(companyId: string, creditTypeId: string, credits: number, leaseId?: string): Promise<void>;
+    /** Snapshot of all current entries (see `ILeaseStore.list`). */
+    list(): LeaseEntry[];
+    private withLock;
+}

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

@@ -0,0 +1,30 @@
+import type { RedisClient } from "../cache/redis";
+import { type ILeaseStore, type LeaseEntry } 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
+ * standalone and clustered Redis.
+ */
+export declare class RedisLeaseStore implements ILeaseStore {
+    private readonly client;
+    private readonly keyPrefix;
+    private readonly defaultLeaseDurationMs;
+    constructor(opts: {
+        client: RedisClient;
+        keyPrefix?: string;
+        /**
+         * Defensive fallback used by `extend()` when the caller doesn't supply
+         * `newExpiresAt`. The lease manager always passes one today, so this
+         * only matters for direct callers. Default `DEFAULT_LEASE_DURATION_MS`.
+         */
+        defaultLeaseDurationMs?: number;
+    });
+    /** Public so the reservation store can target the same lease hash for refunds. */
+    hashKey(companyId: string, creditTypeId: string): string;
+    get(companyId: string, creditTypeId: string): Promise<LeaseEntry | undefined>;
+    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>;
+    refund(companyId: string, creditTypeId: string, credits: number, leaseId?: string): Promise<void>;
+}

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

@@ -0,0 +1,46 @@
+import type { RedisClient } from "../cache/redis";
+import type { ILeaseStore } from "./lease-store";
+import type { IReservationStore } from "./reservation-store";
+import type { Reservation } from "./types";
+/**
+ * Redis-backed reservation table. Each reservation is a hash, indexed by
+ * `expiresAt` in a sorted set so the sweeper can pop expired entries in
+ * O(log n), and by `(company, credit)` so the balance display can sum a
+ * tenant's open holds. All mutations use single-key operations (or single-key
+ * Lua), so the store is correct on standalone and clustered Redis alike — the
+ * unspent-slice refund is delegated to the lease store rather than reaching
+ * across to the lease hash inside a multi-key script.
+ */
+export declare class RedisReservationStore implements IReservationStore {
+    private readonly client;
+    private readonly leaseStore;
+    private readonly sweepIntervalMs;
+    private readonly keyPrefix;
+    private sweepInterval;
+    private stopped;
+    constructor(opts: {
+        client: RedisClient;
+        leaseStore: ILeaseStore;
+        sweepIntervalMs?: number;
+        keyPrefix?: string;
+    });
+    private hashKey;
+    private indexKey;
+    private byCreditKey;
+    add(reservation: Reservation): Promise<void>;
+    get(id: string): Promise<Reservation | undefined>;
+    /**
+     * Sum open reservations for a (company, credit) with a single `HGETALL` on
+     * the per-tenant index hash — one round trip, one key (Cluster-safe), no
+     * per-reservation fan-out. The hash values are the authoritative
+     * `creditsReserved` figures; a field is present iff its reservation is open
+     * and unrefunded (consume removes the field and refunds in the same call),
+     * so summing them is exact. Display-path call, not a hot path.
+     */
+    reservedCredits(companyId: string, creditTypeId: string): Promise<number>;
+    consume(id: string, creditsConsumed: number): Promise<number | null>;
+    startSweep(): void;
+    sweepExpired(now?: Date): Promise<number>;
+    stop(): void;
+    size(): Promise<number>;
+}

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

@@ -0,0 +1,64 @@
+import type { Reservation } from "./types";
+import type { ILeaseStore } from "./lease-store";
+/** Backing-store contract for the reservation table. */
+export interface IReservationStore {
+    add(reservation: Reservation): Promise<void> | void;
+    get(id: string): Promise<Reservation | undefined> | Reservation | undefined;
+    consume(id: string, creditsConsumed: number): Promise<number | null>;
+    /**
+     * Sum of `creditsReserved` across open reservations for a (company, credit).
+     * These credits are carved out of the lease's `localRemainingCredits` but
+     * aren't spent yet, so a balance display can add them back to ignore
+     * in-flight holds.
+     */
+    reservedCredits(companyId: string, creditTypeId: string): Promise<number> | number;
+    startSweep(): void;
+    sweepExpired(now?: Date): Promise<number>;
+    stop(): void;
+    size(): Promise<number> | number;
+}
+/**
+ * In-memory reservation table, paired with a sweep loop that returns expired
+ * reservations to their underlying lease.
+ *
+ * For cross-pod deployments, swap this for `RedisReservationStore` — both
+ * implement `IReservationStore`.
+ */
+export declare class ReservationStore implements IReservationStore {
+    private readonly leaseStore;
+    private readonly sweepIntervalMs;
+    private reservations;
+    private sweepInterval;
+    private stopped;
+    constructor(leaseStore: ILeaseStore, sweepIntervalMs?: number);
+    /** Register a new reservation. Idempotent on `id`. */
+    add(reservation: Reservation): void;
+    /** Look up a reservation by ID. */
+    get(id: string): Reservation | undefined;
+    /**
+     * Sum open reservations for a (company, credit). Counts every reservation
+     * still in the table: its credits stay carved out of the lease's
+     * `localRemainingCredits` until `consume`/`sweepExpired` removes it and
+     * refunds the unspent remainder in the same step, so summing by presence
+     * keeps `localRemainingCredits + reservedCredits` exact.
+     */
+    reservedCredits(companyId: string, creditTypeId: string): number;
+    /**
+     * Consume a reservation — removes it from the table and refunds
+     * `creditsReserved - creditsConsumed` back to the underlying lease.
+     * Returns the credits actually consumed (clamped to `creditsReserved`)
+     * or `null` if the reservation is missing/already consumed.
+     */
+    consume(id: string, creditsConsumed: number): Promise<number | null>;
+    /** Start the background sweep loop. Safe to call repeatedly. */
+    startSweep(): void;
+    /**
+     * Scan for expired reservations, remove them, and refund their credits to
+     * the lease.
+     */
+    sweepExpired(now?: Date): Promise<number>;
+    /** Stop the sweep loop. */
+    stop(): void;
+    /** Test/debug: current reservation count. */
+    size(): number;
+}

package/dist/credits/track.d.ts

@@ -0,0 +1,44 @@
+import * as api from "../api";
+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`. */
+    track: api.EventBodyTrack;
+    /**
+     * `true` when the reservation was still live and `consume` debited/refunded
+     * the local lease in this call. `false` when the reservation was already
+     * gone from the store (swept after its TTL, or already consumed): the local
+     * lease balance was *not* touched here, and the returned `track` is a
+     * recovery event so the server still bills the actual usage. The caller is
+     * responsible for de-duping recovery emits (see `trackWithReservation`).
+     */
+    settledLocally: boolean;
+}
+/**
+ * Build the `EventBodyTrack` payload for a Track event that consumes a
+ * reservation, and consume the reservation against the lease (refunding the
+ * unused slice locally).
+ *
+ * The Track is built from the caller-held `reservation` handle, so it can be
+ * emitted even when the reservation has already been swept out of the store —
+ * the server is the source of truth for actual consumption. When the lease is
+ * still live server-side the `leaseId` routes the spend through its sub-ledger;
+ * when the server lease has itself expired/released, the server falls through
+ * to a direct grant decrement. Either way the usage is billed, so a hold that
+ * outlives its (client-side) reservation TTL is no longer dropped on the floor.
+ *
+ * On the recovery path (`settledLocally: false`) the sweeper already refunded
+ * the full hold and nothing re-debits the consumed slice, so the local lease
+ * reads high until rollover — hence `reservationTTL` should exceed the longest
+ * expected work duration (see `CreditLeaseConfig.defaultReservationTTL`).
+ */
+export declare function consumeReservationAndBuildEvent(reservations: IReservationStore, reservation: Reservation, actualQuantity: number, options?: TrackWithReservationOptions): Promise<ReservationConsumeResult>;
+/**
+ * Build the Track event for a reservation purely from the caller-held handle —
+ * no store access. Split out so `trackWithReservation` can still emit the
+ * billing event when the local settle (`consume`) fails on an unreachable
+ * store: the server is the source of truth for actual consumption, so the
+ * usage must be reported regardless of local bookkeeping.
+ */
+export declare function buildReservationTrackEvent(reservation: Reservation, actualQuantity: number, options?: TrackWithReservationOptions): api.EventBodyTrack;