@schematichq/schematic-typescript-node 1.4.8 → 1.5.1

package/dist/wrapper.d.ts

@@ -3,6 +3,7 @@ import { SchematicClient as BaseClient } from "./Client";
 import { type CacheProvider } from "./cache";
 import { type Logger, type LogLevel } from "./logger";
 import type { RedisClient } from "./cache/redis";
+import { type CheckOptions, type CheckResult, type CreditLeaseConfig, type Reservation, type TrackWithReservationOptions } from "./credits";
 /**
  * Configuration options for the SchematicClient
  */
@@ -53,12 +54,42 @@ export interface SchematicOptions {
     offline?: boolean;
     /** The default maximum time to wait for a response in milliseconds */
     timeoutMs?: number;
+    /**
+     * Enable client-side credit lease + reservation behavior on `check` /
+     * `trackWithReservation`. Omit to keep the SDK lease-unaware.
+     *
+     * Lease-bearing checks require DataStream (or replicator mode) so the
+     * SDK has access to the cached flag + company state needed for local
+     * gating against the lease balance.
+     */
+    creditLeases?: CreditLeaseConfig;
 }
 export interface CheckFlagOptions {
     /** Default value to return on error. Can be a boolean or a function returning a boolean. If not provided, uses configured flag defaults */
     defaultValue?: boolean | (() => boolean);
     /** The maximum time to wait for a response in milliseconds */
     timeoutMs?: number;
+    /**
+     * Preflight inputs forwarded to the WASM rules engine's
+     * `checkFlagWithOptions`. The engine picks the most specific knob for each
+     * condition it evaluates. Only applied when the flag is evaluated locally
+     * (DataStream); the REST fallback path does not support preflight and
+     * ignores these. No reservation is issued — for lease-backed gating use
+     * `check()` instead.
+     */
+    /** Pre-computed per-credit-id cost. Highest precedence for credit-balance gates. */
+    creditCost?: Record<string, number>;
+    /** Single integer quantity applied to whatever numeric condition is being evaluated. */
+    usage?: number;
+    /**
+     * Simulated quantity scoped to a specific event subtype. Preferred over
+     * `usage` when the subtype is known. Deliberately singular: one check
+     * preflights one action.
+     */
+    eventUsage?: {
+        eventSubtype: string;
+        quantity: number;
+    };
 }
 /**
  * Optional metadata for a track event. Only fields that are explicitly set are
@@ -81,6 +112,14 @@ export interface TrackOptions {
 export interface IdentifyOptions {
     /** Client-supplied dedupe key. Duplicate events with the same key (scoped to the environment) are dropped server-side for 24 hours. */
     idempotencyKey?: string;
+    /**
+     * Credit type IDs to acquire leases for in the background after the
+     * identify event is enqueued. Fire-and-forget — failures are logged but
+     * never surface to the caller. Equivalent to calling `client.prewarm()`
+     * directly with the same evalCtx and creditTypeIds. No-op unless
+     * `creditLeases` is configured on the client.
+     */
+    prewarm?: string[];
 }
 export interface CheckFlagWithEntitlementResponse {
     companyId?: string;
@@ -101,6 +140,11 @@ export declare class SchematicClient extends BaseClient {
     private flagDefaults;
     private logger;
     private offline;
+    private creditLeaseManager?;
+    private leaseStore?;
+    private reservations?;
+    private leaseBackendShared;
+    private prewarmResolveTimeoutMs;
     /**
      * Creates a new instance of the SchematicClient
      * @param opts - Configuration options for the client
@@ -144,16 +188,124 @@ export declare class SchematicClient extends BaseClient {
      */
     private checkFlagsViaDataStream;
     /**
-     * Gracefully shuts down the client by stopping the event buffer and DataStream client
+     * Gracefully shuts down the client by stopping the event buffer, the
+     * reservation sweeper, and the DataStream client.
+     *
+     * Credit leases: with the per-process in-memory backend, this process is
+     * the only holder of its leases, so they are released here (best-effort) —
+     * their unspent remainder returns to the company balance immediately
+     * instead of waiting out the lease expiry. With a shared (Redis) backend,
+     * leases are deliberately *not* released: a lease is shared across every
+     * SDK instance pointed at the same backend (one row per company+credit),
+     * so a single pod shutting down must not release a lease that sibling pods
+     * are still drawing on — doing so would refund the grant server-side and
+     * pull the balance out from under them. Shared leases reclaim themselves:
+     * they expire (client- and server-side) or are fully consumed.
      * @returns Promise that resolves when everything has been stopped
      */
     close(): Promise<void>;
     /**
-     * Send a non-blocking event to create or update companies and users
-     * @param body - The identify event payload containing user properties
-     * @param options - Optional event metadata (e.g. idempotencyKey)
-     * @returns Promise that resolves when the event has been enqueued
-     * @throws Will log error if event enqueueing fails
+     * Pre-warm a credit lease for each given credit type ID, so the first
+     * `check()` against it doesn't pay the acquire round-trip. Fire-and-forget
+     * — failures are logged but don't throw.
+     *
+     * When `evalCtx.company` carries only secondary keys (no `id`), `prewarm`
+     * actively fetches the company over the datastream (waiting up to
+     * `creditLeases.prewarmResolveTimeoutMs` for the WS to connect), which both
+     * resolves the id and warms the cache so the first `check()` hits the lease
+     * path. Covers a brand-new company too: the fetch retries until the server
+     * has ingested the preceding `identify` and can stream it back.
+     */
+    prewarm(evalCtx: api.CheckFlagRequestBody, creditTypeIds: string[]): Promise<void>;
+    /**
+     * Like `resolveCompanyId` but actively fetches the company over the
+     * datastream when only secondary keys are supplied, warming the cache as a
+     * side effect. Returns the resolved id, or undefined if the company never
+     * surfaced within `prewarmResolveTimeoutMs`.
+     *
+     * `identify` does not push a company into the datastream cache —  companies
+     * are only streamed in response to a request. So we call `getCompany`
+     * (cache-first, then sends the request and awaits the push) rather than
+     * passively polling `getCachedCompany`, which would watch an empty cache
+     * until it times out. Fetching also primes the cache so the first real
+     * `check()` hits the lease path instead of falling back.
+     */
+    private resolveCompanyIdWithWait;
+    /**
+     * Lease-aware feature check. When `creditLeases` is configured and the
+     * caller passes `usage` (optionally qualified by `eventSubtype`), this
+     * acquires a lease (if needed), gates the check against the lease's local
+     * balance via WASM, and returns a reservation handle on success — pass
+     * that handle to `trackWithReservation` when the work completes.
+     *
+     * When `creditLeases` is not configured (or `usage` is omitted) this falls
+     * through to a plain flag check and returns `{allowed: value}` with no
+     * reservation, byte-compatible with `checkFlag` semantics. The caller's
+     * preflight (`usage` / `eventSubtype`) is still threaded through the plain
+     * check, so any client-side evaluation path (datastream, replicator)
+     * gates on the post-call balance — just without a reservation. Only the
+     * REST fallback ignores preflight.
+     */
+    check(evalCtx: api.CheckFlagRequestBody, key: string, options?: CheckOptions): Promise<CheckResult>;
+    /**
+     * Consume a reservation issued by `check()`. Refunds the unused slice
+     * (`creditsReserved - actualQuantity * consumptionRate`) back to the
+     * lease's local balance and enqueues a Track event with
+     * `quantity = actualQuantity`. The server-side event processor consumes
+     * `actualQuantity × consumption_rate` from the company's real credit
+     * balance.
+     *
+     * If the work outlived the reservation's TTL and the sweeper already
+     * returned the hold to the lease, the local refund has happened but the
+     * usage must still be billed — so we emit the Track anyway (a "recovery"
+     * emit). The server bills it against the lease's sub-ledger if the lease is
+     * still live, or falls through to a direct grant decrement if the server
+     * lease has itself expired.
+     *
+     * Double-billing is prevented server-side: the Track carries a deterministic
+     * `idempotencyKey` derived from the reservation id, and the events pipeline
+     * drops duplicates by `(account, env, event_type, key)` for 24h before any
+     * credit consumption runs. So a recovery emit racing the normal emit, or an
+     * accidental second `trackWithReservation`, collapses to a single billed
+     * event — across pods and process restarts, not just within one process.
+     */
+    trackWithReservation(reservation: Reservation, actualQuantity: number, options?: TrackWithReservationOptions): Promise<void>;
+    /**
+     * Lease-aware credit balance for display, in the same three-way split the
+     * server exposes on `listCompanyCreditBalances`:
+     *
+     *   - `remaining`: credits available to draw right now — the server balance
+     *     (`company.creditBalances[creditId]`, already net of any active lease
+     *     tranche): `B − L`.
+     *   - `reserved`: the active lease's unsettled hold — its unspent local
+     *     balance plus open reservations (`L − spent`), reported as the
+     *     aggregate the server models.
+     *   - `settled`: the economic balance the end user should see —
+     *     `remaining + reserved = B − spent`. Invariant to in-flight holds, so
+     *     a counter bound to it doesn't dip mid-call.
+     *
+     * Bind a user-facing "credits remaining" counter to `settled`: the server
+     * balance alone reads low (or 0) while a lease still has unspent balance.
+     *
+     * `reserved` is 0 when no lease is held or the held lease has expired — the
+     * server refunds an expired lease's unspent hold into the balance, so
+     * counting a stale local entry would double-count. Returns zeros when
+     * credit leases / datastream aren't configured or the company can't be
+     * resolved. The `reserved` term comes from this process's lease +
+     * reservation stores, so it (and `settled`) is per-process unless
+     * Redis-backed stores are configured.
+     */
+    getCreditBalance(company: Record<string, string>, creditId: string): Promise<{
+        remaining: number;
+        reserved: number;
+        settled: number;
+    }>;
+    private resolveCompanyId;
+    /**
+     * Send a non-blocking event to create or update companies and users.
+     * Pass `options.prewarm` with credit type IDs to kick off lease acquires in
+     * the background after the identify event is enqueued (no-op unless
+     * `creditLeases` is configured on the client).
      */
     identify(body: api.EventBodyIdentify, options?: IdentifyOptions): Promise<void>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@schematichq/schematic-typescript-node",
-    "version": "1.4.8",
+    "version": "1.5.1",
     "private": false,
     "repository": {
         "type": "git",
@@ -28,8 +28,7 @@
         "formdata-node": "^6.0.3",
         "node-fetch": "^2.7.0",
         "readable-stream": "^4.7.0",
-        "ws": "^8.18.1",
-        "@types/ws": "^8.18.1"
+        "ws": "^8.18.1"
     },
     "devDependencies": {
         "@types/node-fetch": "^2.6.12",
@@ -46,7 +45,9 @@
         "typescript": "~5.9.3",
         "@biomejs/biome": "2.4.10",
         "esbuild": "^0.25.9",
-        "miniflare": "^4.20260421.0"
+        "miniflare": "^4.20260421.0",
+        "redis": "^4.7.0",
+        "@types/ws": "^8.18.1"
     },
     "browser": {
         "fs": false,

package/dist/api/resources/credits/client/requests/CountCreditLedgerRequest.d.ts

@@ -1,26 +0,0 @@
-import type * as Schematic from "../../../../index";
-/**
- * @example
- *     {
- *         companyId: "company_id",
- *         billingCreditId: "billing_credit_id",
- *         featureId: "feature_id",
- *         period: "daily",
- *         startTime: "start_time",
- *         endTime: "end_time",
- *         limit: 1000000,
- *         offset: 1000000
- *     }
- */
-export interface CountCreditLedgerRequest {
-    companyId: string;
-    billingCreditId?: string;
-    featureId?: string;
-    period: Schematic.CreditLedgerPeriod;
-    startTime?: string;
-    endTime?: string;
-    /** Page limit (default 100) */
-    limit?: number;
-    /** Page offset (default 0) */
-    offset?: number;
-}

package/dist/api/resources/credits/client/requests/GetEnrichedCreditLedgerRequest.d.ts

@@ -1,26 +0,0 @@
-import type * as Schematic from "../../../../index";
-/**
- * @example
- *     {
- *         companyId: "company_id",
- *         billingCreditId: "billing_credit_id",
- *         featureId: "feature_id",
- *         period: "daily",
- *         startTime: "start_time",
- *         endTime: "end_time",
- *         limit: 1000000,
- *         offset: 1000000
- *     }
- */
-export interface GetEnrichedCreditLedgerRequest {
-    companyId: string;
-    billingCreditId?: string;
-    featureId?: string;
-    period: Schematic.CreditLedgerPeriod;
-    startTime?: string;
-    endTime?: string;
-    /** Page limit (default 100) */
-    limit?: number;
-    /** Page offset (default 0) */
-    offset?: number;
-}

package/dist/api/resources/credits/types/CountCreditLedgerParams.d.ts

@@ -1,16 +0,0 @@
-import type * as Schematic from "../../../index";
-/**
- * Input parameters
- */
-export interface CountCreditLedgerParams {
-    billingCreditId?: string;
-    companyId?: string;
-    endTime?: string;
-    featureId?: string;
-    /** Page limit (default 100) */
-    limit?: number;
-    /** Page offset (default 0) */
-    offset?: number;
-    period?: Schematic.CreditLedgerPeriod;
-    startTime?: string;
-}

package/dist/api/resources/credits/types/CountCreditLedgerResponse.d.ts

@@ -1,6 +0,0 @@
-import type * as Schematic from "../../../index";
-export interface CountCreditLedgerResponse {
-    data: Schematic.CountResponse;
-    /** Input parameters */
-    params: Schematic.CountCreditLedgerParams;
-}

package/dist/api/resources/credits/types/GetEnrichedCreditLedgerParams.d.ts

@@ -1,16 +0,0 @@
-import type * as Schematic from "../../../index";
-/**
- * Input parameters
- */
-export interface GetEnrichedCreditLedgerParams {
-    billingCreditId?: string;
-    companyId?: string;
-    endTime?: string;
-    featureId?: string;
-    /** Page limit (default 100) */
-    limit?: number;
-    /** Page offset (default 0) */
-    offset?: number;
-    period?: Schematic.CreditLedgerPeriod;
-    startTime?: string;
-}

package/dist/api/resources/credits/types/GetEnrichedCreditLedgerResponse.d.ts

@@ -1,6 +0,0 @@
-import type * as Schematic from "../../../index";
-export interface GetEnrichedCreditLedgerResponse {
-    data: Schematic.CreditLedgerEnrichedEntryResponseData[];
-    /** Input parameters */
-    params: Schematic.GetEnrichedCreditLedgerParams;
-}

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

@@ -1,25 +0,0 @@
-import type * as Schematic from "../index";
-export interface CreditLedgerEnrichedEntryResponseData {
-    billingCreditAutoTopupGrantCount: number;
-    billingCreditId: string;
-    company?: Schematic.CompanyLedgerResponseData;
-    companyId: string;
-    credit?: Schematic.BillingCreditLedgerResponseData;
-    expiredGrantCount: number;
-    feature?: Schematic.FeatureLedgerResponseData;
-    featureId?: string;
-    firstTransactionAt: Date;
-    freeGrantCount: number;
-    grantCount: number;
-    lastTransactionAt: Date;
-    manuallyZeroedCount: number;
-    netChange: number;
-    planGrantCount: number;
-    purchasedGrantCount: number;
-    timeBucket: Date;
-    totalConsumed: number;
-    totalGranted: number;
-    transactionCount: number;
-    usageCount: number;
-    zeroedOutCount: number;
-}

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

@@ -1,7 +0,0 @@
-export declare const CreditLedgerPeriod: {
-    readonly Daily: "daily";
-    readonly Monthly: "monthly";
-    readonly Raw: "raw";
-    readonly Weekly: "weekly";
-};
-export type CreditLedgerPeriod = (typeof CreditLedgerPeriod)[keyof typeof CreditLedgerPeriod];

package/dist/serialization/resources/credits/types/CountCreditLedgerParams.d.ts

@@ -1,17 +0,0 @@
-import type * as Schematic from "../../../../api/index";
-import * as core from "../../../../core";
-import type * as serializers from "../../../index";
-import { CreditLedgerPeriod } from "../../../types/CreditLedgerPeriod";
-export declare const CountCreditLedgerParams: core.serialization.ObjectSchema<serializers.CountCreditLedgerParams.Raw, Schematic.CountCreditLedgerParams>;
-export declare namespace CountCreditLedgerParams {
-    interface Raw {
-        billing_credit_id?: string | null;
-        company_id?: string | null;
-        end_time?: string | null;
-        feature_id?: string | null;
-        limit?: number | null;
-        offset?: number | null;
-        period?: CreditLedgerPeriod.Raw | null;
-        start_time?: string | null;
-    }
-}

package/dist/serialization/resources/credits/types/CountCreditLedgerResponse.d.ts

@@ -1,12 +0,0 @@
-import type * as Schematic from "../../../../api/index";
-import * as core from "../../../../core";
-import type * as serializers from "../../../index";
-import { CountResponse } from "../../../types/CountResponse";
-import { CountCreditLedgerParams } from "./CountCreditLedgerParams";
-export declare const CountCreditLedgerResponse: core.serialization.ObjectSchema<serializers.CountCreditLedgerResponse.Raw, Schematic.CountCreditLedgerResponse>;
-export declare namespace CountCreditLedgerResponse {
-    interface Raw {
-        data: CountResponse.Raw;
-        params: CountCreditLedgerParams.Raw;
-    }
-}

package/dist/serialization/resources/credits/types/GetEnrichedCreditLedgerParams.d.ts

@@ -1,17 +0,0 @@
-import type * as Schematic from "../../../../api/index";
-import * as core from "../../../../core";
-import type * as serializers from "../../../index";
-import { CreditLedgerPeriod } from "../../../types/CreditLedgerPeriod";
-export declare const GetEnrichedCreditLedgerParams: core.serialization.ObjectSchema<serializers.GetEnrichedCreditLedgerParams.Raw, Schematic.GetEnrichedCreditLedgerParams>;
-export declare namespace GetEnrichedCreditLedgerParams {
-    interface Raw {
-        billing_credit_id?: string | null;
-        company_id?: string | null;
-        end_time?: string | null;
-        feature_id?: string | null;
-        limit?: number | null;
-        offset?: number | null;
-        period?: CreditLedgerPeriod.Raw | null;
-        start_time?: string | null;
-    }
-}

package/dist/serialization/resources/credits/types/GetEnrichedCreditLedgerResponse.d.ts

@@ -1,12 +0,0 @@
-import type * as Schematic from "../../../../api/index";
-import * as core from "../../../../core";
-import type * as serializers from "../../../index";
-import { CreditLedgerEnrichedEntryResponseData } from "../../../types/CreditLedgerEnrichedEntryResponseData";
-import { GetEnrichedCreditLedgerParams } from "./GetEnrichedCreditLedgerParams";
-export declare const GetEnrichedCreditLedgerResponse: core.serialization.ObjectSchema<serializers.GetEnrichedCreditLedgerResponse.Raw, Schematic.GetEnrichedCreditLedgerResponse>;
-export declare namespace GetEnrichedCreditLedgerResponse {
-    interface Raw {
-        data: CreditLedgerEnrichedEntryResponseData.Raw[];
-        params: GetEnrichedCreditLedgerParams.Raw;
-    }
-}

package/dist/serialization/types/CreditLedgerEnrichedEntryResponseData.d.ts

@@ -1,33 +0,0 @@
-import type * as Schematic from "../../api/index";
-import * as core from "../../core";
-import type * as serializers from "../index";
-import { BillingCreditLedgerResponseData } from "./BillingCreditLedgerResponseData";
-import { CompanyLedgerResponseData } from "./CompanyLedgerResponseData";
-import { FeatureLedgerResponseData } from "./FeatureLedgerResponseData";
-export declare const CreditLedgerEnrichedEntryResponseData: core.serialization.ObjectSchema<serializers.CreditLedgerEnrichedEntryResponseData.Raw, Schematic.CreditLedgerEnrichedEntryResponseData>;
-export declare namespace CreditLedgerEnrichedEntryResponseData {
-    interface Raw {
-        billing_credit_auto_topup_grant_count: number;
-        billing_credit_id: string;
-        company?: CompanyLedgerResponseData.Raw | null;
-        company_id: string;
-        credit?: BillingCreditLedgerResponseData.Raw | null;
-        expired_grant_count: number;
-        feature?: FeatureLedgerResponseData.Raw | null;
-        feature_id?: string | null;
-        first_transaction_at: string;
-        free_grant_count: number;
-        grant_count: number;
-        last_transaction_at: string;
-        manually_zeroed_count: number;
-        net_change: number;
-        plan_grant_count: number;
-        purchased_grant_count: number;
-        time_bucket: string;
-        total_consumed: number;
-        total_granted: number;
-        transaction_count: number;
-        usage_count: number;
-        zeroed_out_count: number;
-    }
-}

package/dist/serialization/types/CreditLedgerPeriod.d.ts

@@ -1,7 +0,0 @@
-import type * as Schematic from "../../api/index";
-import * as core from "../../core";
-import type * as serializers from "../index";
-export declare const CreditLedgerPeriod: core.serialization.Schema<serializers.CreditLedgerPeriod.Raw, Schematic.CreditLedgerPeriod>;
-export declare namespace CreditLedgerPeriod {
-    type Raw = "daily" | "monthly" | "raw" | "weekly";
-}