mbase-sdk 0.0.8 → 0.0.9

package/dist/index.d.cts

@@ -204,7 +204,7 @@ type CheckRateLimit = {
 };
 type CheckResult = {
     /** Both gates: the capacity covers the quantity **and** every rate-limit
-     * window admits it. */
+     * window admits it. Under `no_cap` or a soft cap the capacity always does. */
     allowed: boolean;
     /** Unlimited for this meter. `available` is `null`. Rate limits still
      * apply — a customer who is never refused on capacity is the one a runaway
@@ -212,14 +212,19 @@ type CheckResult = {
     no_cap: boolean;
     /**
      * The whole capacity: the plan's unused entitlement for the current period,
-     * floored at 0, plus every open grant. `null` under `no_cap`, where capacity
-     * is not a number.
+     * floored at 0, plus what is left of a rollover carry, plus every open
+     * grant. `null` under `no_cap`, where capacity is not a number. Under a soft
+     * cap it is what is left of the included amount, and running out of it
+     * refuses nothing.
      *
      * One figure and no breakdown: `check` answers from a single cached integer,
      * and itemising where the capacity came from would cost it that. For the
      * per-grant detail, read `customers.allowances.list`.
      */
     available: number | null;
+    /** A soft cap: past `available`, only a rate limit refuses. `false`
+     * everywhere else, `no_cap` included. */
+    allow_overage: boolean;
     /** Which gate said no. Absent when allowed, so its presence is the denial
      * and reading it is never a branch on a truthy string. */
     reason?: CheckReason;
@@ -239,7 +244,7 @@ type CheckResult = {
  * `track` records work that already happened, so it never refuses on capacity
  * — the gate is `check`, which runs before the work. A quantity beyond the
  * customer's capacity is recorded, drives `available` to 0, and the next
- * `check` says no.
+ * `check` says no, unless the plan's cap is soft.
  */
 type TrackParams = {
     customer_id: string;
@@ -357,6 +362,12 @@ type PlanAllowance = {
     /** Units per period. `0` is legal and grants nothing. `null` under no_cap. */
     amount: number | null;
     no_cap: boolean;
+    /** A soft cap: once `amount` is used up, `check` and `reserve` admit rather
+     * than refuse, and the usage past it is overage. */
+    allow_overage: boolean;
+    /** What a period leaves unused of `amount` carries into the next, which
+     * spends it first. The carry lasts that one period. */
+    rollover: boolean;
     kind: PlanAllowanceKind;
     /** `one_time` only; `null` is a grant that never expires. */
     valid_for: Validity | null;
@@ -372,6 +383,12 @@ type PlanAllowanceSetParams = {
     meter_id: string;
     amount?: number;
     no_cap?: boolean;
+    /** A soft cap: past `amount`, admit rather than refuse. Defaults to `false`;
+     * refused beside `no_cap` and on `one_time`. */
+    allow_overage?: boolean;
+    /** Carry what a period leaves unused into the next. Defaults to `false`;
+     * refused beside `no_cap` and on `one_time`. */
+    rollover?: boolean;
     /** Defaults to `recurring`. */
     kind?: PlanAllowanceKind;
     /** `one_time` only. */
@@ -434,16 +451,30 @@ type PlanChangeNowParams = Omit<PlanChangeParams, "effective">;
 type PlanMoveParams = Pick<PlanChangeParams, "plan">;
 /** `awaiting`: the plan meters this, but its only versions land later. */
 type EntitlementState = "granted" | "awaiting";
-/** `used` counts toward `amount`; `total` adds what grants paid for. */
+/** `used` counts toward `amount`; `total` adds what the carry and grants paid
+ * for. */
 type MeterEntitlement = {
     meter_id: string;
     state: EntitlementState;
     version: PlanAllowance | null;
     amount: number | null;
     no_cap: boolean;
+    /** The version in effect's; `false` while `awaiting`. */
+    allow_overage: boolean;
+    /** The version in effect's; `false` while `awaiting`. */
+    rollover: boolean;
     used: number;
     total: number;
     remaining: number | null;
+    /** `max(used - amount, 0)`, under a hard cap too. `null` where `remaining`
+     * is. */
+    overage_used: number | null;
+    /** What the period before left unused and this one took in; `0` unless
+     * both versions roll over. `null` where `remaining` is. */
+    carried_in: number | null;
+    /** What this period has spent of `carried_in`, counted apart from `used`.
+     * `null` where `remaining` is. */
+    carried_used: number | null;
     reserved: number;
     available: number | null;
     incoming: {
@@ -463,6 +494,33 @@ type CustomerEntitlement = {
     };
     meters: MeterEntitlement[];
 };
+type ClosedPeriodParams = {
+    /** An RFC 3339 instant; omitted, now. To walk back, pass a period's `from`
+     * exactly as it came: a trip through a `Date` drops its microseconds. */
+    before?: string;
+};
+/** The entitlement meter at the period's last instant, less what describes
+ * now. `total - used - carried_used` is what grants absorbed. */
+type ClosedPeriodMeter = Omit<MeterEntitlement, "reserved" | "available" | "incoming"> & {
+    /** What it passed to the next period: `max(amount - used, 0)` under a
+     * version that rolled over, `0` otherwise. `null` where `remaining` is. */
+    carried_out: number | null;
+};
+/** `[from, to)`, final: nothing written after it restates it. */
+type ClosedPeriod = {
+    customer_id: string;
+    /** The plan in force at the period's last instant. */
+    plan_id: string;
+    cycle: PlanCycle;
+    /** When that plan took effect, as on the entitlement read. */
+    since: string;
+    /** Microseconds included: pass it back as `before` exactly as it came. */
+    from: string;
+    /** Its boundary, or the instant a reset closed it early. */
+    to: string;
+    /** One per meter that plan meters. */
+    meters: ClosedPeriodMeter[];
+};
 type UsagePeriod = "current" | "last";
 /** 1–90 UTC days, ending today. */
 type UsageDaysParams = {
@@ -604,7 +662,8 @@ type ThresholdCrossing = {
     } | null;
     /** A whole percent, 1–1000; past 100 is an overage alert. */
     threshold: number;
-    /** The plan's figures at the crossing; neither includes grants. */
+    /** The plan's figures at the crossing; neither includes grants or a
+     * carry. */
     used: number;
     entitlement: number;
     period: {
@@ -647,6 +706,20 @@ declare class CustomerAllowances$1 {
     revoke(customerId: string, allowanceId: string, options?: RequestOptions): Promise<Allowance>;
 }
 
+/** A customer's ended periods, exact from the engine's counters: the figures
+ * to bill from. */
+declare class CustomerPeriods$1 {
+    #private;
+    constructor(client: Client);
+    /**
+     * The newest period that has ended, or that ended at or before `before`;
+     * `null` when there is none. Walk back by passing each period's `from` as
+     * `before`, exactly as it came. Throws `PeriodSettlingError` for a minute
+     * after a period ends.
+     */
+    last(id: string, params?: ClosedPeriodParams, options?: RequestOptions): Promise<ClosedPeriod | null>;
+}
+
 /**
  * Which plan a customer holds. The history is append-only: there is no patch
  * and no delete, and moving a customer to a different plan is the same call as
@@ -752,6 +825,8 @@ declare class Customers$1 {
     readonly plan: CustomerPlan$1;
     /** Grants, which sit on top of whatever the plan gives. */
     readonly allowances: CustomerAllowances$1;
+    /** Periods that have ended, with the figures to bill them from. */
+    readonly periods: CustomerPeriods$1;
     constructor(client: Client);
     create(params: CustomerCreateParams, options?: RequestOptions): Promise<Customer>;
     /** Lean: a listing does not embed the plan. Read one customer for that. */
@@ -892,6 +967,17 @@ declare class ReservationMismatchError extends InvalidRequestError {
  */
 declare class CycleChangeRequiresResetError extends InvalidRequestError {
 }
+/**
+ * `409 period_settling`: the period ended under a minute ago and may still be
+ * taking writes. Read again after `retryAfter`; the SDK never retries it.
+ */
+declare class PeriodSettlingError extends ConflictError {
+    /** Seconds until the period is final, from `Retry-After`. */
+    readonly retryAfter: number | undefined;
+    constructor(args: ConstructorParameters<typeof APIError>[0] & {
+        retryAfter?: number | undefined;
+    });
+}
 declare class RateLimitError extends APIError {
     /** Seconds to wait, from `Retry-After`, when the engine sends one. */
     readonly retryAfter: number | undefined;
@@ -992,14 +1078,17 @@ declare class Meterbase {
      * to cover the quantity, and every rate-limit window in force has to admit
      * it. `reason` names the one that said no. `rate_limits` reports each window
      * whether or not it refused, so a caller can ease off as its headroom closes
-     * instead of discovering the ceiling by hitting it.
+     * instead of discovering the ceiling by hitting it. Under a soft cap
+     * (`allow_overage`) the capacity admits any quantity, so only a window can
+     * refuse.
      */
     check(params: CheckParams, options?: RequestOptions): Promise<CheckResult>;
     /**
      * Records usage that already happened — the tokens were spent, the image
      * was generated — so it never refuses on capacity. A quantity beyond the
      * customer's capacity is recorded, drives `available` to 0, and the next
-     * `check` says no. The answer is a receipt, not a verdict.
+     * `check` says no, unless the plan's cap is soft. The answer is a receipt,
+     * not a verdict.
      *
      * `idempotency_key` is a UUIDv7, generated when omitted, so retrying this
      * call — the SDK's own retries included — replays the original rather than
@@ -1039,10 +1128,11 @@ declare class Meterbase {
  * runtime binding the bundle never has.
  */
 type CustomerAllowances = InstanceType<typeof CustomerAllowances$1>;
+type CustomerPeriods = InstanceType<typeof CustomerPeriods$1>;
 type CustomerPlan = InstanceType<typeof CustomerPlan$1>;
 type Customers = InstanceType<typeof Customers$1>;
 type Meters = InstanceType<typeof Meters$1>;
 type PlanAllowances = InstanceType<typeof PlanAllowances$1>;
 type Plans = InstanceType<typeof Plans$1>;
 
-export { APIError, type Allowance, type AllowanceGrantParams, type AllowanceListParams, type AllowanceSource, type ApplyMode, type AssignPlanParams, type Assignment, AuthenticationError, type CheckParams, type CheckRateLimit, type CheckReason, type CheckResult, ConflictError, ConnectionError, type Customer, type CustomerAllowances, type CustomerCreateParams, type CustomerEntitlement, type CustomerListParams, type CustomerPlan, type CustomerUpdateParams, type CustomerUsage, type CustomerUsageParams, type CustomerWithPlan, type Customers, CycleChangeRequiresResetError, type DayUsage, type EmbeddedPlan, type EntitlementReachedEvent, type EntitlementState, type Hold, InvalidIdempotencyKeyError, InvalidRequestError, type List, type Meter, type MeterCreateParams, type MeterEntitlement, type MeterListParams, type MeterUpdateParams, type MeterUsage, type MeterUsageHistory, Meterbase, MeterbaseError, type MeterbaseOptions, type Meters, NotFoundError, PermissionDeniedError, type Plan, type PlanAllowance, type PlanAllowanceKind, type PlanAllowanceListParams, type PlanAllowanceSetParams, type PlanAllowances, type PlanChangeNowParams, type PlanChangeParams, type PlanCreateParams, type PlanCycle, type PlanListParams, type PlanMoveParams, type PlanUpdateParams, type Plans, RateLimitError, type Reconciliation, type RecordedReconciliation, type ReleaseParams, type ReleaseResult, type RequestOptions, ReservationMismatchError, type ReserveParams, type ReserveRefused, type ReserveResponse, type ReserveResult, ServerError, type ThresholdCrossedEvent, type ThresholdCrossing, TimeoutError, TooLateError, type TrackParams, type TrackResult, type UsageDaysParams, type UsageEvent, type UsagePeriod, type UsagePeriodParams, type Validity, type VerifyWebhookParams, type WebhookEvent, type WebhookHeaders, WebhookVerificationError, type WhoAmI, errorFromResponse, verifyWebhook };
+export { APIError, type Allowance, type AllowanceGrantParams, type AllowanceListParams, type AllowanceSource, type ApplyMode, type AssignPlanParams, type Assignment, AuthenticationError, type CheckParams, type CheckRateLimit, type CheckReason, type CheckResult, type ClosedPeriod, type ClosedPeriodMeter, type ClosedPeriodParams, ConflictError, ConnectionError, type Customer, type CustomerAllowances, type CustomerCreateParams, type CustomerEntitlement, type CustomerListParams, type CustomerPeriods, type CustomerPlan, type CustomerUpdateParams, type CustomerUsage, type CustomerUsageParams, type CustomerWithPlan, type Customers, CycleChangeRequiresResetError, type DayUsage, type EmbeddedPlan, type EntitlementReachedEvent, type EntitlementState, type Hold, InvalidIdempotencyKeyError, InvalidRequestError, type List, type Meter, type MeterCreateParams, type MeterEntitlement, type MeterListParams, type MeterUpdateParams, type MeterUsage, type MeterUsageHistory, Meterbase, MeterbaseError, type MeterbaseOptions, type Meters, NotFoundError, PeriodSettlingError, PermissionDeniedError, type Plan, type PlanAllowance, type PlanAllowanceKind, type PlanAllowanceListParams, type PlanAllowanceSetParams, type PlanAllowances, type PlanChangeNowParams, type PlanChangeParams, type PlanCreateParams, type PlanCycle, type PlanListParams, type PlanMoveParams, type PlanUpdateParams, type Plans, RateLimitError, type Reconciliation, type RecordedReconciliation, type ReleaseParams, type ReleaseResult, type RequestOptions, ReservationMismatchError, type ReserveParams, type ReserveRefused, type ReserveResponse, type ReserveResult, ServerError, type ThresholdCrossedEvent, type ThresholdCrossing, TimeoutError, TooLateError, type TrackParams, type TrackResult, type UsageDaysParams, type UsageEvent, type UsagePeriod, type UsagePeriodParams, type Validity, type VerifyWebhookParams, type WebhookEvent, type WebhookHeaders, WebhookVerificationError, type WhoAmI, errorFromResponse, verifyWebhook };

package/dist/index.d.ts

@@ -204,7 +204,7 @@ type CheckRateLimit = {
 };
 type CheckResult = {
     /** Both gates: the capacity covers the quantity **and** every rate-limit
-     * window admits it. */
+     * window admits it. Under `no_cap` or a soft cap the capacity always does. */
     allowed: boolean;
     /** Unlimited for this meter. `available` is `null`. Rate limits still
      * apply — a customer who is never refused on capacity is the one a runaway
@@ -212,14 +212,19 @@ type CheckResult = {
     no_cap: boolean;
     /**
      * The whole capacity: the plan's unused entitlement for the current period,
-     * floored at 0, plus every open grant. `null` under `no_cap`, where capacity
-     * is not a number.
+     * floored at 0, plus what is left of a rollover carry, plus every open
+     * grant. `null` under `no_cap`, where capacity is not a number. Under a soft
+     * cap it is what is left of the included amount, and running out of it
+     * refuses nothing.
      *
      * One figure and no breakdown: `check` answers from a single cached integer,
      * and itemising where the capacity came from would cost it that. For the
      * per-grant detail, read `customers.allowances.list`.
      */
     available: number | null;
+    /** A soft cap: past `available`, only a rate limit refuses. `false`
+     * everywhere else, `no_cap` included. */
+    allow_overage: boolean;
     /** Which gate said no. Absent when allowed, so its presence is the denial
      * and reading it is never a branch on a truthy string. */
     reason?: CheckReason;
@@ -239,7 +244,7 @@ type CheckResult = {
  * `track` records work that already happened, so it never refuses on capacity
  * — the gate is `check`, which runs before the work. A quantity beyond the
  * customer's capacity is recorded, drives `available` to 0, and the next
- * `check` says no.
+ * `check` says no, unless the plan's cap is soft.
  */
 type TrackParams = {
     customer_id: string;
@@ -357,6 +362,12 @@ type PlanAllowance = {
     /** Units per period. `0` is legal and grants nothing. `null` under no_cap. */
     amount: number | null;
     no_cap: boolean;
+    /** A soft cap: once `amount` is used up, `check` and `reserve` admit rather
+     * than refuse, and the usage past it is overage. */
+    allow_overage: boolean;
+    /** What a period leaves unused of `amount` carries into the next, which
+     * spends it first. The carry lasts that one period. */
+    rollover: boolean;
     kind: PlanAllowanceKind;
     /** `one_time` only; `null` is a grant that never expires. */
     valid_for: Validity | null;
@@ -372,6 +383,12 @@ type PlanAllowanceSetParams = {
     meter_id: string;
     amount?: number;
     no_cap?: boolean;
+    /** A soft cap: past `amount`, admit rather than refuse. Defaults to `false`;
+     * refused beside `no_cap` and on `one_time`. */
+    allow_overage?: boolean;
+    /** Carry what a period leaves unused into the next. Defaults to `false`;
+     * refused beside `no_cap` and on `one_time`. */
+    rollover?: boolean;
     /** Defaults to `recurring`. */
     kind?: PlanAllowanceKind;
     /** `one_time` only. */
@@ -434,16 +451,30 @@ type PlanChangeNowParams = Omit<PlanChangeParams, "effective">;
 type PlanMoveParams = Pick<PlanChangeParams, "plan">;
 /** `awaiting`: the plan meters this, but its only versions land later. */
 type EntitlementState = "granted" | "awaiting";
-/** `used` counts toward `amount`; `total` adds what grants paid for. */
+/** `used` counts toward `amount`; `total` adds what the carry and grants paid
+ * for. */
 type MeterEntitlement = {
     meter_id: string;
     state: EntitlementState;
     version: PlanAllowance | null;
     amount: number | null;
     no_cap: boolean;
+    /** The version in effect's; `false` while `awaiting`. */
+    allow_overage: boolean;
+    /** The version in effect's; `false` while `awaiting`. */
+    rollover: boolean;
     used: number;
     total: number;
     remaining: number | null;
+    /** `max(used - amount, 0)`, under a hard cap too. `null` where `remaining`
+     * is. */
+    overage_used: number | null;
+    /** What the period before left unused and this one took in; `0` unless
+     * both versions roll over. `null` where `remaining` is. */
+    carried_in: number | null;
+    /** What this period has spent of `carried_in`, counted apart from `used`.
+     * `null` where `remaining` is. */
+    carried_used: number | null;
     reserved: number;
     available: number | null;
     incoming: {
@@ -463,6 +494,33 @@ type CustomerEntitlement = {
     };
     meters: MeterEntitlement[];
 };
+type ClosedPeriodParams = {
+    /** An RFC 3339 instant; omitted, now. To walk back, pass a period's `from`
+     * exactly as it came: a trip through a `Date` drops its microseconds. */
+    before?: string;
+};
+/** The entitlement meter at the period's last instant, less what describes
+ * now. `total - used - carried_used` is what grants absorbed. */
+type ClosedPeriodMeter = Omit<MeterEntitlement, "reserved" | "available" | "incoming"> & {
+    /** What it passed to the next period: `max(amount - used, 0)` under a
+     * version that rolled over, `0` otherwise. `null` where `remaining` is. */
+    carried_out: number | null;
+};
+/** `[from, to)`, final: nothing written after it restates it. */
+type ClosedPeriod = {
+    customer_id: string;
+    /** The plan in force at the period's last instant. */
+    plan_id: string;
+    cycle: PlanCycle;
+    /** When that plan took effect, as on the entitlement read. */
+    since: string;
+    /** Microseconds included: pass it back as `before` exactly as it came. */
+    from: string;
+    /** Its boundary, or the instant a reset closed it early. */
+    to: string;
+    /** One per meter that plan meters. */
+    meters: ClosedPeriodMeter[];
+};
 type UsagePeriod = "current" | "last";
 /** 1–90 UTC days, ending today. */
 type UsageDaysParams = {
@@ -604,7 +662,8 @@ type ThresholdCrossing = {
     } | null;
     /** A whole percent, 1–1000; past 100 is an overage alert. */
     threshold: number;
-    /** The plan's figures at the crossing; neither includes grants. */
+    /** The plan's figures at the crossing; neither includes grants or a
+     * carry. */
     used: number;
     entitlement: number;
     period: {
@@ -647,6 +706,20 @@ declare class CustomerAllowances$1 {
     revoke(customerId: string, allowanceId: string, options?: RequestOptions): Promise<Allowance>;
 }
 
+/** A customer's ended periods, exact from the engine's counters: the figures
+ * to bill from. */
+declare class CustomerPeriods$1 {
+    #private;
+    constructor(client: Client);
+    /**
+     * The newest period that has ended, or that ended at or before `before`;
+     * `null` when there is none. Walk back by passing each period's `from` as
+     * `before`, exactly as it came. Throws `PeriodSettlingError` for a minute
+     * after a period ends.
+     */
+    last(id: string, params?: ClosedPeriodParams, options?: RequestOptions): Promise<ClosedPeriod | null>;
+}
+
 /**
  * Which plan a customer holds. The history is append-only: there is no patch
  * and no delete, and moving a customer to a different plan is the same call as
@@ -752,6 +825,8 @@ declare class Customers$1 {
     readonly plan: CustomerPlan$1;
     /** Grants, which sit on top of whatever the plan gives. */
     readonly allowances: CustomerAllowances$1;
+    /** Periods that have ended, with the figures to bill them from. */
+    readonly periods: CustomerPeriods$1;
     constructor(client: Client);
     create(params: CustomerCreateParams, options?: RequestOptions): Promise<Customer>;
     /** Lean: a listing does not embed the plan. Read one customer for that. */
@@ -892,6 +967,17 @@ declare class ReservationMismatchError extends InvalidRequestError {
  */
 declare class CycleChangeRequiresResetError extends InvalidRequestError {
 }
+/**
+ * `409 period_settling`: the period ended under a minute ago and may still be
+ * taking writes. Read again after `retryAfter`; the SDK never retries it.
+ */
+declare class PeriodSettlingError extends ConflictError {
+    /** Seconds until the period is final, from `Retry-After`. */
+    readonly retryAfter: number | undefined;
+    constructor(args: ConstructorParameters<typeof APIError>[0] & {
+        retryAfter?: number | undefined;
+    });
+}
 declare class RateLimitError extends APIError {
     /** Seconds to wait, from `Retry-After`, when the engine sends one. */
     readonly retryAfter: number | undefined;
@@ -992,14 +1078,17 @@ declare class Meterbase {
      * to cover the quantity, and every rate-limit window in force has to admit
      * it. `reason` names the one that said no. `rate_limits` reports each window
      * whether or not it refused, so a caller can ease off as its headroom closes
-     * instead of discovering the ceiling by hitting it.
+     * instead of discovering the ceiling by hitting it. Under a soft cap
+     * (`allow_overage`) the capacity admits any quantity, so only a window can
+     * refuse.
      */
     check(params: CheckParams, options?: RequestOptions): Promise<CheckResult>;
     /**
      * Records usage that already happened — the tokens were spent, the image
      * was generated — so it never refuses on capacity. A quantity beyond the
      * customer's capacity is recorded, drives `available` to 0, and the next
-     * `check` says no. The answer is a receipt, not a verdict.
+     * `check` says no, unless the plan's cap is soft. The answer is a receipt,
+     * not a verdict.
      *
      * `idempotency_key` is a UUIDv7, generated when omitted, so retrying this
      * call — the SDK's own retries included — replays the original rather than
@@ -1039,10 +1128,11 @@ declare class Meterbase {
  * runtime binding the bundle never has.
  */
 type CustomerAllowances = InstanceType<typeof CustomerAllowances$1>;
+type CustomerPeriods = InstanceType<typeof CustomerPeriods$1>;
 type CustomerPlan = InstanceType<typeof CustomerPlan$1>;
 type Customers = InstanceType<typeof Customers$1>;
 type Meters = InstanceType<typeof Meters$1>;
 type PlanAllowances = InstanceType<typeof PlanAllowances$1>;
 type Plans = InstanceType<typeof Plans$1>;
 
-export { APIError, type Allowance, type AllowanceGrantParams, type AllowanceListParams, type AllowanceSource, type ApplyMode, type AssignPlanParams, type Assignment, AuthenticationError, type CheckParams, type CheckRateLimit, type CheckReason, type CheckResult, ConflictError, ConnectionError, type Customer, type CustomerAllowances, type CustomerCreateParams, type CustomerEntitlement, type CustomerListParams, type CustomerPlan, type CustomerUpdateParams, type CustomerUsage, type CustomerUsageParams, type CustomerWithPlan, type Customers, CycleChangeRequiresResetError, type DayUsage, type EmbeddedPlan, type EntitlementReachedEvent, type EntitlementState, type Hold, InvalidIdempotencyKeyError, InvalidRequestError, type List, type Meter, type MeterCreateParams, type MeterEntitlement, type MeterListParams, type MeterUpdateParams, type MeterUsage, type MeterUsageHistory, Meterbase, MeterbaseError, type MeterbaseOptions, type Meters, NotFoundError, PermissionDeniedError, type Plan, type PlanAllowance, type PlanAllowanceKind, type PlanAllowanceListParams, type PlanAllowanceSetParams, type PlanAllowances, type PlanChangeNowParams, type PlanChangeParams, type PlanCreateParams, type PlanCycle, type PlanListParams, type PlanMoveParams, type PlanUpdateParams, type Plans, RateLimitError, type Reconciliation, type RecordedReconciliation, type ReleaseParams, type ReleaseResult, type RequestOptions, ReservationMismatchError, type ReserveParams, type ReserveRefused, type ReserveResponse, type ReserveResult, ServerError, type ThresholdCrossedEvent, type ThresholdCrossing, TimeoutError, TooLateError, type TrackParams, type TrackResult, type UsageDaysParams, type UsageEvent, type UsagePeriod, type UsagePeriodParams, type Validity, type VerifyWebhookParams, type WebhookEvent, type WebhookHeaders, WebhookVerificationError, type WhoAmI, errorFromResponse, verifyWebhook };
+export { APIError, type Allowance, type AllowanceGrantParams, type AllowanceListParams, type AllowanceSource, type ApplyMode, type AssignPlanParams, type Assignment, AuthenticationError, type CheckParams, type CheckRateLimit, type CheckReason, type CheckResult, type ClosedPeriod, type ClosedPeriodMeter, type ClosedPeriodParams, ConflictError, ConnectionError, type Customer, type CustomerAllowances, type CustomerCreateParams, type CustomerEntitlement, type CustomerListParams, type CustomerPeriods, type CustomerPlan, type CustomerUpdateParams, type CustomerUsage, type CustomerUsageParams, type CustomerWithPlan, type Customers, CycleChangeRequiresResetError, type DayUsage, type EmbeddedPlan, type EntitlementReachedEvent, type EntitlementState, type Hold, InvalidIdempotencyKeyError, InvalidRequestError, type List, type Meter, type MeterCreateParams, type MeterEntitlement, type MeterListParams, type MeterUpdateParams, type MeterUsage, type MeterUsageHistory, Meterbase, MeterbaseError, type MeterbaseOptions, type Meters, NotFoundError, PeriodSettlingError, PermissionDeniedError, type Plan, type PlanAllowance, type PlanAllowanceKind, type PlanAllowanceListParams, type PlanAllowanceSetParams, type PlanAllowances, type PlanChangeNowParams, type PlanChangeParams, type PlanCreateParams, type PlanCycle, type PlanListParams, type PlanMoveParams, type PlanUpdateParams, type Plans, RateLimitError, type Reconciliation, type RecordedReconciliation, type ReleaseParams, type ReleaseResult, type RequestOptions, ReservationMismatchError, type ReserveParams, type ReserveRefused, type ReserveResponse, type ReserveResult, ServerError, type ThresholdCrossedEvent, type ThresholdCrossing, TimeoutError, TooLateError, type TrackParams, type TrackResult, type UsageDaysParams, type UsageEvent, type UsagePeriod, type UsagePeriodParams, type Validity, type VerifyWebhookParams, type WebhookEvent, type WebhookHeaders, WebhookVerificationError, type WhoAmI, errorFromResponse, verifyWebhook };

package/dist/index.js

@@ -43,6 +43,14 @@ var ReservationMismatchError = class extends InvalidRequestError {
 };
 var CycleChangeRequiresResetError = class extends InvalidRequestError {
 };
+var PeriodSettlingError = class extends ConflictError {
+  /** Seconds until the period is final, from `Retry-After`. */
+  retryAfter;
+  constructor(args) {
+    super(args);
+    this.retryAfter = args.retryAfter;
+  }
+};
 var RateLimitError = class extends APIError {
   /** Seconds to wait, from `Retry-After`, when the engine sends one. */
   retryAfter;
@@ -59,6 +67,14 @@ var TimeoutError = class extends ConnectionError {
 };
 function errorFromResponse(args) {
   switch (args.status) {
+    case 400:
+      switch (args.code) {
+        // A parameter that failed validation, as a 422 is a field that did.
+        case "invalid_query":
+          return new InvalidRequestError(args);
+        default:
+          return new APIError(args);
+      }
     case 401:
       return new AuthenticationError(args);
     case 403:
@@ -66,7 +82,12 @@ function errorFromResponse(args) {
     case 404:
       return new NotFoundError(args);
     case 409:
-      return new ConflictError(args);
+      switch (args.code) {
+        case "period_settling":
+          return new PeriodSettlingError(args);
+        default:
+          return new ConflictError(args);
+      }
     case 422:
       switch (args.code) {
         case "cycle_change_requires_reset":
@@ -317,6 +338,35 @@ var CustomerAllowances = class {
   }
 };
 
+// src/resources/customer-periods.ts
+var CustomerPeriods = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * The newest period that has ended, or that ended at or before `before`;
+   * `null` when there is none. Walk back by passing each period's `from` as
+   * `before`, exactly as it came. Throws `PeriodSettlingError` for a minute
+   * after a period ends.
+   */
+  async last(id, params = {}, options) {
+    try {
+      return await this.#client.request({
+        ...options,
+        method: "GET",
+        path: `/v1/customers/${encodeURIComponent(id)}/periods/last`,
+        query: { before: params.before }
+      });
+    } catch (error) {
+      if (error instanceof NotFoundError && (error.code === "no_plan_assigned" || error.code === "no_previous_period")) {
+        return null;
+      }
+      throw error;
+    }
+  }
+};
+
 // src/resources/customer-plan.ts
 var CustomerPlan = class {
   #client;
@@ -475,11 +525,14 @@ var Customers = class {
   plan;
   /** Grants, which sit on top of whatever the plan gives. */
   allowances;
+  /** Periods that have ended, with the figures to bill them from. */
+  periods;
   #client;
   constructor(client) {
     this.#client = client;
     this.plan = new CustomerPlan(client);
     this.allowances = new CustomerAllowances(client);
+    this.periods = new CustomerPeriods(client);
   }
   create(params, options) {
     return this.#client.request({
@@ -806,7 +859,9 @@ var Meterbase = class {
    * to cover the quantity, and every rate-limit window in force has to admit
    * it. `reason` names the one that said no. `rate_limits` reports each window
    * whether or not it refused, so a caller can ease off as its headroom closes
-   * instead of discovering the ceiling by hitting it.
+   * instead of discovering the ceiling by hitting it. Under a soft cap
+   * (`allow_overage`) the capacity admits any quantity, so only a window can
+   * refuse.
    */
   check(params, options) {
     return this.#client.request({
@@ -820,7 +875,8 @@ var Meterbase = class {
    * Records usage that already happened — the tokens were spent, the image
    * was generated — so it never refuses on capacity. A quantity beyond the
    * customer's capacity is recorded, drives `available` to 0, and the next
-   * `check` says no. The answer is a receipt, not a verdict.
+   * `check` says no, unless the plan's cap is soft. The answer is a receipt,
+   * not a verdict.
    *
    * `idempotency_key` is a UUIDv7, generated when omitted, so retrying this
    * call — the SDK's own retries included — replays the original rather than
@@ -1002,6 +1058,6 @@ function idempotencyKey(atMs) {
   ].join("-");
 }
 
-export { APIError, AuthenticationError, ConflictError, ConnectionError, CycleChangeRequiresResetError, InvalidIdempotencyKeyError, InvalidRequestError, Meterbase, MeterbaseError, NotFoundError, PermissionDeniedError, RateLimitError, ReservationMismatchError, ServerError, TimeoutError, TooLateError, WebhookVerificationError, errorFromResponse, verifyWebhook };
+export { APIError, AuthenticationError, ConflictError, ConnectionError, CycleChangeRequiresResetError, InvalidIdempotencyKeyError, InvalidRequestError, Meterbase, MeterbaseError, NotFoundError, PeriodSettlingError, PermissionDeniedError, RateLimitError, ReservationMismatchError, ServerError, TimeoutError, TooLateError, WebhookVerificationError, errorFromResponse, verifyWebhook };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map