@schematichq/schematic-typescript-node 1.6.0 → 1.6.2

package/README.md

@@ -800,13 +800,12 @@ const client = new SchematicClient({
 
 ## 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:
+For features metered by credit burndown (e.g. inference tokens), `check()` holds credits for the work about to run and `trackWithReservation()` settles the hold with actual usage. The SDK gates in one of two modes:
 
-- 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.
+- **Client mode** acquires a **lease**, a tranche of credits held against the company's balance, and carves a per-request **reservation** out of it locally, so a check needs no API call. It requires [DataStream](#datastream) (or [Replicator Mode](#replicator-mode)) and, across multiple processes, a shared Redis so every instance gates against the same lease.
+- **Server mode** makes one `check-and-reserve` API call per check. No lease, no Redis, no local state.
 
-> **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.
+`creditLeases.mode` defaults to `auto`: client when DataStream is enabled, server otherwise. Client mode suits high-throughput gating; server mode suits low-volume checks and operations that run for seconds.
 
 ### Setup
 
@@ -821,25 +820,35 @@ const client = new SchematicClient({
     apiKey: process.env.SCHEMATIC_API_KEY,
     useDataStream: true,
     dataStream: {
-        redisClient, // also backs lease + reservation state automatically
+        redisClient, // also backs lease + reservation state
     },
     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
+        defaultLeaseDuration: 5 * 60 * 1000, // lease lifetime (ms)
+        defaultReservationTTL: 60 * 1000, // how long a reservation is held if no track settles it (ms)
     },
 });
 ```
 
-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.
+Set `creditLeases.redisClient` to keep lease state in a different Redis than the DataStream cache.
 
-### Checking and tracking
+Server mode needs only a TTL:
+
+```ts
+const client = new SchematicClient({
+    apiKey: process.env.SCHEMATIC_API_KEY,
+    creditLeases: {
+        defaultReservationTTL: 60 * 1000, // how long the server holds the credits if no track settles them (ms, max 1 hour)
+    },
+});
+```
 
-`check()` reserves the operation's upper-bound usage against the lease and returns a reservation handle; `trackWithReservation()` settles it with actual usage:
+Only `mode` and `defaultReservationTTL` apply in server mode; the SDK warns at startup if a client-only option is set.
+
+### Checking and tracking
 
 ```ts
-// Per-request: reserve up to maxTokens against the lease.
+// Reserve up to maxTokens for this operation.
 const result = await client.check(
     { company: { id: "your-company-id" } },
     "inference",
@@ -854,15 +863,25 @@ if (!result.allowed) {
 
 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);
+// Report actual usage; the unused slice of the reservation is refunded.
+if (result.reservation) {
+    await client.trackWithReservation(result.reservation, inference.tokensUsed);
+} else {
+    await client.track({
+        event: "inference_tokens",
+        company: { id: "your-company-id" },
+        quantity: 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.
+A check can allow without taking a hold (the feature is not credit-metered, `usage` is 0, or the check failed open), and that usage still has to be tracked.
+
+An unsettled reservation expires after `defaultReservationTTL` and its credits return to the lease. A late settle still bills the usage (the track event carries a deterministic idempotency key, so it never double-bills) but does not re-debit the local lease, so set `defaultReservationTTL` above the longest expected gap between `check()` and `trackWithReservation()`.
 
 ### Pre-warming
 
-To avoid paying the lease-acquire round trip on a session's first check, pre-warm leases when the user is identified:
+Pre-warm leases when the user is identified, so a session's first check does not wait on a lease acquire:
 
 ```ts
 await client.identify(
@@ -874,11 +893,13 @@ await client.identify(
 );
 ```
 
-Or call `client.prewarm(evalCtx, creditTypeIds)` directly.
+Or call `client.prewarm(evalCtx, creditTypeIds)` directly. Both are no-ops in server mode.
+
+Pre-warming resolves the company the way the server does: it looks the keys up first, whatever they are named, and only when nothing matches does it read a value carrying Schematic's `comp_` prefix as the company id.
 
 ### 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:
+A check that cannot be gated (API unreachable, Redis down, lease exhausted) fails closed by default. Override per check:
 
 ```ts
 const result = await client.check(evalCtx, "inference", {
@@ -888,20 +909,22 @@ const result = await client.check(evalCtx, "inference", {
 });
 ```
 
-`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.
+In client mode, `fail-open` still evaluates the flag's rules with the credit balance assumed sufficient, so plan targeting and all non-credit conditions apply and only the credit gate is bypassed. In server mode it returns the flag's default value, which is `false` unless you pass `defaultValue` or configure a `flagDefaults` entry.
 
 ### 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) |
+| `mode` | `"client" \| "server" \| "auto"` | `auto` | Where the credit hold lives; `auto` picks client when DataStream is enabled, server otherwise |
+| `defaultReservationTTL` | `number` | 60 seconds | How long an unsettled reservation is held (ms) |
+| `defaultLeaseDuration` | `number` | 5 minutes | (client mode) Lease lifetime (ms) |
+| `defaultLeaseSize` | `number` | 10000 | (client mode) Credits requested per lease acquire or extend |
+| `lowWaterMark` | `number` | 0.25 | (client mode) Extend in the background when the lease balance dips below this fraction |
+| `sweepIntervalMs` | `number` | 1000 | (client mode) Sweep interval for expired reservations (ms) |
+| `prewarmResolveTimeoutMs` | `number` | 5000 | (client mode) How long `prewarm()` waits for a freshly identified company to surface (ms) |
+| `redisClient` | `RedisClient` | `dataStream.redisClient` | (client mode) Redis client for lease and reservation state |
+| `redisKeyPrefix` | `string` | `dataStream.redisKeyPrefix` | (client mode) Key prefix for lease and reservation keys |
+| `overrides` | `object` | — | (client mode) Per-credit-type overrides of the above, keyed by credit type ID |
 
 ## Testing
 

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

@@ -9,6 +9,7 @@
 export interface AcquireCreditLeaseRequestBody {
     companyId: string;
     creditTypeId: string;
+    /** When the hold lapses if the lease is never released; defaults to five minutes from now and may be at most one hour out. The unspent hold is refunded on expiry */
     expiresAt?: Date;
     requestedAmount: number;
 }

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

@@ -6,5 +6,8 @@
  */
 export interface ExtendCreditLeaseRequestBody {
     additionalAmount: number;
+    /** Pushes the lease's expiry out; may be at most one hour from now. Leave unset to keep the expiry the lease already has */
     expiresAt?: Date;
+    /** A caller-chosen key for safe retries: a second request with the same key returns the lease as it stands instead of growing it again. Keys are unique per environment across every extend */
+    idempotencyKey?: string;
 }

package/dist/api/resources/entitlements/client/requests/CreateBillingLinkedPlanEntitlementRequestBody.d.ts

@@ -24,7 +24,11 @@ export interface CreateBillingLinkedPlanEntitlementRequestBody {
     monthlyPriceTiers?: Schematic.CreatePriceTierRequestBody[];
     monthlyUnitPrice?: number;
     monthlyUnitPriceDecimal?: string;
+    /** How often overage charges are assessed and invoiced. Defaults to end_of_billing_period, where the billing provider aggregates usage over the subscription's own period and bills it at period end. Set to monthly or quarterly to have overage assessed each month or quarter and billed on its own invoice, which is the point of the setting on annual plans. A quarter charges each month's usage against that month's allowance. Only applies to overage price behavior. */
+    overageBillingCadence?: Schematic.BillingArrearsCadence;
     overageBillingProductId?: string;
+    /** Which boundary closes a monthly or quarterly overage window: the subscription's own recurrence (billing_period_start) or the calendar month (month_end). Quarterly windows run in three-month blocks from the billing period start, held to the subscription's own period, or in calendar quarters at month_end. Only applies when overage_billing_cadence is monthly or quarterly, and must match metric_period_month_reset so each window closes when the allowance resets: billing_period_start for billing_cycle, month_end for first_of_month. Defaults to the anchor that matches the reset. */
+    overageInvoiceAnchor?: Schematic.BillingArrearsAnchor;
     planId: string;
     planVersionId?: string;
     priceBehavior?: Schematic.EntitlementPriceBehavior;

package/dist/api/resources/entitlements/client/requests/CreatePlanEntitlementRequestBody.d.ts

@@ -20,7 +20,11 @@ export interface CreatePlanEntitlementRequestBody {
     monthlyPriceTiers?: Schematic.CreatePriceTierRequestBody[];
     monthlyUnitPrice?: number;
     monthlyUnitPriceDecimal?: string;
+    /** How often overage charges are assessed and invoiced. Defaults to end_of_billing_period, where the billing provider aggregates usage over the subscription's own period and bills it at period end. Set to monthly or quarterly to have overage assessed each month or quarter and billed on its own invoice, which is the point of the setting on annual plans. A quarter charges each month's usage against that month's allowance. Only applies to overage price behavior. */
+    overageBillingCadence?: Schematic.BillingArrearsCadence;
     overageBillingProductId?: string;
+    /** Which boundary closes a monthly or quarterly overage window: the subscription's own recurrence (billing_period_start) or the calendar month (month_end). Quarterly windows run in three-month blocks from the billing period start, held to the subscription's own period, or in calendar quarters at month_end. Only applies when overage_billing_cadence is monthly or quarterly, and must match metric_period_month_reset so each window closes when the allowance resets: billing_period_start for billing_cycle, month_end for first_of_month. Defaults to the anchor that matches the reset. */
+    overageInvoiceAnchor?: Schematic.BillingArrearsAnchor;
     planId: string;
     planVersionId?: string;
     priceBehavior?: Schematic.EntitlementPriceBehavior;

package/dist/api/resources/entitlements/client/requests/UpdatePlanEntitlementRequestBody.d.ts

@@ -17,7 +17,11 @@ export interface UpdatePlanEntitlementRequestBody {
     monthlyPriceTiers?: Schematic.CreatePriceTierRequestBody[];
     monthlyUnitPrice?: number;
     monthlyUnitPriceDecimal?: string;
+    /** How often overage charges are assessed and invoiced. Defaults to end_of_billing_period, where the billing provider aggregates usage over the subscription's own period and bills it at period end. Set to monthly or quarterly to have overage assessed each month or quarter and billed on its own invoice, which is the point of the setting on annual plans. A quarter charges each month's usage against that month's allowance. Only applies to overage price behavior. */
+    overageBillingCadence?: Schematic.BillingArrearsCadence;
     overageBillingProductId?: string;
+    /** Which boundary closes a monthly or quarterly overage window: the subscription's own recurrence (billing_period_start) or the calendar month (month_end). Quarterly windows run in three-month blocks from the billing period start, held to the subscription's own period, or in calendar quarters at month_end. Only applies when overage_billing_cadence is monthly or quarterly, and must match metric_period_month_reset so each window closes when the allowance resets: billing_period_start for billing_cycle, month_end for first_of_month. Defaults to the anchor that matches the reset. */
+    overageInvoiceAnchor?: Schematic.BillingArrearsAnchor;
     priceBehavior?: Schematic.EntitlementPriceBehavior;
     /** Use MonthlyPriceTiers or YearlyPriceTiers instead */
     priceTiers?: Schematic.CreatePriceTierRequestBody[];

package/dist/api/resources/features/client/requests/CheckAndReserveFlagRequestBody.d.ts

@@ -7,9 +7,11 @@ export interface CheckAndReserveFlagRequestBody {
     company?: Record<string, string>;
     /** When the hold lapses if no track event settles it; defaults to one minute from now and may be at most one hour out. The unspent hold is refunded on expiry */
     expiresAt?: Date;
-    /** Hypothetical usage to evaluate the flag against. When credit_cost names the entitlement's credit, that cost is what gets held; otherwise the hold is quantity times the entitlement's consumption rate */
+    /** A caller-chosen key for safe retries: a second request with the same key returns the original reservation instead of taking another hold */
+    idempotencyKey?: string;
+    /** Hypothetical usage to evaluate the flag against. When credit_cost names the entitlement's credit, that cost is what gets held; otherwise the hold is the entitlement's consumption rate times quantity, or, when quantity is omitted, times the usage stated here */
     preflight?: Schematic.PreflightRequestBody;
-    /** Units of the feature the operation will consume; defaults to 1. Sets the hold size together with the entitlement's consumption rate, and is echoed back on the reservation for the settling track event */
+    /** Units of the feature the operation will consume. Sets the hold size together with the entitlement's consumption rate, and is echoed back on the reservation for the settling track event. When it is omitted the units come from preflight.event_usage.quantity, if that event subtype is the entitlement's, else from preflight.usage, else 1 */
     quantity?: number;
     user?: Record<string, string>;
 }

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

@@ -87,13 +87,14 @@ export declare class PlanmigrationsClient {
      *
      * @example
      *     await client.planmigrations.listMigrations({
+     *         featureId: "feature_id",
      *         planVersionId: "plan_version_id",
      *         status: "cancelled",
      *         limit: 1000000,
      *         offset: 1000000
      *     })
      */
-    listMigrations(request: Schematic.ListMigrationsRequest, requestOptions?: PlanmigrationsClient.RequestOptions): core.HttpResponsePromise<Schematic.ListMigrationsResponse>;
+    listMigrations(request?: Schematic.ListMigrationsRequest, requestOptions?: PlanmigrationsClient.RequestOptions): core.HttpResponsePromise<Schematic.ListMigrationsResponse>;
     private __listMigrations;
     /**
      * @param {Schematic.CreateMigrationInput} request
@@ -202,13 +203,14 @@ export declare class PlanmigrationsClient {
      *
      * @example
      *     await client.planmigrations.countMigrations({
+     *         featureId: "feature_id",
      *         planVersionId: "plan_version_id",
      *         status: "cancelled",
      *         limit: 1000000,
      *         offset: 1000000
      *     })
      */
-    countMigrations(request: Schematic.CountMigrationsRequest, requestOptions?: PlanmigrationsClient.RequestOptions): core.HttpResponsePromise<Schematic.CountMigrationsResponse>;
+    countMigrations(request?: Schematic.CountMigrationsRequest, requestOptions?: PlanmigrationsClient.RequestOptions): core.HttpResponsePromise<Schematic.CountMigrationsResponse>;
     private __countMigrations;
     /**
      * @param {Schematic.PreviewMigrationRequestBody} request

package/dist/api/resources/planmigrations/client/requests/CountMigrationsRequest.d.ts

@@ -2,6 +2,7 @@ import type * as Schematic from "../../../../index";
 /**
  * @example
  *     {
+ *         featureId: "feature_id",
  *         planVersionId: "plan_version_id",
  *         status: "cancelled",
  *         limit: 1000000,
@@ -9,7 +10,8 @@ import type * as Schematic from "../../../../index";
  *     }
  */
 export interface CountMigrationsRequest {
-    planVersionId: string;
+    featureId?: string;
+    planVersionId?: string;
     status?: Schematic.PlanVersionMigrationStatus;
     /** Page limit (default 100) */
     limit?: number;

package/dist/api/resources/planmigrations/client/requests/ListMigrationsRequest.d.ts

@@ -2,6 +2,7 @@ import type * as Schematic from "../../../../index";
 /**
  * @example
  *     {
+ *         featureId: "feature_id",
  *         planVersionId: "plan_version_id",
  *         status: "cancelled",
  *         limit: 1000000,
@@ -9,7 +10,8 @@ import type * as Schematic from "../../../../index";
  *     }
  */
 export interface ListMigrationsRequest {
-    planVersionId: string;
+    featureId?: string;
+    planVersionId?: string;
     status?: Schematic.PlanVersionMigrationStatus;
     /** Page limit (default 100) */
     limit?: number;

package/dist/api/resources/planmigrations/types/CountMigrationsParams.d.ts

@@ -3,6 +3,7 @@ import type * as Schematic from "../../../index";
  * Input parameters
  */
 export interface CountMigrationsParams {
+    featureId?: string;
     /** Page limit (default 100) */
     limit?: number;
     /** Page offset (default 0) */

package/dist/api/resources/planmigrations/types/ListMigrationsParams.d.ts

@@ -3,6 +3,7 @@ import type * as Schematic from "../../../index";
  * Input parameters
  */
 export interface ListMigrationsParams {
+    featureId?: string;
     /** Page limit (default 100) */
     limit?: number;
     /** Page offset (default 0) */

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

@@ -143,6 +143,8 @@ export declare class PlansClient {
      *         q: "q",
      *         scopedToCompanyId: "scoped_to_company_id",
      *         withEntitlements: true,
+     *         withPublishedVersion: true,
+     *         withoutEntitlementForIncludeDrafts: true,
      *         withoutEntitlementFor: "without_entitlement_for",
      *         withoutPaidProductId: true,
      *         limit: 1000000,
@@ -342,6 +344,8 @@ export declare class PlansClient {
      *         q: "q",
      *         scopedToCompanyId: "scoped_to_company_id",
      *         withEntitlements: true,
+     *         withPublishedVersion: true,
+     *         withoutEntitlementForIncludeDrafts: true,
      *         withoutEntitlementFor: "without_entitlement_for",
      *         withoutPaidProductId: true,
      *         limit: 1000000,

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

@@ -16,6 +16,8 @@ import type * as Schematic from "../../../../index";
  *         q: "q",
  *         scopedToCompanyId: "scoped_to_company_id",
  *         withEntitlements: true,
+ *         withPublishedVersion: true,
+ *         withoutEntitlementForIncludeDrafts: true,
  *         withoutEntitlementFor: "without_entitlement_for",
  *         withoutPaidProductId: true,
  *         limit: 1000000,
@@ -48,6 +50,10 @@ export interface CountPlansRequest {
     scopedToCompanyId?: string;
     /** Include each plan's entitlements in the response */
     withEntitlements?: boolean;
+    /** Only return plans that have a published version */
+    withPublishedVersion?: boolean;
+    /** With without_entitlement_for, also treat an entitlement on a plan's draft version as existing */
+    withoutEntitlementForIncludeDrafts?: boolean;
     /** Filter out plans that already have a plan entitlement for the specified feature ID */
     withoutEntitlementFor?: string;
     /** Filter out plans that have a paid billing product ID */

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

@@ -16,6 +16,8 @@ import type * as Schematic from "../../../../index";
  *         q: "q",
  *         scopedToCompanyId: "scoped_to_company_id",
  *         withEntitlements: true,
+ *         withPublishedVersion: true,
+ *         withoutEntitlementForIncludeDrafts: true,
  *         withoutEntitlementFor: "without_entitlement_for",
  *         withoutPaidProductId: true,
  *         limit: 1000000,
@@ -48,6 +50,10 @@ export interface ListPlansRequest {
     scopedToCompanyId?: string;
     /** Include each plan's entitlements in the response */
     withEntitlements?: boolean;
+    /** Only return plans that have a published version */
+    withPublishedVersion?: boolean;
+    /** With without_entitlement_for, also treat an entitlement on a plan's draft version as existing */
+    withoutEntitlementForIncludeDrafts?: boolean;
     /** Filter out plans that already have a plan entitlement for the specified feature ID */
     withoutEntitlementFor?: string;
     /** Filter out plans that have a paid billing product ID */

package/dist/api/resources/plans/types/CountPlansParams.d.ts

@@ -32,8 +32,12 @@ export interface CountPlansParams {
     scopedToCompanyId?: string;
     /** Include each plan's entitlements in the response */
     withEntitlements?: boolean;
+    /** Only return plans that have a published version */
+    withPublishedVersion?: boolean;
     /** Filter out plans that already have a plan entitlement for the specified feature ID */
     withoutEntitlementFor?: string;
+    /** With without_entitlement_for, also treat an entitlement on a plan's draft version as existing */
+    withoutEntitlementForIncludeDrafts?: boolean;
     /** Filter out plans that have a paid billing product ID */
     withoutPaidProductId?: boolean;
 }

package/dist/api/resources/plans/types/ListPlansParams.d.ts

@@ -32,8 +32,12 @@ export interface ListPlansParams {
     scopedToCompanyId?: string;
     /** Include each plan's entitlements in the response */
     withEntitlements?: boolean;
+    /** Only return plans that have a published version */
+    withPublishedVersion?: boolean;
     /** Filter out plans that already have a plan entitlement for the specified feature ID */
     withoutEntitlementFor?: string;
+    /** With without_entitlement_for, also treat an entitlement on a plan's draft version as existing */
+    withoutEntitlementForIncludeDrafts?: boolean;
     /** Filter out plans that have a paid billing product ID */
     withoutPaidProductId?: boolean;
 }

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

@@ -1,5 +1,6 @@
 export declare const BillingArrearsCadence: {
     readonly EndOfBillingPeriod: "end_of_billing_period";
     readonly Monthly: "monthly";
+    readonly Quarterly: "quarterly";
 };
 export type BillingArrearsCadence = (typeof BillingArrearsCadence)[keyof typeof BillingArrearsCadence];

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

@@ -3,6 +3,9 @@ export declare const BillingCreditGrantReason: {
     readonly BillingCreditAutoTopup: "billing_credit_auto_topup";
     readonly Free: "free";
     readonly Plan: "plan";
+    readonly PostpaidForgiven: "postpaid_forgiven";
+    readonly PostpaidOverdraft: "postpaid_overdraft";
+    readonly PostpaidSettlement: "postpaid_settlement";
     readonly Purchased: "purchased";
     readonly Rollover: "rollover";
 };

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

@@ -10,6 +10,7 @@ export interface BillingCreditResponseData {
     description: string;
     icon?: string;
     id: string;
+    ledgerAuthority: Schematic.BillingCreditLedgerAuthority;
     name: string;
     pluralName?: string;
     price?: Schematic.BillingPriceResponseData;

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

@@ -0,0 +1,5 @@
+export declare const BillingPlanCreditGrantBillingMode: {
+    readonly Granted: "granted";
+    readonly Billed: "billed";
+};
+export type BillingPlanCreditGrantBillingMode = (typeof BillingPlanCreditGrantBillingMode)[keyof typeof BillingPlanCreditGrantBillingMode];

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

@@ -0,0 +1,10 @@
+export interface BillingPlanCreditGrantPriceTierResponseData {
+    /** Lower bound of the tier, in credits per invoice (inclusive). */
+    from: number;
+    /** Price per credit in this tier, in the plan currency's smallest unit. */
+    perUnitPrice?: number;
+    /** Price per credit in this tier as a decimal, for rates below one cent. */
+    perUnitPriceDecimal?: string;
+    /** Upper bound of the tier, in credits per invoice (inclusive). Null marks the final, unbounded tier. */
+    to?: number;
+}

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

@@ -16,6 +16,8 @@ export interface BillingPlanCreditGrantResponseData {
     autoTopupSelfService: boolean;
     autoTopupThresholdCredits?: number;
     autoTopupThresholdPercent?: number;
+    /** Whether the credits are included in the plan price (granted) or billed as their own subscription line at a price per credit (billed). */
+    billingMode: Schematic.BillingPlanCreditGrantBillingMode;
     /** Deprecated: bundle availability is a per-bundle plan compatibility set now; use compatible_plan_ids on credit bundles instead. */
     canBuyBundles: boolean;
     /** Credits granted once per company on top of the per-license amount. Always 0 when scaling is fixed. */
@@ -49,6 +51,10 @@ export interface BillingPlanCreditGrantResponseData {
     postpaidRatePerUnit?: number;
     /** Decimal form of postpaid_rate_per_unit, for rates finer than one minor unit. */
     postpaidRatePerUnitDecimal?: string;
+    /** The Stripe price a billed grant bills through. Minted when the plan version is published. */
+    price?: Schematic.BillingPriceResponseData;
+    /** Tier table pricing the credits, cheapest bound first. Empty unless billing_mode is billed and the credits are priced on tiers. */
+    priceTiers: Schematic.BillingPlanCreditGrantPriceTierResponseData[];
     resetCadence?: Schematic.BillingPlanCreditGrantResetCadence;
     resetStart?: Schematic.BillingPlanCreditGrantResetStart;
     resetType?: Schematic.BillingPlanCreditGrantResetType;
@@ -56,5 +62,11 @@ export interface BillingPlanCreditGrantResponseData {
     rolloverPercentage: number;
     /** Whether the grant is a fixed amount per company, or issued once per license the company holds. */
     scaling: Schematic.PlanCreditGrantScaling;
+    /** How price_tiers apply: volume prices every credit at the rate of the tier the total lands in, graduated prices each tier's own credits at its own rate. Set only when price_tiers is non-empty. */
+    tierMode?: Schematic.BillingTiersMode;
+    /** Price per credit in the plan currency's smallest unit. Set only when billing_mode is billed and the credits are priced at one rate. */
+    unitPrice?: number;
+    /** Price per credit as a decimal in the plan currency's smallest unit. Set only when billing_mode is billed and the rate is below one cent. */
+    unitPriceDecimal?: string;
     updatedAt: Date;
 }

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

@@ -17,6 +17,8 @@ export interface CompanyPlanCreditGrantView {
     billingCreditPostpaidEnabled: boolean;
     billingCreditPostpaidRatePerUnit?: number;
     billingCreditPostpaidRatePerUnitDecimal?: string;
+    billingMode: Schematic.BillingPlanCreditGrantBillingMode;
+    billingProductPriceId?: string;
     companyAutoTopupAmount?: number;
     companyAutoTopupEnabled?: boolean;
     companyAutoTopupThresholdCredits?: number;
@@ -41,6 +43,7 @@ export interface CompanyPlanCreditGrantView {
     planVersionId?: string;
     /** Deprecated field, will be removed in the future. Use Credit.PluralName instead. */
     pluralName?: string;
+    price?: Schematic.BillingPriceView;
     resetCadence?: Schematic.BillingPlanCreditGrantResetCadence;
     resetStart?: Schematic.BillingPlanCreditGrantResetStart;
     resetType: Schematic.BillingPlanCreditGrantResetType;

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

@@ -3,7 +3,7 @@ export interface CreateBillingPlanCreditGrantRequestBody {
     applyToExisting?: boolean;
     /** Which boundary closes a monthly arrears window: the subscription's own recurrence (billing_period_start) or the calendar month (month_end). Only applies when arrears_cadence is monthly; defaults to billing_period_start. */
     arrearsAnchor?: Schematic.BillingArrearsAnchor;
-    /** How often postpaid charges are closed and invoiced: end_of_billing_period (the default) or monthly. */
+    /** How often postpaid charges are closed and invoiced: end_of_billing_period (the default) or monthly. Quarterly is not available for postpaid charges. */
     arrearsCadence?: Schematic.BillingArrearsCadence;
     autoTopupAmount?: number;
     autoTopupAmountType?: Schematic.CreditAutoTopupAmountType;
@@ -15,6 +15,8 @@ export interface CreateBillingPlanCreditGrantRequestBody {
     autoTopupSelfService?: boolean;
     autoTopupThresholdCredits?: number;
     autoTopupThresholdPercent?: number;
+    /** Whether the credits are included in the plan price (granted) or billed as their own subscription line at a price per credit (billed). Billed is only available on custom plans. Defaults to granted. */
+    billingMode?: Schematic.BillingPlanCreditGrantBillingMode;
     /** Deprecated: use compatible_plan_ids on credit bundles instead. Still accepted; writes through to the credit's bundle compatibility. */
     canBuyBundles?: boolean;
     /** Credits granted once per company on top of the per-license amount. Only valid when scaling is per_license. Defaults to 0. */
@@ -36,6 +38,8 @@ export interface CreateBillingPlanCreditGrantRequestBody {
     postpaidRatePerUnit?: number;
     /** Decimal string form of postpaid_rate_per_unit, for rates finer than one minor unit (for example 0.0002). Takes precedence over postpaid_rate_per_unit when both are set, matching how the credit's own price_per_unit_decimal behaves. */
     postpaidRatePerUnitDecimal?: string;
+    /** Tier table pricing the credits on this grant, cheapest bound first, the last tier unbounded. Give this instead of unit_price to charge a rate that changes with the number of credits on the invoice. Requires tier_mode. */
+    priceTiers?: Schematic.CreditGrantPriceTierRequestBody[];
     resetCadence: Schematic.BillingPlanCreditGrantResetCadence;
     resetStart: Schematic.BillingPlanCreditGrantResetStart;
     resetType?: Schematic.BillingPlanCreditGrantResetType;
@@ -43,4 +47,10 @@ export interface CreateBillingPlanCreditGrantRequestBody {
     rolloverPercentage?: number;
     /** Whether the grant is a fixed amount per company, or issued once per license the company holds. Defaults to fixed. */
     scaling?: Schematic.PlanCreditGrantScaling;
+    /** How price_tiers apply: volume prices every credit at the rate of the tier the total lands in, graduated prices each tier's own credits at its own rate. Required with price_tiers. */
+    tierMode?: Schematic.BillingTiersMode;
+    /** Price per credit in the plan currency's smallest unit. Required when billing_mode is billed, unless unit_price_decimal or price_tiers is set. */
+    unitPrice?: number;
+    /** Price per credit as a decimal in the plan currency's smallest unit, for prices below one cent. */
+    unitPriceDecimal?: string;
 }

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

@@ -12,7 +12,11 @@ export interface CreateEntitlementInBundleRequestBody {
     monthlyPriceTiers?: Schematic.CreatePriceTierRequestBody[];
     monthlyUnitPrice?: number;
     monthlyUnitPriceDecimal?: string;
+    /** How often overage charges are assessed and invoiced. Defaults to end_of_billing_period, where the billing provider aggregates usage over the subscription's own period and bills it at period end. Set to monthly or quarterly to have overage assessed each month or quarter and billed on its own invoice, which is the point of the setting on annual plans. A quarter charges each month's usage against that month's allowance. Only applies to overage price behavior. */
+    overageBillingCadence?: Schematic.BillingArrearsCadence;
     overageBillingProductId?: string;
+    /** Which boundary closes a monthly or quarterly overage window: the subscription's own recurrence (billing_period_start) or the calendar month (month_end). Quarterly windows run in three-month blocks from the billing period start, held to the subscription's own period, or in calendar quarters at month_end. Only applies when overage_billing_cadence is monthly or quarterly, and must match metric_period_month_reset so each window closes when the allowance resets: billing_period_start for billing_cycle, month_end for first_of_month. Defaults to the anchor that matches the reset. */
+    overageInvoiceAnchor?: Schematic.BillingArrearsAnchor;
     planId: string;
     planVersionId?: string;
     priceBehavior?: Schematic.EntitlementPriceBehavior;

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

@@ -29,6 +29,7 @@ export interface CreditEventLedgerResponseData {
     quantityRemainingAtZeroOut?: number;
     sourceId: number;
     toGrantId?: string;
+    transferReason?: Schematic.CreditTransferReason;
     usageEventId?: string;
     usageReason?: Schematic.CreditUsageReason;
     zeroedOutReason?: Schematic.BillingCreditGrantZeroedOutReason;

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

@@ -0,0 +1,8 @@
+export interface CreditGrantPriceTierRequestBody {
+    /** Price per credit in this tier, in the plan currency's smallest unit. */
+    perUnitPrice?: number;
+    /** Price per credit in this tier as a decimal in the plan currency's smallest unit, for prices below one cent. */
+    perUnitPriceDecimal?: string;
+    /** Inclusive upper bound of this tier, counted in credits per invoice. Null marks the final, unbounded tier. */
+    upTo?: number;
+}

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

@@ -0,0 +1,7 @@
+export declare const CreditTransferReason: {
+    readonly OverdraftRecovery: "overdraft_recovery";
+    readonly PostpaidDebtMoved: "postpaid_debt_moved";
+    readonly PostpaidForgiven: "postpaid_forgiven";
+    readonly PostpaidPaid: "postpaid_paid";
+};
+export type CreditTransferReason = (typeof CreditTransferReason)[keyof typeof CreditTransferReason];

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

@@ -17,6 +17,8 @@ export interface PlanCreditGrantView {
     billingCreditPostpaidEnabled: boolean;
     billingCreditPostpaidRatePerUnit?: number;
     billingCreditPostpaidRatePerUnitDecimal?: string;
+    billingMode: Schematic.BillingPlanCreditGrantBillingMode;
+    billingProductPriceId?: string;
     companyCreditAmount: number;
     createdAt: Date;
     credit?: Schematic.BillingCreditView;
@@ -38,6 +40,7 @@ export interface PlanCreditGrantView {
     planVersionId?: string;
     /** Deprecated field, will be removed in the future. Use Credit.PluralName instead. */
     pluralName?: string;
+    price?: Schematic.BillingPriceView;
     resetCadence?: Schematic.BillingPlanCreditGrantResetCadence;
     resetStart?: Schematic.BillingPlanCreditGrantResetStart;
     resetType: Schematic.BillingPlanCreditGrantResetType;

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

@@ -14,6 +14,10 @@ export interface PlanEntitlementResponseData {
     meteredYearlyPrice?: Schematic.BillingPriceView;
     metricPeriod?: Schematic.MetricPeriod;
     metricPeriodMonthReset?: Schematic.MetricPeriodMonthReset;
+    /** How often overage charges are assessed and invoiced. Null or end_of_billing_period means the billing provider aggregates usage over the subscription's own period and bills it at period end. Monthly and quarterly mean Schematic assesses the overage each month or quarter and bills it on its own invoice. Only applies to overage price behavior. */
+    overageBillingCadence?: Schematic.BillingArrearsCadence;
+    /** Which boundary closes a monthly or quarterly overage window: the subscription's own recurrence (billing_period_start) or the calendar month (month_end), which for a quarterly window means calendar quarters. Only meaningful when overage_billing_cadence is monthly or quarterly. */
+    overageInvoiceAnchor?: Schematic.BillingArrearsAnchor;
     plan?: Schematic.PlanResponseData;
     planId: string;
     priceBehavior?: Schematic.EntitlementPriceBehavior;