mbase-sdk 0.0.8 → 0.0.9

package/README.md

@@ -48,10 +48,11 @@ denial — that is an answer, not a failure. Absence of entitlement is not
 permission: a customer with no plan and no grant is denied.
 
 `available` is the whole capacity — the plan's unused entitlement for the
-current period plus every open grant — and is `null` under `no_cap`, where
-capacity is not a number. It is one figure and not a 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 a customer's allowances.
+current period, plus what is left of a [rollover](#plan-allowances) carry, plus
+every open grant — and is `null` under `no_cap`, where capacity is not a
+number. It is one figure and not a 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 a customer's allowances.
 
 A check answers **two gates**, and `allowed` needs both: the capacity has to
 cover the quantity, and every rate limit in force — _at most so much of this
@@ -63,12 +64,20 @@ applies. A limit is protective and not commercial, so it is never folded into
 `available`: a customer well inside their plan can still be limited, and one on
 `no_cap` is precisely the customer a runaway loop costs most.
 
+Under a **soft cap** — included usage, then overage; see
+[Plan allowances](#plan-allowances) — the capacity admits any quantity, so only
+a rate limit can refuse. `available` is what is left of the included amount and
+stops at 0, `allow_overage: true` says why a quantity past it was still
+allowed, and the overage in a request is `Math.max(quantity - available, 0)`.
+`allow_overage` is `false` everywhere else, `no_cap` included.
+
 ### Recording usage
 
 `track` counts work 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, with no verdict and nothing to branch on:
+says no, unless the cap is [soft](#plan-allowances). The answer is a receipt,
+with no verdict and nothing to branch on:
 
 ```ts
 const { event } = await meterbase.track({
@@ -164,6 +173,7 @@ read — refusals included — so it is not the call to put in front of cheap wo
 
 A reserve answers everything `check` answers, plus the hold: `reservation_id`,
 the `quantity` it set aside, and `expires_at`. `available` is already net of it.
+Past a soft cap it holds rather than refuses, and `available` stops at 0.
 A refusal holds nothing, so it carries no id and no expiry, and `allowed`
 narrows the type — after `if (!hold.allowed)`, `commit` and `release` are there.
 
@@ -311,6 +321,50 @@ const { data } = await meterbase.plans.allowances.list(plan.id)
 Each `(plan, meter)` pair carries up to two lineages, `recurring` and
 `one_time`, numbering themselves separately. `kind` defaults to `recurring`.
 
+**A soft cap** keeps the amount and drops the refusal: included usage, then
+overage.
+
+```ts
+await meterbase.plans.allowances.set(plan.id, {
+  meter_id: meter.id,
+  amount: 5_000,
+  allow_overage: true,
+})
+```
+
+Once `amount` is used up, `check` and `reserve` admit rather than refuse, with
+`allow_overage: true` on the answer, and the usage past it is overage: read it
+as `overage_used` on [the entitlement](#how-much-they-have-used). Rate limits
+still refuse, thresholds still fire — a mark over 100 is an overage alert — and
+a grant is spent before any overage is. `allow_overage` defaults to `false` and
+is refused beside `no_cap` and on `one_time`. Like the amount, it is a term of
+the version, so turning it on or off follows `apply_mode`: at each customer's
+next cycle by default.
+
+**Rollover** carries what a period leaves unused of `amount` into the next
+period, which spends it first.
+
+```ts
+await meterbase.plans.allowances.set(plan.id, {
+  meter_id: meter.id,
+  amount: 1_000,
+  rollover: true,
+})
+```
+
+A customer who uses 300 of September's 1,000 starts October with 1,700: the
+700 carried goes first, and whatever October leaves of it is lost. A carry
+lasts one period and never stacks, because only a period's own amount rolls on.
+Both periods' versions have to roll over, so a move to a plan that does not
+ends the carry, and a `restart` passes nothing on. `check` and `reserve` count
+what is left of the carry in `available`; read it as `carried_in` and
+`carried_used` on [the entitlement](#how-much-they-have-used). Thresholds
+measure the amount alone, so usage the carry paid reaches no mark. `rollover`
+defaults to `false`, is refused beside `no_cap` and on `one_time`, and is
+allowed beside `allow_overage`, where the carry is spent before any overage.
+It follows `apply_mode` like the amount, and the first carry arrives a boundary
+after the version lands.
+
 ### A customer's plan
 
 A customer's plan is an append-only history, not a field: assigning is the only
@@ -429,13 +483,60 @@ for (const meter of entitlement?.meters ?? []) {
 
 `entitlement` is the plan's side of the current period, one entry per meter the
 plan meters: the read behind a usage bar in your own app. `used` is what
-`amount` is measured against, `total` adds what grants paid for, and
-`available` is what `check` would answer. Meters are named by id, and like
-`retrieve` it is `null` for a customer holding no plan.
+`amount` is measured against, `total` adds what the carry and grants paid for,
+and `available` is what `check` would answer. `overage_used` is how far `used`
+has run past `amount` — what a [soft cap](#plan-allowances) bills for, and
+reported under a hard cap too — and `null` where there is no amount;
+`allow_overage` says whether the cap in effect is soft. `carried_in` is what
+the period before left unused and this one took in, `0` unless both versions
+[roll over](#plan-allowances), and `carried_used` is what this period has spent
+of it; what is left of it when the period ends is lost. Both are `null` where
+there is no amount, and `carried_in` settles a minute after the boundary, with
+the period it comes from. `rollover` says whether the version in effect rolls
+over. Meters are named by id, and like `retrieve` it is `null` for a customer
+holding no plan.
 
 Unlike `check`, it is not answered from a cache, so read it where usage is
 shown rather than on every request.
 
+#### Closed periods
+
+`customers.periods.last` is the newest period that has ended, with the figures
+to bill from: per meter, the cap `check` answered at its last instant, `used`
+against it, and `overage_used`, which is what a soft cap bills. `carried_in`
+and `carried_used` are what a [rolling](#plan-allowances) allowance took from
+the period before and spent of it, `carried_out` what it passed to the next,
+and `total - used - carried_used` is what grants absorbed. They come from the
+counters behind `check`, which count each event exactly once.
+[Usage by day](#usage-by-day) is for where usage went, not for billing.
+
+A billing job reads the newest, then walks back by passing each `from` as
+`before`, until it reaches the `to` it last billed. `null` ends the walk:
+nothing closed before that, or no plan at all.
+
+```ts
+const unbilled: ClosedPeriod[] = []
+let period = await meterbase.customers.periods.last(customer.id)
+
+while (period && period.to !== lastBilledTo) {
+  unbilled.unshift(period) // oldest first
+  period = await meterbase.customers.periods.last(customer.id, {
+    before: period.from, // exactly as it came
+  })
+}
+```
+
+**Pass `from` back verbatim.** It carries microseconds and a `Date` keeps
+milliseconds, so a `before` that went through a `Date` lands inside the older
+period and skips it. That is why `before` is a string. Keep `to` as it came
+too: it is what the loop compares.
+
+For a minute after a period ends, while a track dated inside it may still be
+committing, `last` throws `PeriodSettlingError`. Read again after its
+`retryAfter` seconds; from then on the answer never changes. It is not retried
+for you: the wait runs to a minute, and whether to sit it out is the job's
+call.
+
 #### Usage by day
 
 ```ts
@@ -508,8 +609,9 @@ secret, shown once when you add it and revealable from its settings.
 ```
 
 `used` and `entitlement` are the plan's figures at the crossing; neither counts
-grants, so ask `check` for capacity. `entitlement.reached` marks the plan's
-entitlement, not spent capacity: a grant can still have balance.
+grants or a carry, so ask `check` for capacity. `entitlement.reached` marks the
+plan's entitlement, not spent capacity: a grant can still have balance, and a
+soft cap admits past it.
 
 ### Verifying a delivery
 
@@ -608,7 +710,8 @@ try {
 | `PermissionDeniedError`            | 403 — the key may not use this route                                                                                                    |
 | `NotFoundError`                    | 404                                                                                                                                     |
 | `ConflictError`                    | 409 — a key or external id is taken                                                                                                     |
-| `InvalidRequestError`              | 422 — a field failed validation                                                                                                         |
+| `PeriodSettlingError`              | 409 — a `ConflictError`: the period ended under a minute ago, so read it again after `retryAfter` seconds                               |
+| `InvalidRequestError`              | 422 — a field failed validation; or `400 invalid_query`, a query parameter that did                                                     |
 | `CycleChangeRequiresResetError`    | 422 — an `InvalidRequestError`: the two plans' cycles differ, so use `restart`                                                          |
 | `InvalidIdempotencyKeyError`       | 422 — an `InvalidRequestError`: the key was not a UUIDv7                                                                                |
 | `TooLateError`                     | 422 — an `InvalidRequestError`: the key is over an hour from the engine's clock, which it carries on `serverTime`. Nothing was recorded |
@@ -731,6 +834,13 @@ and the minted bonus summed into `available`; that tracked usage takes exactly
 that much away, that a replay takes nothing, and that a reused key naming a
 different event is refused; that a rate limit set on a meter comes back on
 every `check` as a live window, and refuses with the allowance untouched; that
+a soft cap admits and holds past its amount and reports the overage, and that
+`allow_overage` is refused beside `no_cap` and on a one-time bonus; that a
+period a `restart` closes settles for a minute, which the run waits out, and
+then reads final with the overage it closed on; that a rolling allowance
+carries what a period left unused into the next, which spends it first, and
+the closed period reads what it passed on, and that `rollover` is refused
+beside `no_cap` and on a one-time bonus; that
 a scheduled plan change is dated ahead and reads as `pending`, that cancelling
 it supersedes it, that a `restart` re-anchors the customer, and that two plans
 on different cycles refuse a scheduled change; that soft deletes and archiving

package/dist/index.cjs

@@ -45,6 +45,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;
@@ -61,6 +69,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:
@@ -68,7 +84,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":
@@ -319,6 +340,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;
@@ -477,11 +527,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({
@@ -808,7 +861,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({
@@ -822,7 +877,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
@@ -1014,6 +1070,7 @@ exports.InvalidRequestError = InvalidRequestError;
 exports.Meterbase = Meterbase;
 exports.MeterbaseError = MeterbaseError;
 exports.NotFoundError = NotFoundError;
+exports.PeriodSettlingError = PeriodSettlingError;
 exports.PermissionDeniedError = PermissionDeniedError;
 exports.RateLimitError = RateLimitError;
 exports.ReservationMismatchError = ReservationMismatchError;