mbase-sdk 0.0.5 → 0.0.7

package/README.md

@@ -1,13 +1,13 @@
-# @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
@@ -16,7 +16,7 @@ Two calls, in this order: **`check` → do the work → `track`** — or, for wo
 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! })
 
@@ -253,7 +253,7 @@ It is the one field where `null` is a value rather than silence:
 | `thresholds: []`   | alerts off for this scope alone                   |
 | `thresholds: [80]` | these marks                                       |
 
-Crossings are recorded by the engine; no webhook delivers them yet.
+Each crossing is delivered as a webhook; see [Webhooks](#webhooks).
 
 ### Meters
 
@@ -374,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, {
@@ -417,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.
@@ -439,13 +475,119 @@ Revoking withdraws what is left without erasing what was consumed, and is
 idempotent. Grants the engine minted itself from a plan's `one_time` allowance
 appear here with `source: "plan"`; they cannot be created through `grant`.
 
+## Webhooks
+
+Meterbase posts to your endpoints when a customer crosses a usage threshold.
+Add an endpoint in the dashboard under **Webhooks**; each has its own signing
+secret, shown once when you add it and revealable from its settings.
+
+| Event                 | When                                                                                   |
+| --------------------- | -------------------------------------------------------------------------------------- |
+| `threshold.crossed`   | a customer's usage of a meter crosses one of their thresholds                          |
+| `entitlement.reached` | that crossing at 100% of their plan's entitlement, sent as well as `threshold.crossed` |
+
+```json
+{
+  "id": "0199c3b1-3f05-7a90-b6e2-49c817d05fa3",
+  "type": "threshold.crossed",
+  "timestamp": "2026-09-18T14:08:12Z",
+  "data": {
+    "customer_id": "acct_1",
+    "meter_id": "ai_tokens",
+    "plan": { "id": "01993c40-…", "key": "pro", "name": "Pro" },
+    "threshold": 80,
+    "used": 801400,
+    "entitlement": 1000000,
+    "period": {
+      "start": "2026-09-01T00:00:00Z",
+      "end": "2026-10-01T00:00:00Z"
+    },
+    "usage_event_id": "0199c3b0-9e41-7d2a-8c55-2f6e1a3bc738"
+  }
+}
+```
+
+`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.
+
+### Verifying a delivery
+
+Verify every request before you trust it. `verifyWebhook` checks the signature
+and the timestamp, then returns the event:
+
+```ts
+import { verifyWebhook, WebhookVerificationError } from "mbase-sdk"
+
+app.post(
+  "/meterbase",
+  express.raw({ type: "application/json" }),
+  async (req, res) => {
+    let event
+    try {
+      event = await verifyWebhook({
+        payload: req.body, // the raw body: re-serialized JSON will not verify
+        headers: req.headers,
+        secret: process.env.METERBASE_WEBHOOK_SECRET!,
+      })
+    } catch (error) {
+      if (error instanceof WebhookVerificationError) return res.sendStatus(400)
+      throw error
+    }
+
+    if (event.type === "entitlement.reached") {
+      // event.data.customer_id has used their plan's allowance for event.data.meter_id
+    }
+    res.sendStatus(204)
+  },
+)
+```
+
+Without the SDK, it is [Standard Webhooks](https://www.standardwebhooks.com):
+
+1. Each request carries `webhook-id`, `webhook-timestamp` (Unix seconds) and
+   `webhook-signature`.
+2. Compute HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed
+   with the base64-decoded part of the secret after `whsec_`.
+3. `webhook-signature` is a space-separated list of `v1,{base64}`. Accept the
+   request if any of them equals yours, compared in constant time.
+4. Refuse a timestamp more than five minutes from your clock.
+
+### Responding and retries
+
+Answer with a 2xx within 10 seconds. Anything else is a failure, a redirect
+included: Meterbase does not follow them.
+
+| Attempt | After the one before            |
+| ------- | ------------------------------- |
+| 1       | within a minute of the crossing |
+| 2       | 1 minute                        |
+| 3       | 6 minutes                       |
+| 4       | 36 minutes                      |
+| 5       | 3 hours 36 minutes              |
+| 6       | 21 hours 36 minutes             |
+
+Each wait varies by up to 10%. An event keeps its `id` on every attempt and
+every endpoint, so dedupe on it, and do not rely on order. The dashboard logs
+every attempt for 30 days and can retry a delivery by hand.
+
+An answer of `410 Gone` pauses the endpoint, as does a failure a day into a
+streak of them. A paused endpoint holds new deliveries until you resume it,
+with or without replaying them.
+
+### Rotating a secret
+
+Rotate from the endpoint's settings. For the next 24 hours both secrets sign
+every request, so deploy the new one at your own pace; while you switch over,
+`secret` takes both.
+
 ## Errors
 
 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" })
@@ -473,6 +615,7 @@ try {
 | `RateLimitError`                   | 429                                                                                                                                     |
 | `ServerError`                      | 5xx                                                                                                                                     |
 | `ConnectionError` / `TimeoutError` | the request never got an answer                                                                                                         |
+| `WebhookVerificationError`         | `verifyWebhook`: not a delivery Meterbase signed in the last five minutes                                                               |
 
 `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

@@ -97,6 +97,8 @@ function serverTime(body) {
   const parsed = new Date(at);
   return Number.isNaN(parsed.getTime()) ? void 0 : parsed;
 }
+var WebhookVerificationError = class extends MeterbaseError {
+};
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.meterbase.tech";
@@ -137,7 +139,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+."
       );
     }
   }
@@ -508,6 +510,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,
@@ -563,6 +595,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({
@@ -649,6 +690,84 @@ var Plans = class {
   }
 };
 
+// src/webhooks.ts
+var SECRET_PREFIX = "whsec_";
+var DEFAULT_TOLERANCE_SECONDS = 5 * 60;
+async function verifyWebhook(params) {
+  const id = header(params.headers, "webhook-id");
+  const timestamp = header(params.headers, "webhook-timestamp");
+  const signatures = header(params.headers, "webhook-signature");
+  if (!id || !timestamp || !signatures) {
+    throw new WebhookVerificationError(
+      "Missing a webhook-id, webhook-timestamp or webhook-signature header."
+    );
+  }
+  const sentAt = Number(timestamp);
+  const tolerance = params.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (!Number.isInteger(sentAt) || Math.abs(Date.now() / 1e3 - sentAt) > tolerance) {
+    throw new WebhookVerificationError(
+      "The webhook-timestamp is too far from now; this may be a replay."
+    );
+  }
+  const body = typeof params.payload === "string" ? new TextEncoder().encode(params.payload) : params.payload;
+  const signed = concat(new TextEncoder().encode(`${id}.${timestamp}.`), body);
+  const candidates = signatures.split(" ").filter((entry) => entry.startsWith("v1,")).map((entry) => fromBase64(entry.slice(3)));
+  const subtle = webCrypto();
+  const secrets = typeof params.secret === "string" ? [params.secret] : params.secret;
+  for (const secret of secrets) {
+    const raw = secret.startsWith(SECRET_PREFIX) ? fromBase64(secret.slice(SECRET_PREFIX.length)) : void 0;
+    if (!raw) {
+      throw new WebhookVerificationError(
+        "The secret should be whsec_ and base64: copy it from the endpoint's settings."
+      );
+    }
+    const key = await subtle.importKey(
+      "raw",
+      raw,
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["verify"]
+    );
+    for (const candidate of candidates) {
+      if (candidate && await subtle.verify("HMAC", key, candidate, signed)) {
+        return JSON.parse(new TextDecoder().decode(body));
+      }
+    }
+  }
+  throw new WebhookVerificationError(
+    "No signature matches: the body changed, or this is the wrong secret."
+  );
+}
+function header(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name) ?? void 0;
+  }
+  const value = headers[name];
+  return Array.isArray(value) ? value[0] : value;
+}
+function webCrypto() {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new MeterbaseError(
+      "No Web Crypto to verify a webhook with: run on Node 20+, Deno, Bun or a Worker."
+    );
+  }
+  return subtle;
+}
+function fromBase64(text) {
+  try {
+    return Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+  } catch {
+    return void 0;
+  }
+}
+function concat(head, tail) {
+  const out = new Uint8Array(head.length + tail.length);
+  out.set(head);
+  out.set(tail, head.length);
+  return out;
+}
+
 // src/index.ts
 var Meterbase = class {
   customers;
@@ -885,6 +1004,8 @@ exports.ReservationMismatchError = ReservationMismatchError;
 exports.ServerError = ServerError;
 exports.TimeoutError = TimeoutError;
 exports.TooLateError = TooLateError;
+exports.WebhookVerificationError = WebhookVerificationError;
 exports.errorFromResponse = errorFromResponse;
+exports.verifyWebhook = verifyWebhook;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map