@schematichq/schematic-typescript-node 1.4.8 → 1.5.1

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/Client.d.ts

@@ -69,6 +69,14 @@ export declare class SchematicClient {
     get scheduledcheckout(): ScheduledcheckoutClient;
     get accesstokens(): AccesstokensClient;
     get webhooks(): WebhooksClient;
+    /**
+     * @param {SchematicClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @example
+     *     await client.getCreditLedger()
+     */
+    getCreditLedger(requestOptions?: SchematicClient.RequestOptions): core.HttpResponsePromise<void>;
+    private __getCreditLedger;
     /**
      * Make a passthrough request using the SDK's configured auth, retry, logging, etc.
      * This is useful for making requests to endpoints not yet supported in the SDK.

package/dist/api/resources/credits/client/Client.d.ts

@@ -419,54 +419,6 @@ export declare class CreditsClient {
      */
     releaseCreditLease(lease_id: string, request: Schematic.ReleaseCreditLeaseRequestBody, requestOptions?: CreditsClient.RequestOptions): core.HttpResponsePromise<Schematic.ReleaseCreditLeaseResponse>;
     private __releaseCreditLease;
-    /**
-     * @param {Schematic.GetEnrichedCreditLedgerRequest} request
-     * @param {CreditsClient.RequestOptions} requestOptions - Request-specific configuration.
-     *
-     * @throws {@link Schematic.BadRequestError}
-     * @throws {@link Schematic.UnauthorizedError}
-     * @throws {@link Schematic.ForbiddenError}
-     * @throws {@link Schematic.NotFoundError}
-     * @throws {@link Schematic.InternalServerError}
-     *
-     * @example
-     *     await client.credits.getEnrichedCreditLedger({
-     *         companyId: "company_id",
-     *         billingCreditId: "billing_credit_id",
-     *         featureId: "feature_id",
-     *         period: "daily",
-     *         startTime: "start_time",
-     *         endTime: "end_time",
-     *         limit: 1000000,
-     *         offset: 1000000
-     *     })
-     */
-    getEnrichedCreditLedger(request: Schematic.GetEnrichedCreditLedgerRequest, requestOptions?: CreditsClient.RequestOptions): core.HttpResponsePromise<Schematic.GetEnrichedCreditLedgerResponse>;
-    private __getEnrichedCreditLedger;
-    /**
-     * @param {Schematic.CountCreditLedgerRequest} request
-     * @param {CreditsClient.RequestOptions} requestOptions - Request-specific configuration.
-     *
-     * @throws {@link Schematic.BadRequestError}
-     * @throws {@link Schematic.UnauthorizedError}
-     * @throws {@link Schematic.ForbiddenError}
-     * @throws {@link Schematic.NotFoundError}
-     * @throws {@link Schematic.InternalServerError}
-     *
-     * @example
-     *     await client.credits.countCreditLedger({
-     *         companyId: "company_id",
-     *         billingCreditId: "billing_credit_id",
-     *         featureId: "feature_id",
-     *         period: "daily",
-     *         startTime: "start_time",
-     *         endTime: "end_time",
-     *         limit: 1000000,
-     *         offset: 1000000
-     *     })
-     */
-    countCreditLedger(request: Schematic.CountCreditLedgerRequest, requestOptions?: CreditsClient.RequestOptions): core.HttpResponsePromise<Schematic.CountCreditLedgerResponse>;
-    private __countCreditLedger;
     /**
      * @param {Schematic.ListBillingPlanCreditGrantsRequest} request
      * @param {CreditsClient.RequestOptions} requestOptions - Request-specific configuration.

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

@@ -5,13 +5,11 @@ export type { CountBillingPlanCreditGrantsRequest } from "./CountBillingPlanCred
 export type { CountCompanyGrantsRequest } from "./CountCompanyGrantsRequest";
 export type { CountCreditBundlesRequest } from "./CountCreditBundlesRequest";
 export type { CountCreditEventLedgerRequest } from "./CountCreditEventLedgerRequest";
-export type { CountCreditLedgerRequest } from "./CountCreditLedgerRequest";
 export type { CreateBillingCreditRequestBody } from "./CreateBillingCreditRequestBody";
 export type { CreateCompanyCreditGrant } from "./CreateCompanyCreditGrant";
 export type { CreateCreditBundleRequestBody } from "./CreateCreditBundleRequestBody";
 export type { DeleteBillingPlanCreditGrantRequest } from "./DeleteBillingPlanCreditGrantRequest";
 export type { ExtendCreditLeaseRequestBody } from "./ExtendCreditLeaseRequestBody";
-export type { GetEnrichedCreditLedgerRequest } from "./GetEnrichedCreditLedgerRequest";
 export type { ListBillingCreditsRequest } from "./ListBillingCreditsRequest";
 export type { ListBillingPlanCreditGrantsRequest } from "./ListBillingPlanCreditGrantsRequest";
 export type { ListCompanyCreditBalancesRequest } from "./ListCompanyCreditBalancesRequest";

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

@@ -11,8 +11,6 @@ export * from "./CountCreditBundlesParams";
 export * from "./CountCreditBundlesResponse";
 export * from "./CountCreditEventLedgerParams";
 export * from "./CountCreditEventLedgerResponse";
-export * from "./CountCreditLedgerParams";
-export * from "./CountCreditLedgerResponse";
 export * from "./CreateBillingCreditResponse";
 export * from "./CreateBillingPlanCreditGrantResponse";
 export * from "./CreateCreditBundleResponse";
@@ -21,8 +19,6 @@ export * from "./DeleteBillingPlanCreditGrantResponse";
 export * from "./DeleteCreditBundleResponse";
 export * from "./ExtendCreditLeaseResponse";
 export * from "./GetCreditBundleResponse";
-export * from "./GetEnrichedCreditLedgerParams";
-export * from "./GetEnrichedCreditLedgerResponse";
 export * from "./GetSingleBillingCreditResponse";
 export * from "./GetSingleBillingPlanCreditGrantResponse";
 export * from "./GrantBillingCreditsToCompanyResponse";

package/dist/api/resources/plangroups/client/Client.d.ts

@@ -43,6 +43,7 @@ export declare class PlangroupsClient {
      *         checkoutCollectEmail: true,
      *         checkoutCollectPhone: true,
      *         enableTaxCollection: true,
+     *         optInEnabled: true,
      *         orderedAddOns: [{
      *                 planId: "plan_id"
      *             }],
@@ -84,6 +85,7 @@ export declare class PlangroupsClient {
      *         checkoutCollectEmail: true,
      *         checkoutCollectPhone: true,
      *         enableTaxCollection: true,
+     *         optInEnabled: true,
      *         orderedAddOns: [{
      *                 planId: "plan_id"
      *             }],

package/dist/api/resources/plangroups/client/requests/CreatePlanGroupRequestBody.d.ts

@@ -7,6 +7,7 @@ import type * as Schematic from "../../../../index";
  *         checkoutCollectEmail: true,
  *         checkoutCollectPhone: true,
  *         enableTaxCollection: true,
+ *         optInEnabled: true,
  *         orderedAddOns: [{
  *                 planId: "plan_id"
  *             }],
@@ -42,6 +43,9 @@ export interface CreatePlanGroupRequestBody {
     fallbackPlanId?: string;
     initialPlanId?: string;
     initialPlanPriceId?: string;
+    optInEnabled: boolean;
+    optInText?: string;
+    optInTitle?: string;
     orderedAddOns: Schematic.OrderedPlansInGroup[];
     orderedBundleList: Schematic.PlanGroupBundleOrder[];
     orderedPlans: Schematic.OrderedPlansInGroup[];

package/dist/api/resources/plangroups/client/requests/UpdatePlanGroupRequestBody.d.ts

@@ -7,6 +7,7 @@ import type * as Schematic from "../../../../index";
  *         checkoutCollectEmail: true,
  *         checkoutCollectPhone: true,
  *         enableTaxCollection: true,
+ *         optInEnabled: true,
  *         orderedAddOns: [{
  *                 planId: "plan_id"
  *             }],
@@ -42,6 +43,9 @@ export interface UpdatePlanGroupRequestBody {
     fallbackPlanId?: string;
     initialPlanId?: string;
     initialPlanPriceId?: string;
+    optInEnabled: boolean;
+    optInText?: string;
+    optInTitle?: string;
     orderedAddOns: Schematic.OrderedPlansInGroup[];
     orderedBundleList: Schematic.PlanGroupBundleOrder[];
     orderedPlans: Schematic.OrderedPlansInGroup[];

package/dist/api/resources/plans/client/Client.d.ts

@@ -81,11 +81,7 @@ export declare class PlansClient {
      *
      * @example
      *     await client.plans.retryCustomPlanBilling("custom_plan_billing_id", {
-     *         customerEmail: "customer_email",
-     *         payInAdvance: [{
-     *                 priceId: "price_id",
-     *                 quantity: 1000000
-     *             }]
+     *         customerEmail: "customer_email"
      *     })
      */
     retryCustomPlanBilling(custom_plan_billing_id: string, request: Schematic.RetryCustomPlanBillingRequestBody, requestOptions?: PlansClient.RequestOptions): core.HttpResponsePromise<Schematic.RetryCustomPlanBillingResponse>;

package/dist/api/resources/plans/client/requests/RetryCustomPlanBillingRequestBody.d.ts

@@ -2,16 +2,11 @@ import type * as Schematic from "../../../../index";
 /**
  * @example
  *     {
- *         customerEmail: "customer_email",
- *         payInAdvance: [{
- *                 priceId: "price_id",
- *                 quantity: 1000000
- *             }]
+ *         customerEmail: "customer_email"
  *     }
  */
 export interface RetryCustomPlanBillingRequestBody {
     activationStrategy?: Schematic.CustomPlanActivationStrategy;
     customerEmail: string;
     daysUntilDue?: number;
-    payInAdvance: Schematic.UpdatePayInAdvanceRequestBody[];
 }

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

@@ -3,5 +3,6 @@ export declare const BillingCreditGrantZeroedOutReason: {
     readonly Manual: "manual";
     readonly PlanChange: "plan_change";
     readonly PlanPeriodReset: "plan_period_reset";
+    readonly Reconciled: "reconciled";
 };
 export type BillingCreditGrantZeroedOutReason = (typeof BillingCreditGrantZeroedOutReason)[keyof typeof BillingCreditGrantZeroedOutReason];

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

@@ -8,6 +8,7 @@ export interface ChangeSubscriptionInternalRequestBody {
     customFieldValues: Schematic.CheckoutFieldValue[];
     newPlanId: string;
     newPriceId: string;
+    optInAccepted?: boolean;
     payInAdvance: Schematic.UpdatePayInAdvanceRequestBody[];
     paymentMethodId?: string;
     promoCode?: string;

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

@@ -7,6 +7,7 @@ export interface ChangeSubscriptionRequestBody {
     customFieldValues: Schematic.CheckoutFieldValue[];
     newPlanId: string;
     newPriceId: string;
+    optInAccepted?: boolean;
     payInAdvance: Schematic.UpdatePayInAdvanceRequestBody[];
     paymentMethodId?: string;
     promoCode?: string;

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

@@ -2,4 +2,7 @@ export interface CheckoutSettingsResponseData {
     collectAddress: boolean;
     collectEmail: boolean;
     collectPhone: boolean;
+    optInEnabled: boolean;
+    optInText?: string;
+    optInTitle?: string;
 }

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

@@ -4,8 +4,12 @@ export interface FeatureEntitlement {
     allocation?: number;
     /** If the company has a credit-based entitlement for this feature, the ID of the credit */
     creditId?: string;
-    /** If the company has a credit-based entitlement for this feature, the remaining credit amount */
+    /** If the company has a credit-based entitlement for this feature, the credit available to fund new consumption or a new lease hold — open lease holds are excluded. Clients that hold a lease should gate on this plus their own unspent hold; clients with no lease awareness should use credit_settled instead */
     creditRemaining?: number;
+    /** If the company has a credit-based entitlement for this feature, the unspent amount held by an open credit lease. Returns to credit_remaining when the lease is released */
+    creditReserved?: number;
+    /** If the company has a credit-based entitlement for this feature, the balance net of actual consumption, unaffected by open lease holds (credit_remaining plus credit_reserved). The number to display to end users */
+    creditSettled?: number;
     /** If the company has a credit-based entitlement for this feature, the total credit amount */
     creditTotal?: number;
     /** If the company has a credit-based entitlement for this feature, the amount of credit used */

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

@@ -16,6 +16,8 @@ export interface PlanChangeResponseData {
     createdAt: Date;
     environmentId: string;
     id: string;
+    /** True when this change moved the company to a different version of the same plan (e.g. a plan version migration) rather than to a different plan. */
+    isVersionUpgrade: boolean;
     previousBasePlan?: Schematic.PlanSnapshotView;
     /** The plan version of the previous base plan before this change. */
     previousBasePlanVersion?: Schematic.PlanVersionSnapshotView;

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

@@ -5,6 +5,9 @@ export interface PreviewSubscriptionChangeResponseData {
     finance?: Schematic.PreviewSubscriptionFinanceResponseData;
     isScheduledDowngrade: boolean;
     newCharges: number;
+    optInRequired: boolean;
+    optInText?: string;
+    optInTitle?: string;
     paymentMethodRequired: boolean;
     percentOff: number;
     periodStart: Date;

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

@@ -4,8 +4,12 @@ export interface RulesengineFeatureEntitlement {
     allocation?: number;
     /** If the company has a credit-based entitlement for this feature, the ID of the credit */
     creditId?: string;
-    /** If the company has a credit-based entitlement for this feature, the remaining credit amount */
+    /** If the company has a credit-based entitlement for this feature, the credit available to fund new consumption or a new lease hold — open lease holds are excluded. Clients that hold a lease should gate on this plus their own unspent hold; clients with no lease awareness should use credit_settled instead */
     creditRemaining?: number;
+    /** If the company has a credit-based entitlement for this feature, the unspent amount held by an open credit lease. Returns to credit_remaining when the lease is released */
+    creditReserved?: number;
+    /** If the company has a credit-based entitlement for this feature, the balance net of actual consumption, unaffected by open lease holds (credit_remaining plus credit_reserved). The number to display to end users */
+    creditSettled?: number;
     /** If the company has a credit-based entitlement for this feature, the total credit amount */
     creditTotal?: number;
     /** If the company has a credit-based entitlement for this feature, the amount of credit used */

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

@@ -137,8 +137,6 @@ export * from "./CreditGrantDetail";
 export * from "./CreditGrantExpiryRequestBody";
 export * from "./CreditGrantSortOrder";
 export * from "./CreditLeaseResponseData";
-export * from "./CreditLedgerEnrichedEntryResponseData";
-export * from "./CreditLedgerPeriod";
 export * from "./CreditsAutoTopupCompanySummary";
 export * from "./CreditsAutoTopupCreditSummary";
 export * from "./CreditsAutoTopupHardFailure";

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>;
+}