@schematichq/schematic-typescript-node 1.6.0 → 1.6.2

package/dist/wrapper.d.ts

@@ -55,36 +55,51 @@ export interface SchematicOptions {
     /** 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.
+     * Enable credit reservation behavior on `check` / `trackWithReservation`.
+     * Omit to keep the SDK credit-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.
+     * Client mode (local leases) requires DataStream (or replicator mode) so
+     * the SDK has the cached flag + company state it needs to gate locally
+     * against the lease balance. Without DataStream the SDK gates in server
+     * mode instead — one `check-and-reserve` API call per check. See
+     * `CreditLeaseConfig.mode`.
      */
     creditLeases?: CreditLeaseConfig;
 }
+/**
+ * Options for a single flag check.
+ *
+ * `creditCost`, `usage` and `eventUsage` are preflight inputs: they ask
+ * "would this action be allowed?" rather than "is it allowed now". They apply
+ * on every evaluation path, forwarded to the WASM rules engine's
+ * `checkFlagWithOptions` when the flag is evaluated locally (DataStream) and
+ * sent as the request body's `preflight` when it is evaluated over the REST
+ * API. The engine picks the most specific knob for each condition it
+ * evaluates. No reservation is issued; for lease-backed gating use `check()`.
+ */
 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 cost of the action, keyed by credit id. Highest precedence
+     * for credit-balance gates. A cost of zero means the action is free, not
+     * that the input is absent.
      */
-    /** 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. */
+    /**
+     * Quantity applied to whatever numeric condition is being evaluated. Zero
+     * has no effect. Both the REST request body and the local (WASM) engine
+     * take an integer, so a fraction rounds up rather than letting the check
+     * pass on less usage than the action is about to record.
+     */
     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.
+     * preflights one action. `quantity` rounds up the same way `usage` does,
+     * and zero has no effect.
      */
     eventUsage?: {
         eventSubtype: string;
@@ -145,6 +160,10 @@ export declare class SchematicClient extends BaseClient {
     private reservations?;
     private leaseBackendShared;
     private prewarmResolveTimeoutMs;
+    private creditLeaseMode?;
+    private serverReservationTTL;
+    private closing;
+    private readonly pendingPrewarms;
     /**
      * Creates a new instance of the SchematicClient
      * @param opts - Configuration options for the client
@@ -154,6 +173,23 @@ export declare class SchematicClient extends BaseClient {
      * Returns whether DataStream is enabled and available
      */
     private useDataStream;
+    /**
+     * Whether the configured mode wants the local lease plumbing (stores,
+     * manager, sweeper). Read during construction, after the DataStream client
+     * has been wired, so `auto` can resolve against it.
+     */
+    private creditLeaseModeUsesLeases;
+    /**
+     * Which reservation mode a `check()` with `usage` resolves to right now.
+     * `undefined` means no credit gating at all — `creditLeases` isn't
+     * configured, or the client is offline.
+     *
+     * `auto` is resolved per check rather than once at startup so a DataStream
+     * that failed to start after construction (its `start()` rejection clears
+     * `datastreamClient`) falls to server mode instead of silently dropping
+     * every check to a plain, ungated flag check.
+     */
+    private effectiveLeaseMode;
     /**
      * Checks the value of a feature flag for the given evaluation context
      * @param evalCtx - The context (company and/or user) for evaluating the feature flag
@@ -201,6 +237,11 @@ export declare class SchematicClient extends BaseClient {
      * 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.
+     *
+     * Lease work already in flight is waited out before the release, so an
+     * acquire that lands mid-shutdown is one the release can see. The wait and
+     * the release share one `SHUTDOWN_DRAIN_TIMEOUT_MS` budget, so close()
+     * stays bounded however slow the store or the wire is.
      * @returns Promise that resolves when everything has been stopped
      */
     close(): Promise<void>;
@@ -218,10 +259,10 @@ export declare class SchematicClient extends BaseClient {
      */
     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`.
+     * Like `resolveCompanyId` but, on a cache miss, actively fetches the
+     * company over the datastream, warming the cache as a side effect. Returns
+     * the resolved id, the `comp_`-prefixed id the keys carry if the company
+     * never surfaced within `prewarmResolveTimeoutMs`, or undefined.
      *
      * `identify` does not push a company into the datastream cache —  companies
      * are only streamed in response to a request. So we call `getCompany`
@@ -232,19 +273,24 @@ export declare class SchematicClient extends BaseClient {
      */
     private resolveCompanyIdWithWait;
     /**
-     * Lease-aware feature check. When `creditLeases` is configured and the
+     * Credit-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.
+     * gates the check against the company's credit balance and returns a
+     * reservation handle on success — pass that handle to
+     * `trackWithReservation` when the work completes.
+     *
+     * In client mode (DataStream enabled) the hold is carved out of a local
+     * lease and the flag is evaluated by the WASM engine. In server mode it is
+     * a single `check-and-reserve` API call that evaluates the flag and takes
+     * the hold server-side. `creditLeases.mode` picks; the default (`auto`)
+     * uses client mode when DataStream is enabled and server mode otherwise.
      *
      * 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, so every evaluation path (datastream, replicator, REST) gates on
+     * the post-call balance — just without a reservation.
      */
     check(evalCtx: api.CheckFlagRequestBody, key: string, options?: CheckOptions): Promise<CheckResult>;
     /**
@@ -255,6 +301,10 @@ export declare class SchematicClient extends BaseClient {
      * `actualQuantity × consumption_rate` from the company's real credit
      * balance.
      *
+     * A server-mode handle has no local hold to refund: the Track event carries
+     * the reservation id, and the server settles the hold (refunding the
+     * unspent slice) when it processes the event.
+     *
      * 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"
@@ -269,7 +319,15 @@ export declare class SchematicClient extends BaseClient {
      * 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>;
+    trackWithReservation(reservation: Reservation | undefined, actualQuantity: number, options?: TrackWithReservationOptions): Promise<void>;
+    /**
+     * The Schematic company id for an evaluation context, resolved in the
+     * server's order: every supplied key/value pair is an ordinary entity key
+     * and gets looked up first; only when nothing matches is a value read as
+     * the company's own id, by its `comp_` prefix rather than by the name of
+     * the key it sits under. An account is free to define a key called `id`
+     * holding its own identifier, so the name alone settles nothing.
+     */
     private resolveCompanyId;
     /**
      * Send a non-blocking event to create or update companies and users.
@@ -286,6 +344,13 @@ export declare class SchematicClient extends BaseClient {
      * @throws Will log error if event enqueueing fails
      */
     track(body: api.EventBodyTrack, options?: TrackOptions): Promise<void>;
+    /**
+     * Enqueue a track event, optimistically bumping the cached company metric
+     * with it unless `updateMetrics` says not to. The bump is a local
+     * prediction of what the stream will push back, so it belongs only to an
+     * event that records usage the server has not already counted.
+     */
+    private emitTrack;
     /**
      * Sets the default value for a specific feature flag
      * @param flag - The feature flag identifier

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@schematichq/schematic-typescript-node",
-    "version": "1.6.0",
+    "version": "1.6.2",
     "private": false,
     "repository": {
         "type": "git",
@@ -57,6 +57,10 @@
         "crypto": false,
         "timers": false
     },
+    "resolutions": {
+        "sharp": "^0.35.4",
+        "undici": "7.29.0"
+    },
     "packageManager": "yarn@1.22.22",
     "engines": {
         "node": ">=18.0.0"