@schematichq/schematic-typescript-node 1.6.1 → 1.6.2

package/README.md

@@ -895,6 +895,8 @@ await client.identify(
 
 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
 
 A check that cannot be gated (API unreachable, Redis down, lease exhausted) fails closed by default. Override per check:

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/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;

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

@@ -3,7 +3,7 @@ export interface UpdateBillingPlanCreditGrantRequestBody {
     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. Send null to fall back to the default. */
     arrearsAnchor?: Schematic.BillingArrearsAnchor;
-    /** How often postpaid charges are closed and invoiced: end_of_billing_period (the default) or monthly. Send null to fall back to the default. */
+    /** How often postpaid charges are closed and invoiced: end_of_billing_period (the default) or monthly. Quarterly is not available for postpaid charges. Send null to fall back to the default. */
     arrearsCadence?: Schematic.BillingArrearsCadence;
     autoTopupAmount?: number;
     autoTopupAmountType?: Schematic.CreditAutoTopupAmountType;
@@ -15,6 +15,8 @@ export interface UpdateBillingPlanCreditGrantRequestBody {
     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. */
+    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 the grant scales per license. */
@@ -33,6 +35,8 @@ export interface UpdateBillingPlanCreditGrantRequestBody {
     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. Send null to clear it. */
     postpaidRatePerUnitDecimal?: string;
+    /** Tier table pricing the credits on this grant, cheapest bound first, the last tier unbounded. Sending it moves the grant off one rate per credit. Requires tier_mode. */
+    priceTiers?: Schematic.CreditGrantPriceTierRequestBody[];
     resetCadence: Schematic.BillingPlanCreditGrantResetCadence;
     resetStart: Schematic.BillingPlanCreditGrantResetStart;
     resetType?: Schematic.BillingPlanCreditGrantResetType;
@@ -40,4 +44,10 @@ export interface UpdateBillingPlanCreditGrantRequestBody {
     rolloverPercentage?: number;
     /** Whether the grant is a fixed amount per company, or issued once per license the company holds. Changing this re-issues the credits companies already hold for this grant. */
     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. Sending it moves a tiered grant back to one rate per credit. */
+    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/UsageBasedEntitlementRequestBody.d.ts

@@ -8,7 +8,11 @@ export interface UsageBasedEntitlementRequestBody {
     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/types/index.d.ts

@@ -37,6 +37,8 @@ export * from "./BillingCustomerSubscription";
 export * from "./BillingCustomerWithSubscriptionsResponseData";
 export * from "./BillingLinkedResourceResponseData";
 export * from "./BillingMeterResponseData";
+export * from "./BillingPlanCreditGrantBillingMode";
+export * from "./BillingPlanCreditGrantPriceTierResponseData";
 export * from "./BillingPlanCreditGrantResetCadence";
 export * from "./BillingPlanCreditGrantResetStart";
 export * from "./BillingPlanCreditGrantResetType";
@@ -168,6 +170,7 @@ export * from "./CreditEventLedgerResponseData";
 export * from "./CreditEventType";
 export * from "./CreditGrantDetail";
 export * from "./CreditGrantExpiryRequestBody";
+export * from "./CreditGrantPriceTierRequestBody";
 export * from "./CreditGrantSortOrder";
 export * from "./CreditLeaseResponseData";
 export * from "./CreditReservationResponseData";
@@ -181,6 +184,7 @@ export * from "./CreditsAutoTopupSuccess";
 export * from "./CreditsCreditPurchaseSuccess";
 export * from "./CreditsWebhookCompanySummary";
 export * from "./CreditsWebhookCreditSummary";
+export * from "./CreditTransferReason";
 export * from "./CreditTransferResponseData";
 export * from "./CreditTransferView";
 export * from "./CreditTriggerConfig";

package/dist/cache/redis.d.ts

@@ -39,6 +39,17 @@ export interface RedisClient {
         arguments: string[];
     }): Promise<unknown>;
     pExpireAt(key: string, timestamp: number): Promise<unknown>;
+    multi?(): RedisMulti;
+}
+/**
+ * The queued-command half of MULTI/EXEC, as node-redis v4 returns it from
+ * `multi()`. Only the commands the SDK queues are declared; every one of them
+ * is single-key, so the transaction is safe under Redis Cluster too.
+ */
+export interface RedisMulti {
+    hSet(key: string, field: string | Record<string, string | number>, value?: string | number): RedisMulti;
+    pExpireAt(key: string, timestamp: number): RedisMulti;
+    exec(): Promise<unknown>;
 }
 export interface RedisOptions extends CacheOptions {
     /** Pre-created, connected redis client */

package/dist/credits/check.d.ts

@@ -33,7 +33,7 @@ export interface CreditCheckDeps {
  *      check. Otherwise `creditId` + `consumptionRate` + `eventSubtype` come
  *      straight off the entitlement — no structural flag scan.
  *   2. Acquire (or reuse) a lease for `(company, creditId)`.
- *   3. Try to reserve `quantity × consumptionRate` from the lease.
+ *   3. Try to reserve `ceil(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), gating with `credit_cost` so the
@@ -45,9 +45,14 @@ export declare function checkWithLease(deps: CreditCheckDeps, key: string, evalC
  * 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.
+ * as the generic `usage` knob. Exported so `client.check`'s fallback path and
+ * the server-mode check-and-reserve body can thread the same preflight — any
+ * evaluation path honors it even when the lease path can't run.
+ *
+ * The quantity rounds up here, once, so every consumer of this envelope asks
+ * the same whole-unit question: the engine takes an integer, the REST body
+ * takes an integer, and the settling Track event bills `ceil(actual)`. A
+ * preflight is an upper bound, so rounding up is also the only safe direction
+ * — the check must not pass on less usage than the action is about to record.
  */
 export declare function buildPreflightOptions(options: CheckOptions): CheckFlagOptions | undefined;

package/dist/credits/index.d.ts

@@ -1,7 +1,7 @@
-export { LeaseStore, leaseKey, type LeaseEntry, type ILeaseStore } from "./lease-store";
+export { LeaseStore, leaseKey, type LeaseEntry, type ILeaseStore, type ReserveResult } from "./lease-store";
 export { ReservationStore, type IReservationStore } from "./reservation-store";
-export { CreditLeaseManager } from "./lease-manager";
+export { CreditLeaseManager, settleWithin, unrefTimer } 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, MAX_RESERVATION_TTL_MS, RESERVATION_TTL_SKEW_ALLOWANCE_MS, } 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, SHUTDOWN_DRAIN_TIMEOUT_MS, } from "./types";
 export type { CreditLeaseConfig, CreditLeaseMode, ResolvedLeaseConfig, Reservation, CheckOptions, CheckResult, OnAcquireFailure, TrackWithReservationOptions, } from "./types";

package/dist/credits/lease-manager.d.ts

@@ -2,6 +2,15 @@ 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";
+/** Drop a timer's hold on the event loop where the runtime has one (Node). */
+export declare function unrefTimer(timer: ReturnType<typeof setTimeout>): void;
+/**
+ * Await `promises`, giving up after `timeoutMs`. Reports whether everything
+ * landed, so a caller winding down can say what it is abandoning. Abandoned
+ * work is not cancelled — promises have no cancellation — it just stops being
+ * waited on.
+ */
+export declare function settleWithin(promises: Promise<unknown>[], timeoutMs: number): Promise<boolean>;
 /**
  * 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
@@ -20,6 +29,8 @@ export declare class CreditLeaseManager {
     private readonly config;
     private readonly inflightAcquire;
     private readonly inflightExtend;
+    private readonly background;
+    private stopped;
     constructor(opts: {
         creditsClient: CreditsClient;
         leaseStore: ILeaseStore;
@@ -48,12 +59,71 @@ export declare class CreditLeaseManager {
      *     that figure (a single check just failed a reserve for that many
      *     credits — extend opportunistically instead of waiting for the next
      *     sub-watermark check).
+     * A caller arriving while an extend is in flight joins it. If its own
+     * shortfall is larger than what that extend asked for, it waits the flight
+     * out and then issues exactly one follow-up extend for the remaining
+     * difference — otherwise it would inherit a tranche-sized ask and fail its
+     * post-extend retry with credits still sitting on the server. A flight it
+     * finds on the way back is only joined if that one covers the shortfall
+     * too; a smaller one is waited out, never inherited.
      * 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>;
+    maybeExtendInBackground(companyId: string, creditTypeId: string, requiredCredits?: number, requestOptions?: CreditsClient.RequestOptions, joinDeadlineMs?: number): Promise<LeaseEntry | undefined>;
+    private extendIfNeeded;
+    /** When a joiner's wait on a shared flight runs out, or undefined for no cap. */
+    private joinDeadline;
+    /**
+     * Await a flight somebody else is running, giving up at `deadline`. Giving
+     * up abandons only our wait: the flight keeps running for the callers still
+     * on it, and whatever it installs is there for our next check to read.
+     */
+    private joinWithin;
+    /**
+     * Read the slot, reporting `undefined` when the read fails or the lease is
+     * absent or expired. An expired lease is never extended: the server treats
+     * it as released (its remainder already refunded to the company balance),
+     * so the right move is a fresh acquire, which the next check's
+     * `acquireIfNeeded` performs. Extending would at best waste a wire call and
+     * at worst resurrect a stale local row.
+     */
+    private readLiveLease;
+    /** Whether `entry` sits low enough to warrant an extend. */
+    private needsExtend;
+    /**
+     * Register and run an extend as the slot's in-flight one. The cleanup is
+     * identity-guarded rather than an unconditional `delete`: a joiner whose
+     * shortfall outran this flight registers a follow-up for the same key, and
+     * this flight's `finally` must not evict it.
+     */
+    private startExtend;
+    /**
+     * Re-read the slot now that this flight owns it, and extend only if the
+     * fresh row still warrants one. The row that decided this extend was read
+     * before the flight was registered, so an extend that landed in that gap,
+     * clearing its own flight on the way out, would otherwise be followed by a
+     * second extend, under a new idempotency key, for a lease it already topped
+     * up. The registered `requestedAdditional` stands: a joiner compares its
+     * shortfall against that figure, so the wire body has to carry it.
+     */
+    private recheckAndExtend;
     private extend;
+    /** Hold a reference to unawaited work so `drain()` can wait it out. */
+    private track;
+    /**
+     * Refuse new lease work. Idempotent, and paired with `drain()`: stopping
+     * first is what makes the drain terminate, since nothing can enqueue
+     * behind it.
+     */
+    stop(): void;
+    /**
+     * Wait out lease work already on the wire, so a close releases what that
+     * work installs instead of orphaning it. Bounded: whatever has not landed
+     * by `timeoutMs` is abandoned rather than stalling the caller's shutdown,
+     * and the credits it holds fall back to server-side expiry.
+     */
+    drain(timeoutMs?: number): Promise<void>;
     /**
      * 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
@@ -63,6 +133,8 @@ export declare class CreditLeaseManager {
      * 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.
+     * Bounded by `timeoutMs`, so a store or wire call that never lands cannot
+     * hold a closing client open; whatever is abandoned expires server-side.
      */
-    releaseAllLocalLeases(): Promise<void>;
+    releaseAllLocalLeases(timeoutMs?: number): Promise<void>;
 }

package/dist/credits/lease-store.d.ts

@@ -21,6 +21,14 @@ export interface LeaseEntry {
     localRemainingCredits: number;
     expiresAt: Date;
 }
+/**
+ * Outcome of a successful `tryReserve`: the post-debit balance plus the ID of
+ * the lease the credits actually came out of.
+ */
+export interface ReserveResult {
+    balance: number;
+    leaseId: string;
+}
 /** Backing-store contract shared by `LeaseStore` (in-memory) and `RedisLeaseStore` (shared). */
 export interface ILeaseStore {
     get(companyId: string, creditTypeId: string): Promise<LeaseEntry | undefined> | LeaseEntry | undefined;
@@ -65,15 +73,23 @@ export interface ILeaseStore {
     drop(companyId: string, creditTypeId: string): Promise<void>;
     /**
      * Atomically check-and-debit `credits` from the lease's remaining balance.
-     * Returns the post-debit `localRemainingCredits` on success, or `null` if
-     * there is no live lease, the balance is insufficient, or `credits` is not
-     * a finite non-negative number (NaN must never reach the debit — it slips
-     * through every numeric comparison and would poison the balance into
-     * allowing everything). Returning the balance rather than a boolean lets
-     * the caller derive the pre-debit figure (`returned + credits`) without a
-     * follow-up read.
+     * Returns the post-debit `localRemainingCredits` together with the
+     * `leaseId` the debit landed on, or `null` if there is no live lease, the
+     * balance is insufficient, or `credits` is not a finite non-negative
+     * number (NaN must never reach the debit — it slips through every numeric
+     * comparison and would poison the balance into allowing everything).
+     * Returning the balance rather than a boolean lets the caller derive the
+     * pre-debit figure (`returned + credits`) without a follow-up read.
+     *
+     * The debit is NOT keyed by lease ID: it charges whichever lease occupies
+     * the slot at that moment, which need not be the one the caller's acquire
+     * handed back — the slot's lease can be replaced in between (by the
+     * sweeper, or by a sibling pod on a shared backend). The caller MUST
+     * therefore pin its reservation to the returned `leaseId`, never to the
+     * acquired one: the settle refund, the sweep refund, and the Track event's
+     * `lease_id` all have to name the lease that was actually charged.
      */
-    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | null>;
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<ReserveResult | null>;
     /**
      * Refund credits to the slot's lease balance (clamped at `grantedAmount`).
      * When `leaseId` is supplied, the refund applies ONLY if the slot still
@@ -126,10 +142,10 @@ export declare class LeaseStore implements ILeaseStore {
     drop(companyId: string, creditTypeId: string): Promise<void>;
     /**
      * Attempt to reserve `credits` from the local remaining balance.
-     * Returns the post-debit balance on success, `null` if there isn't enough
-     * remaining (see `ILeaseStore.tryReserve`).
+     * Returns the post-debit balance and the charged lease's ID on success,
+     * `null` if there isn't enough remaining (see `ILeaseStore.tryReserve`).
      */
-    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | null>;
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<ReserveResult | null>;
     /**
      * Refund credits back to the local balance (capped at grantedAmount).
      * When `leaseId` is given, the refund is dropped if the slot now holds a

package/dist/credits/redis-lease-store.d.ts

@@ -1,5 +1,5 @@
 import type { RedisClient } from "../cache/redis";
-import { type ILeaseStore, type LeaseEntry } from "./lease-store";
+import { type ILeaseStore, type LeaseEntry, type ReserveResult } from "./lease-store";
 /**
  * Redis-backed lease store. One hash per `(companyId, creditTypeId)` slot, with
  * atomic mutations via single-key Lua scripts so it stays correct on both
@@ -25,6 +25,6 @@ export declare class RedisLeaseStore implements ILeaseStore {
     replace(entry: Omit<LeaseEntry, "localRemainingCredits">): Promise<boolean>;
     extend(companyId: string, creditTypeId: string, grantedAmount: number, newExpiresAt?: Date, leaseId?: string): Promise<void>;
     drop(companyId: string, creditTypeId: string): Promise<void>;
-    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | null>;
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<ReserveResult | null>;
     refund(companyId: string, creditTypeId: string, credits: number, leaseId?: string): Promise<void>;
 }