mbase-sdk 0.0.6 → 0.0.8

package/README.md

@@ -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
 
@@ -475,6 +475,112 @@ 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
@@ -509,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.
@@ -531,6 +638,11 @@ Per-call overrides, including cancellation:
 await meterbase.meters.list({}, { signal: controller.signal, timeout: 2_000 })
 ```
 
+Aborting the signal ends the call where it stands — mid-attempt or in the wait
+before a retry — and rejects with the reason you aborted with. Nothing is sent
+after it: an attempt already on the wire may still land, but it is never
+replayed, so a cancelled `track` cannot record usage twice.
+
 **Retries** apply to `GET`, `DELETE` and `track`, on connection failures, 408,
 429 and 5xx, with exponential backoff and full jitter. `Retry-After` is honoured
 when the engine sends it. Every other `POST` and `PATCH` is never replayed,

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";
@@ -146,7 +148,7 @@ var Client = class {
     const retryable = req.method === "GET" || req.method === "DELETE" || req.idempotent === true;
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      if (attempt > 0) await sleep(backoff(attempt, lastError));
+      if (attempt > 0) await sleep(backoff(attempt, lastError), req.signal);
       try {
         const response = await this.#send(req);
         if (response.ok) return await parseBody(response);
@@ -160,6 +162,7 @@ var Client = class {
         if (cause instanceof MeterbaseError && !(cause instanceof ConnectionError)) {
           throw cause;
         }
+        if (req.signal?.aborted) throw cause;
         if (!retryable || attempt >= maxRetries) throw cause;
         lastError = cause;
       }
@@ -167,6 +170,7 @@ var Client = class {
     throw lastError;
   }
   async #send(req) {
+    if (req.signal?.aborted) throw req.signal.reason;
     const url = new URL(this.#baseUrl + req.path);
     for (const [key, value] of Object.entries(req.query ?? {})) {
       if (value !== void 0) url.searchParams.set(key, String(value));
@@ -215,8 +219,22 @@ function backoff(attempt, lastError) {
   const ceiling = Math.min(500 * 2 ** (attempt - 1), MAX_BACKOFF);
   return Math.random() * ceiling;
 }
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
 }
 async function parseBody(response) {
   if (response.status === 204) return void 0;
@@ -688,6 +706,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;
@@ -924,6 +1020,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