@schematichq/schematic-typescript-node 1.4.7 → 1.5.0

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;

package/dist/credits/types.d.ts

@@ -0,0 +1,175 @@
+import type * as api from "../api";
+import type { RedisClient } from "../cache/redis";
+/**
+ * Behavior when a lease cannot be acquired or reserved against (API error,
+ * lease/reservation store unreachable, insufficient balance).
+ * - `fail-open`: err on the side of assuming the credits are there — the rules
+ *   engine still evaluates the flag (plan targeting, overrides, and all
+ *   non-credit conditions apply) with the credit balance substituted to an
+ *   effectively unlimited value, so only the credit gate is bypassed. No
+ *   reservation is issued.
+ * - `fail-closed`: `check()` returns `{ allowed: false }` so the caller blocks the action
+ */
+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 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;
+/**
+ * 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 {
+    /** 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
+     * 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.
+     */
+    defaultReservationTTL?: number;
+    /** Default lease size (credit amount requested). Default `DEFAULT_LEASE_SIZE` (10000). */
+    defaultLeaseSize?: number;
+    /**
+     * Fraction of remaining lease balance below which the SDK kicks off a
+     * background extend. Default `DEFAULT_LOW_WATER_MARK` (0.25).
+     */
+    lowWaterMark?: number;
+    /** Sweep interval (ms) for expired reservations. Default `DEFAULT_SWEEP_INTERVAL_MS` (1000). */
+    sweepIntervalMs?: number;
+    /**
+     * Max time `prewarm()` will wait for a freshly-identified company to
+     * surface in the datastream cache when only secondary keys are passed.
+     * Set to 0 to skip waiting entirely (prewarm bails immediately if the
+     * company isn't already cached). Default `DEFAULT_PREWARM_RESOLVE_TIMEOUT_MS`
+     * (5000ms).
+     */
+    prewarmResolveTimeoutMs?: number;
+    /**
+     * Pre-connected Redis client for lease + reservation state. Optional: when
+     * omitted, the SDK reuses the DataStream cache's Redis client
+     * (`dataStream.redisClient`) if one is configured, so an existing Redis
+     * setup backs leases automatically. Set this only to point lease state at a
+     * *different* Redis than the DataStream cache.
+     *
+     * When neither this nor `dataStream.redisClient` is configured, the SDK
+     * falls back to per-process in-memory stores — single-pod only, since
+     * cross-pod gating is lost (a warning is logged). With a Redis client
+     * present, the Lua-driven `tryReserve` / `consume` paths give atomic
+     * cross-pod gating.
+     */
+    redisClient?: RedisClient;
+    /**
+     * Optional Redis key prefix. Falls back to `dataStream.redisKeyPrefix` when
+     * unset, then to `schematic:`.
+     */
+    redisKeyPrefix?: string;
+    /** Per-credit-type overrides (keyed by credit type ID). */
+    overrides?: Record<string, Partial<Omit<CreditLeaseConfig, "overrides" | "sweepIntervalMs" | "redisClient" | "redisKeyPrefix">>>;
+}
+/** Resolved config for a single credit type after applying defaults + overrides. */
+export interface ResolvedLeaseConfig {
+    leaseDuration: number;
+    reservationTTL: number;
+    leaseSize: number;
+    lowWaterMark: number;
+}
+/** Handle returned by `client.check` when a reservation is issued. Pass to `client.trackWithReservation`. */
+export interface Reservation {
+    /** Opaque reservation ID. */
+    id: string;
+    /** Underlying lease ID this reservation draws from. */
+    leaseId: string;
+    /** Company that owns the lease. */
+    companyId: string;
+    /** Credit type the reservation reserves against. */
+    creditTypeId: string;
+    /** Event subtype to record on the Track event when consumed. */
+    eventSubtype: string;
+    /** Quantity (in event units) the caller declared upfront. */
+    quantityReserved: number;
+    /** Credits reserved = `quantityReserved * consumptionRate`. */
+    creditsReserved: number;
+    /** Consumption rate at the time the reservation was issued. */
+    consumptionRate: number;
+    /** When the reservation expires and gets swept back to the lease. */
+    expiresAt: Date;
+    /**
+     * Evaluation context used to issue this reservation. Threaded into the
+     * Track event in `trackWithReservation` so the server can attribute usage
+     * to the same company/user.
+     */
+    evalCtx: api.CheckFlagRequestBody;
+}
+/** Options accepted by `client.check`. */
+export interface CheckOptions {
+    /**
+     * Quantity (in event units) to gate the check on — the check reserves
+     * `usage × consumption_rate` credits from the lease. A check issues at
+     * most ONE reservation, against a single event subtype.
+     */
+    usage?: number;
+    /**
+     * Event subtype the `usage` applies to (e.g. `"inference_tokens"`).
+     * Disambiguates which credit condition to gate on when the flag meters
+     * more than one event. Optional when the flag's credit condition is
+     * unambiguous.
+     */
+    eventSubtype?: string;
+    /**
+     * What to do when a lease cannot be acquired (API error, store
+     * unreachable, insufficient remote balance). Default: `fail-closed`
+     * (`allowed = false`, no reservation) — deny when the gate can't gate.
+     * Override to `fail-open` for trusted/known customers where letting
+     * traffic through is preferable to a denial; the flag's rules are still
+     * evaluated with an assumed-sufficient credit balance, so only the credit
+     * gate is bypassed (see `OnAcquireFailure`).
+     */
+    onAcquireFailure?: OnAcquireFailure;
+    /** Default value to return on error. */
+    defaultValue?: boolean | (() => boolean);
+    /** Custom timeout for API calls within this check (ms). */
+    timeoutMs?: number;
+}
+/** Result of `client.check`. */
+export interface CheckResult {
+    /** Whether the caller is permitted to proceed. */
+    allowed: boolean;
+    /** Boolean flag value (`allowed` mirrors this in non-lease paths). */
+    value: boolean;
+    /** Reservation handle when a lease-bearing check passed. */
+    reservation?: Reservation;
+    /** Human-readable reason (from the rules engine or the SDK). */
+    reason: string;
+    /**
+     * Entitlement payload from the check.
+     *
+     * NOTE: `entitlement.creditRemaining` (and `creditTotal` / `creditUsed`) is
+     * NOT lease-aware and must not be used as a user-facing balance when credit
+     * leases are enabled. The WASM derives those fields from the company's
+     * server `creditBalances`, which a lease distorts: a plain `checkFlag` sees
+     * the balance net of the whole lease tranche (reads low/~0), and a
+     * lease-bearing `check()` sees the substituted *tranche-local* balance, not
+     * the company total. For any "credits remaining" display use
+     * `client.getCreditBalance(...).settled` (`B − spent`), which speaks the
+     * server's `remaining`/`reserved`/`settled` vocabulary.
+     */
+    entitlement?: api.RulesengineFeatureEntitlement;
+    /** Flag key checked. */
+    flagKey: string;
+    /** Flag ID if known. */
+    flagId?: string;
+    /** Optional error string (populated when the SDK fell back to a default). */
+    err?: string;
+}
+/** Extras accepted by `trackWithReservation`. */
+export interface TrackWithReservationOptions {
+    /** Optional traits to attach to the emitted Track event. */
+    traits?: Record<string, unknown>;
+}

package/dist/datastream/datastream-client.d.ts

@@ -1,4 +1,6 @@
 import * as Schematic from '../api/types';
+import { RulesEngineClient } from '../rules-engine';
+import type { CheckFlagOptions } from '../wrapper';
 import { Logger } from '../logger';
 import { LazyEmitter } from './emitter';
 import type { CacheProvider } from '../cache/types';
@@ -9,7 +11,11 @@ import { type RedisClient } from '../cache/redis';
 export interface DataStreamClientOptions {
     /** Schematic API key for authentication */
     apiKey: string;
-    /** Base URL for the API (will be converted to WebSocket URL) */
+    /**
+     * Base URL for the API, converted to its WebSocket counterpart (e.g.
+     * https://api.schematichq.com -> wss://datastream.schematichq.com).
+     * Defaults to the standard Schematic API environment.
+     */
     baseURL?: string;
     /** Logger for debug/info/error messages */
     logger: Logger;
@@ -38,7 +44,7 @@ export interface DataStreamClientOptions {
  */
 export declare class DataStreamClient extends LazyEmitter {
     private readonly apiKey;
-    private readonly baseURL?;
+    private readonly baseURL;
     private readonly logger;
     private readonly cacheTTL;
     private readonly companyCacheProvider;
@@ -106,7 +112,17 @@ export declare class DataStreamClient extends LazyEmitter {
     checkFlag(evalCtx: {
         company?: Record<string, string>;
         user?: Record<string, string>;
-    }, flagKey: string): Promise<Schematic.RulesengineCheckFlagResult>;
+    }, flagKey: string, options?: CheckFlagOptions): Promise<Schematic.RulesengineCheckFlagResult>;
+    /**
+     * Public accessor for the cached company snapshot. Used by credit-lease
+     * callers that need the company's `credit_balances` so they can substitute
+     * a lease-bound view before calling the rules engine.
+     */
+    getCachedCompany(keys: Record<string, string>): Promise<Schematic.RulesengineCompany | null>;
+    /** Public accessor for the cached user snapshot. */
+    getCachedUser(keys: Record<string, string>): Promise<Schematic.RulesengineUser | null>;
+    /** Public accessor for the rules engine. Used by credit-lease eval. */
+    getRulesEngine(): RulesEngineClient;
     /**
      * UpdateCompanyMetrics updates company metrics locally (for track events)
      */

package/dist/datastream/merge.d.ts

@@ -1,11 +1,5 @@
 import type * as Schematic from "../api/types";
-/**
- * Creates a complete deep copy of a Company object.
- */
 export declare function deepCopyCompany(c: Schematic.RulesengineCompany): Schematic.RulesengineCompany;
-/**
- * Creates a complete deep copy of a User object.
- */
 export declare function deepCopyUser(u: Schematic.RulesengineUser): Schematic.RulesengineUser;
 /**
  * Merges a partial update into an existing Company.
@@ -17,13 +11,13 @@ export declare function deepCopyUser(u: Schematic.RulesengineUser): Schematic.Ru
  * Partials don't carry refreshed entitlements, so when their derived fields
  * change in another part of the company we sync them here to match server
  * behavior:
- *   - credit_remaining ← credit_balances[credit_id]
- *   - usage ← metric value matching (event_name, metric_period, month_reset)
+ *   - creditRemaining ← credit_balances[credit_id]
+ *   - usage ← metric value matching (eventName, metricPeriod, monthReset)
  * Both are skipped when the partial also sends entitlements wholesale.
  *
- * Wire format uses snake_case keys. The existing company from cache
- * may have either camelCase or snake_case keys depending on how it
- * was stored.
+ * Partial updates arrive as raw wire payloads (snake_case keys) and are merged
+ * into an existing camelCase-canonicalized entity; each case writes the
+ * corresponding camelCase field so the cached entity stays in a single shape.
  */
 export declare function partialCompany(existing: Schematic.RulesengineCompany, partial: Record<string, unknown>): Schematic.RulesengineCompany;
 /**

package/dist/index.d.ts

@@ -6,4 +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 { verifyWebhookSignature, verifySignature, computeSignature, computeHexSignature, WebhookSignatureError, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER } from "./webhooks";