@schematichq/schematic-typescript-node 1.5.13 → 1.6.1

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

@@ -79,6 +79,7 @@ export * from "./CatalogResponseData";
 export * from "./ChangeSubscriptionInternalRequestBody";
 export * from "./ChangeSubscriptionRequestBody";
 export * from "./ChargeType";
+export * from "./CheckAndReserveFlagResponseData";
 export * from "./CheckFlagRequestBody";
 export * from "./CheckFlagResponseData";
 export * from "./CheckFlagsBulkResponseData";
@@ -169,6 +170,7 @@ export * from "./CreditGrantDetail";
 export * from "./CreditGrantExpiryRequestBody";
 export * from "./CreditGrantSortOrder";
 export * from "./CreditLeaseResponseData";
+export * from "./CreditReservationResponseData";
 export * from "./CreditSpendPolicyResponseData";
 export * from "./CreditSpendPolicyScope";
 export * from "./CreditsAutoTopupCompanySummary";
@@ -251,6 +253,7 @@ export * from "./FeatureUsageLegacyResponseData";
 export * from "./FeatureUsageResponseData";
 export * from "./FeatureUsageTimeSeriesResponseData";
 export * from "./FeatureView";
+export * from "./FlagCheckReservationResponseData";
 export * from "./FlagDetailResponseData";
 export * from "./FlagInPlanResponseData";
 export * from "./FlagResponseData";
@@ -360,7 +363,6 @@ export * from "./PublicPlansResponseData";
 export * from "./QuickstartResp";
 export * from "./RawEventBatchResponseData";
 export * from "./RawEventResponseData";
-export * from "./ReleaseCreditLeaseRequestBody";
 export * from "./Rule";
 export * from "./RuleConditionDetailResponseData";
 export * from "./RuleConditionGroupDetailResponseData";

package/dist/credits/index.d.ts

@@ -3,5 +3,5 @@ export { ReservationStore, type IReservationStore } from "./reservation-store";
 export { CreditLeaseManager } from "./lease-manager";
 export { RedisLeaseStore } from "./redis-lease-store";
 export { RedisReservationStore } from "./redis-reservation-store";
-export { DEFAULT_LEASE_DURATION_MS, DEFAULT_LEASE_SIZE, DEFAULT_LOW_WATER_MARK, DEFAULT_PREWARM_POLL_INTERVAL_MS, DEFAULT_PREWARM_RESOLVE_TIMEOUT_MS, DEFAULT_RESERVATION_TTL_MS, DEFAULT_SWEEP_INTERVAL_MS, } from "./types";
-export type { CreditLeaseConfig, ResolvedLeaseConfig, Reservation, CheckOptions, CheckResult, OnAcquireFailure, TrackWithReservationOptions, } from "./types";
+export { DEFAULT_LEASE_DURATION_MS, DEFAULT_LEASE_SIZE, DEFAULT_LOW_WATER_MARK, DEFAULT_PREWARM_POLL_INTERVAL_MS, DEFAULT_PREWARM_RESOLVE_TIMEOUT_MS, DEFAULT_RESERVATION_TTL_MS, DEFAULT_SWEEP_INTERVAL_MS, MAX_RESERVATION_TTL_MS, RESERVATION_TTL_SKEW_ALLOWANCE_MS, } from "./types";
+export type { CreditLeaseConfig, CreditLeaseMode, ResolvedLeaseConfig, Reservation, CheckOptions, CheckResult, OnAcquireFailure, TrackWithReservationOptions, } from "./types";

package/dist/credits/server-check.d.ts

@@ -0,0 +1,40 @@
+import type * as api from "../api";
+import type { CreditsClient } from "../api/resources/credits/client/Client";
+import type { FeaturesClient } from "../api/resources/features/client/Client";
+import type { Logger } from "../logger";
+import type { CheckOptions, CheckResult } from "./types";
+/** Everything `checkWithServerReservation` needs to satisfy a server-mode check. */
+export interface ServerCheckDeps {
+    features: FeaturesClient;
+    credits: CreditsClient;
+    logger: Logger;
+    /** How far out to set the hold's `expiresAt` (ms). */
+    reservationTTL: number;
+    /**
+     * Resolve the caller's default for this flag — `options.defaultValue` when
+     * set, otherwise the client-level flag default. Used by the fail-open
+     * branch, which has no local engine to re-run.
+     */
+    getDefault: () => boolean;
+}
+/**
+ * Drives a single `client.check` with `usage` set, in server mode.
+ *
+ * One `POST /flags/{key}/check-and-reserve` call does everything the client
+ * path spreads across a lease acquire, a local reserve, and a WASM eval: the
+ * server evaluates the flag against the company's real balance, applies the
+ * preflight cost, and takes the hold — all in the same round-trip. There is no
+ * lease, no local store, and no rules engine involved.
+ *
+ * The failure contract differs from client mode in one place. `fail-open` there
+ * means "re-run the engine with the credit balance assumed sufficient", so plan
+ * targeting and every non-credit condition still apply. Server mode has no
+ * local engine to re-run — the call that would have answered is the one that
+ * failed — so `fail-open` returns the caller's default value
+ * (`options.defaultValue`, else the client's configured flag default) instead.
+ * `fail-closed` denies, same as client mode.
+ *
+ * No `flag_check` event is enqueued here: the server logs the flag check for
+ * check-and-reserve itself, the same way the REST `checkFlag` path does.
+ */
+export declare function checkWithServerReservation(deps: ServerCheckDeps, key: string, evalCtx: api.CheckFlagRequestBody, options: CheckOptions, fallback: () => Promise<CheckResult>): Promise<CheckResult>;

package/dist/credits/track.d.ts

@@ -3,7 +3,7 @@ import type { IReservationStore } from "./reservation-store";
 import type { Reservation, TrackWithReservationOptions } from "./types";
 /** Outcome of consuming a reservation and building its Track event. */
 export interface ReservationConsumeResult {
-    /** The Track event to emit. Always carries the `leaseId`. */
+    /** The Track event to emit. Always carries the `leaseId` (client mode) or the `reservationId` (server mode). */
     track: api.EventBodyTrack;
     /**
      * `true` when the reservation was still live and `consume` debited/refunded

package/dist/credits/types.d.ts

@@ -13,23 +13,46 @@ import type { RedisClient } from "../cache/redis";
 export type OnAcquireFailure = "fail-open" | "fail-closed";
 export declare const DEFAULT_LEASE_DURATION_MS: number;
 export declare const DEFAULT_RESERVATION_TTL_MS: number;
+export declare const MAX_RESERVATION_TTL_MS: number;
+export declare const RESERVATION_TTL_SKEW_ALLOWANCE_MS: number;
 export declare const DEFAULT_LEASE_SIZE: number;
 export declare const DEFAULT_LOW_WATER_MARK: number;
 export declare const DEFAULT_SWEEP_INTERVAL_MS: number;
 export declare const DEFAULT_PREWARM_RESOLVE_TIMEOUT_MS: number;
 export declare const DEFAULT_PREWARM_POLL_INTERVAL_MS: number;
+/**
+ * Where a credit hold lives for a `check()` that passes `usage`.
+ * - `client`: local leases over DataStream — the SDK acquires a tranche of
+ *   credits up front and carves reservations out of it locally (today's
+ *   behavior). Requires DataStream (or replicator mode), and a shared Redis
+ *   backend to gate across pods.
+ * - `server`: one `check-and-reserve` API call per check — the server
+ *   evaluates the flag and takes the hold in the same round-trip. No
+ *   DataStream, no Redis, no local stores.
+ * - `auto` (default): `client` when DataStream is enabled, `server` otherwise.
+ */
+export type CreditLeaseMode = "client" | "server" | "auto";
 /**
  * Configuration block enabling client-side lease + reservation behavior on
  * `client.check` / `client.trackWithReservation`. Omit to keep the SDK
  * lease-unaware (`check` falls back to a plain flag check).
  */
 export interface CreditLeaseConfig {
+    /**
+     * Where the credit hold lives. Default `auto` — client mode when
+     * DataStream is enabled, server mode otherwise. See `CreditLeaseMode`.
+     */
+    mode?: CreditLeaseMode;
     /** Default lease duration in milliseconds. Default `DEFAULT_LEASE_DURATION_MS` (5 minutes). */
     defaultLeaseDuration?: number;
     /**
      * Default reservation TTL in milliseconds. Default `DEFAULT_RESERVATION_TTL_MS`
-     * (60 seconds). Size this above the longest expected gap between `check()`
-     * and `trackWithReservation()`: a settle arriving after the TTL still bills
+     * (60 seconds). In server mode it is capped at `MAX_RESERVATION_TTL_MS`
+     * (1 hour) less `RESERVATION_TTL_SKEW_ALLOWANCE_MS`, since an hour out is
+     * the furthest the API will hold credits and it measures that against its
+     * own clock. Size this above the
+     * longest expected gap between `check()` and `trackWithReservation()`: a
+     * settle arriving after the TTL still bills
      * the server but doesn't re-debit the local lease (its hold was already
      * swept back), so the local balance reads high until the lease rolls over.
      */
@@ -71,7 +94,7 @@ export interface CreditLeaseConfig {
      */
     redisKeyPrefix?: string;
     /** Per-credit-type overrides (keyed by credit type ID). */
-    overrides?: Record<string, Partial<Omit<CreditLeaseConfig, "overrides" | "sweepIntervalMs" | "redisClient" | "redisKeyPrefix">>>;
+    overrides?: Record<string, Partial<Omit<CreditLeaseConfig, "overrides" | "mode" | "sweepIntervalMs" | "redisClient" | "redisKeyPrefix">>>;
 }
 /** Resolved config for a single credit type after applying defaults + overrides. */
 export interface ResolvedLeaseConfig {
@@ -84,8 +107,17 @@ export interface ResolvedLeaseConfig {
 export interface Reservation {
     /** Opaque reservation ID. */
     id: string;
-    /** Underlying lease ID this reservation draws from. */
+    /**
+     * Underlying lease ID this reservation draws from. In server mode there is
+     * no lease — this mirrors `id` so the field stays populated.
+     */
     leaseId: string;
+    /**
+     * Where the hold lives. `server` means the API holds the credits and the
+     * settling Track event routes by `reservation_id`; absent (or `client`)
+     * means the hold is a local carve-out of a lease.
+     */
+    mode?: "client" | "server";
     /** Company that owns the lease. */
     companyId: string;
     /** Credit type the reservation reserves against. */

package/dist/index.d.ts

@@ -6,5 +6,5 @@ export { ConsoleLogger, LogLevel, type Logger } from "./logger";
 export { SchematicEnvironment } from "./environments";
 export { SchematicError, SchematicTimeoutError } from "./errors";
 export { RulesEngineClient } from "./rules-engine";
-export type { CheckOptions, CheckResult, CreditLeaseConfig, OnAcquireFailure, Reservation, TrackWithReservationOptions, } from "./credits";
+export type { CheckOptions, CheckResult, CreditLeaseConfig, CreditLeaseMode, OnAcquireFailure, Reservation, TrackWithReservationOptions, } from "./credits";
 export { verifyWebhookSignature, verifySignature, computeSignature, computeHexSignature, WebhookSignatureError, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER } from "./webhooks";