mbase-sdk 0.0.2 → 0.0.5

package/README.md

@@ -12,20 +12,25 @@ npm install @meterbase/sdk
 
 ## Usage
 
-Two calls, in this order: **`check` → do the work → `track`.**
+Two calls, in this order: **`check` → do the work → `track`** — or, for work
+that must not be done twice, [`reserve`](#work-you-cannot-do-twice).
 
 ```ts
 import { Meterbase } from "@meterbase/sdk"
 
 const meterbase = new Meterbase({ apiKey: process.env.METERBASE_API_KEY! })
 
-const { allowed } = await meterbase.check({
+const { allowed, reason, rate_limits } = await meterbase.check({
   customer_id: "acct_1", // the tenant's own id, not ours
   meter_id: "ai_tokens", // the meter's key, not ours
   quantity: 50_000, // what you are about to spend; defaults to 1
 })
 
-if (!allowed) throw new Error("Out of quota")
+if (!allowed) throw new Error(`Refused: ${reason}`)
+
+// Allowed, and still worth reading: every window comes back on every call.
+const tight = rate_limits.find((w) => w.remaining < w.max / 10)
+if (tight) console.warn(`Slowing down until ${tight.resets_at}`)
 
 const completion = await generate(prompt)
 
@@ -48,6 +53,16 @@ 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
+meter per minute, hour or day_ — has to admit it. `reason` names the one that
+said no, and is absent when the answer is yes. `rate_limits` reports every
+window whether or not it refused, so a caller can ease off as its headroom
+closes instead of finding the ceiling by hitting it; it is `[]` when no rule
+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.
+
 ### Recording usage
 
 `track` counts work that already happened — the tokens were spent, the image
@@ -60,7 +75,7 @@ const { event } = await meterbase.track({
   customer_id: "acct_1",
   meter_id: "ai_tokens",
   quantity: 250_000,
-  idempotency_key: "req_9f3a", // generated when you omit it
+  idempotency_key: "0199e0c0-8f3a-7c21-9d44-6b2e91a0f5c3", // a UUIDv7; generated when you omit it
 })
 
 event.replayed // false the first time, true for a retry of the same call
@@ -75,16 +90,37 @@ bill drawn from a period is never moved by a report that arrives after it.
 
 #### Idempotency
 
-`customer_id` + `idempotency_key` identifies one logical event.
-
-| The retry sends                  | The engine answers                                        |
-| -------------------------------- | --------------------------------------------------------- |
-| the same key, meter and quantity | the original event with `replayed: true`, writing nothing |
-| the same key, a different event  | `409 idempotency_conflict`, naming the original           |
-
-The timestamp is deliberately not compared: every call is stamped with its own
-clock, so a retry carries a later one, and refusing that would punish the
-ordinary retry. The original's timestamp comes back unchanged.
+`idempotency_key` identifies one logical event, and **is** that event's id.
+It has to be a **UUIDv7**, whose first 48 bits are the millisecond it was
+minted. That timestamp is not decoration: the engine admits a key only while
+it is within **one hour** of the engine's clock, and keeps the claim behind it
+until exactly that hour is up. A retry is therefore recognised for as long as
+it is accepted at all.
+
+| The call sends                        | The engine answers                                |
+| ------------------------------------- | ------------------------------------------------- |
+| a fresh key                           | the recorded event, `replayed: false`             |
+| a key it has already seen             | that event with `replayed: true`, writing nothing |
+| a key more than an hour old, or ahead | `422 too_late`, writing nothing                   |
+| anything that is not a UUIDv7         | `422 invalid_idempotency_key`, writing nothing    |
+
+A key it has already seen replays **whatever the rest of the body says**:
+there is one claim behind the key and nothing to compare a retry against, so
+a changed quantity is a replay rather than an error. The upside is that a
+replay costs one lookup and stores nothing.
+
+**The hour is a retry budget.** Retry inside it and your call is recognised.
+Past it, `too_late` — and do not then resend under a fresh key, because the
+original may have been recorded. Nothing is written on either refusal: both
+are checked before the engine touches anything.
+
+**Clocks matter now.** The key is minted here, from this machine's clock, so
+a device running more than an hour off would have every call refused. When
+this SDK mints the key it handles that itself: `too_late` carries the engine's
+`server_time`, the client corrects its offset and retries once, and you never
+see the error. When **you** supply the key, you get `TooLateError` with
+`serverTime` on it, because only you can know whether that key names work that
+was already recorded.
 
 **The SDK generates a key when you omit one, and reuses it across that call's
 retries** — including its own, since `track` is the one `POST` it will replay.
@@ -93,6 +129,68 @@ request id — so that a retry from further out than this SDK replays too. Keys
 are retained 35 days; a retry after that records a second event, which is not a
 case this API sets out to serve.
 
+### Work you cannot do twice
+
+`check` → work → `track` has a hole: two concurrent callers both pass the gate,
+both do the work, and both record it. For an API call that costs nothing that
+is an accepted trade. For an LLM completion, an image, a transcode, it is the
+whole problem — the customer is over their cap and the money is already spent.
+
+`reserve` closes it. It makes the same decision `check` makes and then **holds**
+the capacity, so two reserves for the same last units cannot both be granted:
+
+```ts
+const hold = await meterbase.reserve({
+  customer_id: "acct_1",
+  meter_id: "ai_tokens",
+  quantity: 50_000, // what you are about to spend; defaults to 1
+  expires_in_seconds: 60, // how long to hold it; defaults to 60, at most 900
+})
+
+if (!hold.allowed) throw new Error(`Refused: ${hold.reason}`)
+
+try {
+  const completion = await generate(prompt)
+  await hold.commit(completion.usage.total_tokens) // records what it cost
+} catch (error) {
+  await hold.release() // nothing happened, so nothing is recorded
+  throw error
+}
+```
+
+**The rule for choosing: can you afford to do the work twice? `check`. No?
+`reserve`.** A reserve costs a database transaction where a check costs a cached
+read — refusals included — so it is not the call to put in front of cheap work.
+
+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.
+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.
+
+`commit` is `track` under the hold's own id, which is what makes it a commit
+rather than a second event beside it. Pass what the work actually cost and the
+difference comes back; omit it to record what was held. Going over is allowed —
+the hold only ever guaranteed what it reserved.
+
+`release` gives the capacity back and records nothing. It is built for the
+`catch` block, so it resolves with `null` instead of throwing when there is
+nothing left to release — already committed, already released — because
+throwing there would mask the error you are already handling.
+`meterbase.release({ reservation_id })` throws that 404, as every other call
+does.
+
+**Nothing is lost if your process dies.** A hold expires on its own, and the
+capacity comes back with nothing having run. A commit that arrives after
+`expires_at` is still recorded — you lose the guarantee, not the event — and
+the SDK warns when that happens, which is the only feedback there is on an
+`expires_in_seconds` guessed too short.
+
+`reservation_id` is a UUIDv7 on the same terms as `idempotency_key`, generated
+when you omit it, and it becomes the event's id once the hold is committed. One
+id names the hold, the claim and the event. An id is for one reserve and its
+retries: once its hold is committed or released, sending it again reserves
+afresh rather than finding anything.
+
 ### Customers
 
 ```ts
@@ -362,18 +460,19 @@ try {
 }
 ```
 
-| Class                              | When                                                                                     |
-| ---------------------------------- | ---------------------------------------------------------------------------------------- |
-| `AuthenticationError`              | 401 — unknown, revoked or malformed key                                                  |
-| `PermissionDeniedError`            | 403 — the key may not use this route                                                     |
-| `NotFoundError`                    | 404                                                                                      |
-| `ConflictError`                    | 409 — a key or external id is taken                                                      |
-| `IdempotencyConflictError`         | 409 — a `ConflictError` naming the event that key already recorded, on `existingEventId` |
-| `InvalidRequestError`              | 422 — a field failed validation                                                          |
-| `CycleChangeRequiresResetError`    | 422 — an `InvalidRequestError`: the two plans' cycles differ, so use `restart`           |
-| `RateLimitError`                   | 429                                                                                      |
-| `ServerError`                      | 5xx                                                                                      |
-| `ConnectionError` / `TimeoutError` | the request never got an answer                                                          |
+| Class                              | When                                                                                                                                    |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `AuthenticationError`              | 401 — unknown, revoked or malformed key                                                                                                 |
+| `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                                                                                                         |
+| `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 |
+| `RateLimitError`                   | 429                                                                                                                                     |
+| `ServerError`                      | 5xx                                                                                                                                     |
+| `ConnectionError` / `TimeoutError` | the request never got an answer                                                                                                         |
 
 `APIError` carries `status`, `code` and the parsed `body`. Branch on `code`,
 which is stable; `message` is for humans and may change.
@@ -405,7 +504,8 @@ because a retried create could produce a second row.
 SDK fixes that key **before** the retry loop starts: every attempt of one call
 names the same logical event, so the engine replays it instead of counting the
 work twice. If you retry `track` yourself, pass your own `idempotency_key` and
-keep it the same across attempts for exactly that reason.
+keep it the same across attempts for exactly that reason — and do it inside
+the hour the engine holds that key for.
 
 ## Types
 
@@ -481,11 +581,12 @@ It asserts the whole lifecycle of a customer, a meter and a plan; that a plan's
 allowances become real entitlement a `check` can see, with the recurring cap
 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 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 behave as
-documented; that duplicates really answer
+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 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
+behave as documented; that duplicates really answer
 `409 customer_external_id_taken` / `409 meter_key_taken`; and — via
 `Record<keyof T, true>` field maps — that the engine's fields still match the
 SDK's types exactly, in both directions.

package/dist/index.cjs

@@ -29,16 +29,19 @@ var NotFoundError = class extends APIError {
 };
 var ConflictError = class extends APIError {
 };
-var IdempotencyConflictError = class extends ConflictError {
-  /** The event that key already recorded. Undefined only if the engine sent a
-   * body this could not be read out of. */
-  existingEventId;
+var InvalidRequestError = class extends APIError {
+};
+var InvalidIdempotencyKeyError = class extends InvalidRequestError {
+};
+var TooLateError = class extends InvalidRequestError {
+  /** The engine's clock when it refused. */
+  serverTime;
   constructor(args) {
     super(args);
-    this.existingEventId = existingEventId(args.body);
+    this.serverTime = serverTime(args.body);
   }
 };
-var InvalidRequestError = class extends APIError {
+var ReservationMismatchError = class extends InvalidRequestError {
 };
 var CycleChangeRequiresResetError = class extends InvalidRequestError {
 };
@@ -65,21 +68,34 @@ function errorFromResponse(args) {
     case 404:
       return new NotFoundError(args);
     case 409:
-      return args.code === "idempotency_conflict" ? new IdempotencyConflictError(args) : new ConflictError(args);
+      return new ConflictError(args);
     case 422:
-      return args.code === "cycle_change_requires_reset" ? new CycleChangeRequiresResetError(args) : new InvalidRequestError(args);
+      switch (args.code) {
+        case "cycle_change_requires_reset":
+          return new CycleChangeRequiresResetError(args);
+        case "invalid_idempotency_key":
+          return new InvalidIdempotencyKeyError(args);
+        case "reservation_mismatch":
+          return new ReservationMismatchError(args);
+        case "too_late":
+          return new TooLateError(args);
+        default:
+          return new InvalidRequestError(args);
+      }
     case 429:
       return new RateLimitError(args);
     default:
       return args.status >= 500 ? new ServerError(args) : new APIError(args);
   }
 }
-function existingEventId(body) {
+function serverTime(body) {
   if (typeof body !== "object" || body === null) return void 0;
   const error = body.error;
   if (typeof error !== "object" || error === null) return void 0;
-  const id = error.existing_event_id;
-  return typeof id === "string" ? id : void 0;
+  const at = error.server_time;
+  if (typeof at !== "string") return void 0;
+  const parsed = new Date(at);
+  return Number.isNaN(parsed.getTime()) ? void 0 : parsed;
 }
 
 // src/client.ts
@@ -93,6 +109,21 @@ var Client = class {
   #timeout;
   #maxRetries;
   #fetch;
+  /**
+   * How far the engine's clock is ahead of this machine's, in milliseconds.
+   * Idempotency keys are minted here and the engine refuses one dated more
+   * than an hour from its own clock, so without this a device with a wrong
+   * clock would fail every call forever.
+   */
+  #clockOffset = 0;
+  /** The engine's clock, as well as this client knows it. */
+  now() {
+    return Date.now() + this.#clockOffset;
+  }
+  /** Off by up to one round trip, which a window in hours does not notice. */
+  observeServerTime(at) {
+    this.#clockOffset = at.getTime() - Date.now();
+  }
   constructor(options) {
     if (!options.apiKey) {
       throw new MeterbaseError(
@@ -637,6 +668,12 @@ var Meterbase = class {
    *
    * This is the gate, and the only call that ever refuses. Run it before the
    * work; record the work with `track` afterwards.
+   *
+   * Two gates answer it, and `allowed` needs both: the customer's capacity has
+   * 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.
    */
   check(params, options) {
     return this.#client.request({
@@ -652,24 +689,70 @@ var Meterbase = class {
    * customer's capacity is recorded, drives `available` to 0, and the next
    * `check` says no. The answer is a receipt, not a verdict.
    *
-   * `idempotency_key` is generated when omitted, so retrying this call — the
-   * SDK's own retries included — replays the original rather than counting
-   * the same work twice.
+   * `idempotency_key` is a UUIDv7, generated when omitted, so retrying this
+   * call — the SDK's own retries included — replays the original rather than
+   * counting the same work twice. The engine keeps that claim for an hour,
+   * which is how long a retry stays recognisable.
    */
   // `async` so that generating the key cannot throw synchronously out of a
   // method that otherwise only ever rejects: one call, one way to fail.
   async track(params, options) {
+    return this.#keyed(
+      IDEMPOTENCY_WINDOW_MS,
+      params.idempotency_key,
+      (key) => this.#client.request({
+        ...options,
+        method: "POST",
+        path: "/v1/usage/track",
+        // Fixed before the retry loop is entered: every attempt of this call
+        // carries the same key, which is what makes replaying it safe.
+        body: { ...params, idempotency_key: key },
+        idempotent: true
+      })
+    );
+  }
+  /**
+   * Holds capacity for work that cannot be done twice, or refuses. The same
+   * decision `check` makes, and then a hold on the capacity until the work
+   * is committed, released, or expires.
+   *
+   * The rule for choosing: can you afford to do the work twice? `check`. No?
+   * `reserve`. A reserve costs a transaction where a check costs a cached
+   * read, refusals included, so it is not a per-request gate on cheap work.
+   *
+   * Two concurrent reserves for the same customer and meter cannot both be
+   * granted the same capacity; that is the whole point, and it is what
+   * `check` → work → `track` could never promise.
+   */
+  async reserve(params, options) {
+    const response = await this.#keyed(
+      RESERVE_WINDOW_MS,
+      params.reservation_id,
+      (id) => this.#client.request({
+        ...options,
+        method: "POST",
+        path: "/v1/usage/reserve",
+        body: { ...params, reservation_id: id },
+        // A retry under the same id finds the hold it already made rather
+        // than making a second one.
+        idempotent: true
+      })
+    );
+    return this.#hold(params, response);
+  }
+  /**
+   * Gives a hold back: the work did not happen, so nothing is recorded.
+   *
+   * Throws `NotFoundError` when the id names nothing — committed, released
+   * already, or never made, which are one absence with one meaning. Prefer
+   * `hold.release()`, which treats that as the success it is.
+   */
+  release(params, options) {
     return this.#client.request({
       ...options,
       method: "POST",
-      path: "/v1/usage/track",
-      // Fixed here, once, before the retry loop is entered: every attempt of
-      // this call carries the same key, which is what makes replaying it safe.
-      body: {
-        ...params,
-        idempotency_key: params.idempotency_key ?? idempotencyKey()
-      },
-      idempotent: true
+      path: "/v1/usage/release",
+      body: params
     });
   }
   /** Reports which workspace this key acts for. */
@@ -680,19 +763,110 @@ var Meterbase = class {
       path: "/v1/whoami"
     });
   }
+  /**
+   * Sends a call that carries a caller-minted UUIDv7, minting one when the
+   * caller supplied none and re-minting once if this machine's clock put it
+   * outside the engine's window.
+   *
+   * A key the caller supplied is never re-minted: this cannot know whether it
+   * names work already recorded, and replacing it could count that work
+   * twice.
+   */
+  async #keyed(window, supplied, send) {
+    if (supplied !== void 0) return send(supplied);
+    const key = idempotencyKey(this.#client.now());
+    const startedAt = Date.now();
+    try {
+      return await send(key);
+    } catch (error) {
+      if (!(error instanceof TooLateError) || error.serverTime === void 0) {
+        throw error;
+      }
+      const elapsed = Date.now() - startedAt;
+      const serverAtStart = error.serverTime.getTime() - elapsed;
+      if (Math.abs(serverAtStart - mintedAtMs(key)) <= window) throw error;
+      this.#client.observeServerTime(error.serverTime);
+      return await send(idempotencyKey(this.#client.now()));
+    }
+  }
+  /** Puts `commit` and `release` on a granted hold; a refusal is left as it is. */
+  #hold(params, response) {
+    if (!response.allowed) return response;
+    const id = response.reservation_id;
+    const expiresAt = response.expires_at;
+    if (id === void 0 || expiresAt === void 0) {
+      throw new MeterbaseError(
+        "The engine granted a reservation without an id or an expiry, so there is no hold to commit or release. The capacity it set aside comes back on its own."
+      );
+    }
+    const expiresAtMs = Date.parse(expiresAt);
+    return {
+      ...response,
+      allowed: true,
+      reservation_id: id,
+      quantity: response.quantity ?? params.quantity ?? 1,
+      expires_at: expiresAt,
+      commit: (quantity, commitOptions) => {
+        if (Number.isFinite(expiresAtMs) && this.#client.now() > expiresAtMs && typeof globalThis.console?.warn === "function") {
+          globalThis.console.warn(
+            `Meterbase: committing reservation ${id} after it expired at ${expiresAt}. The event is still recorded, but the capacity was no longer held \u2014 raise expires_in_seconds for this work.`
+          );
+        }
+        return this.track(
+          {
+            customer_id: params.customer_id,
+            meter_id: params.meter_id,
+            quantity,
+            // The hold's own id, so the track commits it rather than
+            // recording a second event beside it.
+            idempotency_key: id
+          },
+          commitOptions
+        );
+      },
+      release: async (releaseOptions) => {
+        try {
+          return await this.release({ reservation_id: id }, releaseOptions);
+        } catch (error) {
+          if (error instanceof NotFoundError) return null;
+          throw error;
+        }
+      }
+    };
+  }
 };
-function idempotencyKey() {
+var IDEMPOTENCY_WINDOW_MS = 60 * 60 * 1e3;
+var RESERVE_WINDOW_MS = 30 * 60 * 1e3;
+function mintedAtMs(key) {
+  return Number.parseInt(key.replace(/-/g, "").slice(0, 12), 16);
+}
+function idempotencyKey(atMs) {
   const webcrypto = globalThis.crypto;
-  if (typeof webcrypto?.randomUUID === "function") {
-    return webcrypto.randomUUID();
-  }
-  if (typeof webcrypto?.getRandomValues === "function") {
-    const bytes = webcrypto.getRandomValues(new Uint8Array(16));
-    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  if (typeof webcrypto?.getRandomValues !== "function") {
+    throw new MeterbaseError(
+      "No crypto to generate an idempotency key with: pass `idempotency_key` yourself (a UUIDv7), or run somewhere `crypto.getRandomValues` exists."
+    );
   }
-  throw new MeterbaseError(
-    "No crypto to generate an idempotency key with: pass `idempotency_key` yourself, or run somewhere `crypto.getRandomValues` exists."
-  );
+  const bytes = webcrypto.getRandomValues(new Uint8Array(16));
+  const ms = Math.max(0, Math.trunc(atMs));
+  const high = Math.floor(ms / 4294967296);
+  const low = ms >>> 0;
+  bytes[0] = high >>> 8 & 255;
+  bytes[1] = high & 255;
+  bytes[2] = low >>> 24 & 255;
+  bytes[3] = low >>> 16 & 255;
+  bytes[4] = low >>> 8 & 255;
+  bytes[5] = low & 255;
+  bytes[6] = bytes[6] & 15 | 112;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20)
+  ].join("-");
 }
 
 exports.APIError = APIError;
@@ -700,15 +874,17 @@ exports.AuthenticationError = AuthenticationError;
 exports.ConflictError = ConflictError;
 exports.ConnectionError = ConnectionError;
 exports.CycleChangeRequiresResetError = CycleChangeRequiresResetError;
-exports.IdempotencyConflictError = IdempotencyConflictError;
+exports.InvalidIdempotencyKeyError = InvalidIdempotencyKeyError;
 exports.InvalidRequestError = InvalidRequestError;
 exports.Meterbase = Meterbase;
 exports.MeterbaseError = MeterbaseError;
 exports.NotFoundError = NotFoundError;
 exports.PermissionDeniedError = PermissionDeniedError;
 exports.RateLimitError = RateLimitError;
+exports.ReservationMismatchError = ReservationMismatchError;
 exports.ServerError = ServerError;
 exports.TimeoutError = TimeoutError;
+exports.TooLateError = TooLateError;
 exports.errorFromResponse = errorFromResponse;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map