mbase-sdk 0.0.4 → 0.0.6

package/README.md

@@ -1,21 +1,22 @@
-# @meterbase/sdk
+# mbase-sdk
 
 TypeScript SDK for the [Meterbase](https://github.com/usemeterbase/engine)
-engine. Works on Node 18+, browsers, and edge runtimes — it uses `fetch` and
+engine. Works on Node 20+, browsers, and edge runtimes — it uses `fetch` and
 nothing else.
 
 ## Install
 
 ```bash
-npm install @meterbase/sdk
+npm install mbase-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"
+import { Meterbase } from "mbase-sdk"
 
 const meterbase = new Meterbase({ apiKey: process.env.METERBASE_API_KEY! })
 
@@ -96,12 +97,12 @@ 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         |
+| 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
@@ -128,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
@@ -311,7 +374,7 @@ weight, so `changeAtNextCycle` and `changeNow` + `"prorate"` both answer
 `changeNow` is the other way out — it keeps the period that is running.
 
 ```ts
-import { CycleChangeRequiresResetError } from "@meterbase/sdk"
+import { CycleChangeRequiresResetError } from "mbase-sdk"
 
 try {
   await meterbase.customers.plan.changeAtNextCycle(customer.id, {
@@ -354,6 +417,42 @@ instruction, and writes no new row of its own — so this reads the plan in forc
 and names it back. It returns the assignment still in force, or `null` for a
 customer holding no plan, who can have nothing pending.
 
+#### How much they have used
+
+```ts
+const entitlement = await meterbase.customers.entitlement(customer.id) // or null
+
+for (const meter of entitlement?.meters ?? []) {
+  console.log(meter.meter_id, `${meter.used} of ${meter.amount ?? "unlimited"}`)
+}
+```
+
+`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.
+
+Unlike `check`, it is not answered from a cache, so read it where usage is
+shown rather than on every request.
+
+#### Usage by day
+
+```ts
+const week = await meterbase.customers.usage(customer.id, { days: 7 })
+const period = await meterbase.customers.usage(customer.id, {
+  period: "current",
+}) // or null
+const meter = await meterbase.meters.usage(meterId, { days: 30 })
+```
+
+Usage per UTC day: `days` is 1–90 days ending today, and a customer can also
+be read by `period`, `current` or `last`. Each meter lists every day that has
+begun, zeros included; a customer's meters with no usage in the range are left
+out. A period the customer never had is `null`.
+
+Figures can be up to five minutes old. `check` and `entitlement` are live.
+
 ### A customer's allowances
 
 Capacity on top of whatever the plan gives.
@@ -382,7 +481,7 @@ Every failure is a `MeterbaseError`. Catch the specific one you care about, or
 the base class for all of them.
 
 ```ts
-import { ConflictError, RateLimitError } from "@meterbase/sdk"
+import { ConflictError, RateLimitError } from "mbase-sdk"
 
 try {
   await meterbase.customers.create({ external_id: "acct_1" })
@@ -397,19 +496,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                                                      |
-| `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                                 |
+| 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                                                          |
+| `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.

package/dist/index.cjs

@@ -41,6 +41,8 @@ var TooLateError = class extends InvalidRequestError {
     this.serverTime = serverTime(args.body);
   }
 };
+var ReservationMismatchError = class extends InvalidRequestError {
+};
 var CycleChangeRequiresResetError = class extends InvalidRequestError {
 };
 var RateLimitError = class extends APIError {
@@ -73,6 +75,8 @@ function errorFromResponse(args) {
           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:
@@ -133,7 +137,7 @@ var Client = class {
     this.#fetch = options.fetch ?? globalThis.fetch;
     if (typeof this.#fetch !== "function") {
       throw new MeterbaseError(
-        "No fetch implementation: pass one as `fetch`, or run on Node 18+."
+        "No fetch implementation: pass one as `fetch`, or run on Node 20+."
       );
     }
   }
@@ -504,6 +508,36 @@ var Customers = class {
     });
     return data[0] ?? null;
   }
+  /** `null` for a customer holding no plan, as `plan.retrieve` answers. */
+  async entitlement(id, options) {
+    try {
+      return await this.#client.request({
+        ...options,
+        method: "GET",
+        path: `/v1/customers/${encodeURIComponent(id)}/entitlement`
+      });
+    } catch (error) {
+      if (error instanceof NotFoundError && error.code === "no_plan_assigned") {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async usage(id, params, options) {
+    try {
+      return await this.#client.request({
+        ...options,
+        method: "GET",
+        path: `/v1/customers/${encodeURIComponent(id)}/usage`,
+        query: { days: params.days, period: params.period }
+      });
+    } catch (error) {
+      if (error instanceof NotFoundError && (error.code === "no_plan_assigned" || error.code === "no_previous_period")) {
+        return null;
+      }
+      throw error;
+    }
+  }
   update(id, params, options) {
     return this.#client.request({
       ...options,
@@ -559,6 +593,15 @@ var Meters = class {
       body: params
     });
   }
+  /** Every customer's usage of the meter per UTC day. */
+  usage(id, params, options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      path: `/v1/meters/${encodeURIComponent(id)}/usage`,
+      query: { days: params.days }
+    });
+  }
   /** Soft delete: plans and usage keep referencing the meter. Idempotent. */
   archive(id, options) {
     return this.#client.request({
@@ -693,18 +736,83 @@ var Meterbase = class {
   // `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) {
-    const send = (key2) => this.#client.request({
+    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 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: key2 },
-      idempotent: true
+      path: "/v1/usage/release",
+      body: params
     });
-    if (params.idempotency_key !== void 0) {
-      return send(params.idempotency_key);
-    }
+  }
+  /** Reports which workspace this key acts for. */
+  whoami(options) {
+    return this.#client.request({
+      ...options,
+      method: "GET",
+      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 {
@@ -715,23 +823,59 @@ var Meterbase = class {
       }
       const elapsed = Date.now() - startedAt;
       const serverAtStart = error.serverTime.getTime() - elapsed;
-      if (Math.abs(serverAtStart - mintedAtMs(key)) <= IDEMPOTENCY_WINDOW_MS) {
-        throw error;
-      }
+      if (Math.abs(serverAtStart - mintedAtMs(key)) <= window) throw error;
       this.#client.observeServerTime(error.serverTime);
       return await send(idempotencyKey(this.#client.now()));
     }
   }
-  /** Reports which workspace this key acts for. */
-  whoami(options) {
-    return this.#client.request({
-      ...options,
-      method: "GET",
-      path: "/v1/whoami"
-    });
+  /** 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;
+        }
+      }
+    };
   }
 };
 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);
 }
@@ -776,6 +920,7 @@ exports.MeterbaseError = MeterbaseError;
 exports.NotFoundError = NotFoundError;
 exports.PermissionDeniedError = PermissionDeniedError;
 exports.RateLimitError = RateLimitError;
+exports.ReservationMismatchError = ReservationMismatchError;
 exports.ServerError = ServerError;
 exports.TimeoutError = TimeoutError;
 exports.TooLateError = TooLateError;