mbase-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meterbase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,361 @@
+# @meterbase/sdk
+
+TypeScript SDK for the [Meterbase](https://github.com/usemeterbase/engine)
+engine. Works on Node 18+, browsers, and edge runtimes — it uses `fetch` and
+nothing else.
+
+## Install
+
+```bash
+npm install @meterbase/sdk
+```
+
+## Usage
+
+Two calls, in this order: **`check` → do the work → `track`.**
+
+```ts
+import { Meterbase } from "@meterbase/sdk"
+
+const meterbase = new Meterbase({ apiKey: process.env.METERBASE_API_KEY! })
+
+const { allowed } = 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")
+
+const completion = await generate(prompt)
+
+await meterbase.track({
+  customer_id: "acct_1",
+  meter_id: "ai_tokens",
+  quantity: completion.usage.total_tokens,
+})
+```
+
+An API key names its own workspace, so there is no workspace to pass.
+
+`check` is the gate, and the only call that ever refuses. It never throws for a
+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.
+
+### 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:
+
+```ts
+const { event } = await meterbase.track({
+  customer_id: "acct_1",
+  meter_id: "ai_tokens",
+  quantity: 250_000,
+  occurred_at: "2026-03-22T10:15:02Z", // defaults to now
+  idempotency_key: "req_9f3a", // generated when you omit it
+})
+
+event.replayed // false the first time, true for a retry of the same call
+```
+
+`occurred_at` chooses the period the event counts against and must fall inside
+the workspace's window — by default 7 days back and 5 minutes ahead — which is
+what lets usage be reported late. `recorded_at` is when Meterbase stored 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           |
+
+`occurred_at` is deliberately not compared, so omitting it and getting a fresh
+server timestamp on the retry still replays rather than conflicts.
+
+**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.
+Supply your own when the caller already has an id for the work — a job id, a
+request id — so that a retry from further out than this SDK replays too. Keys
+are retained 35 days, longer than any `occurred_at` window, so a retry of a
+retired key is refused by the window rather than recorded twice.
+
+### Customers
+
+```ts
+const customer = await meterbase.customers.create({
+  external_id: "acct_1",
+  name: "Acme",
+  metadata: { tier: "pro" },
+})
+
+const found = await meterbase.customers.retrieveByExternalId("acct_1") // or null
+const { data } = await meterbase.customers.list({ include_deleted: true })
+
+await meterbase.customers.update(customer.id, { name: "Acme Inc" })
+await meterbase.customers.delete(customer.id) // soft delete, idempotent
+```
+
+### Alert thresholds
+
+`thresholds` is a list of whole percents — 1–1000, at most 32, and a mark over
+100 is an overage alert — and it hangs off both meters and customers. A
+customer's list beats the meter's, which beats the workspace's defaults.
+
+```ts
+await meterbase.meters.create({
+  key: "ai_tokens",
+  name: "Tokens",
+  thresholds: [80, 100],
+})
+await meterbase.customers.update(customer.id, { thresholds: [50, 90] }) // this customer only
+```
+
+It is the one field where `null` is a value rather than silence:
+
+| You send           | It means                                          |
+| ------------------ | ------------------------------------------------- |
+| nothing            | keep the stored list                              |
+| `thresholds: null` | inherit again — the meter's, then the workspace's |
+| `thresholds: []`   | alerts off for this scope alone                   |
+| `thresholds: [80]` | these marks                                       |
+
+Crossings are recorded by the engine; no webhook delivers them yet.
+
+### Meters
+
+```ts
+await meterbase.meters.create({ key: "api_calls", name: "API calls" }) // plus optional thresholds
+const { data } = await meterbase.meters.list()
+await meterbase.meters.archive(meterId) // soft delete, idempotent
+```
+
+### Plans
+
+A plan has one billing period, fixed when the plan is created. Everything it
+meters resets on that period, measured from each customer's own anchor — which
+is why two customers on the same monthly plan renew on different days.
+
+```ts
+const plan = await meterbase.plans.create({
+  key: "pro",
+  name: "Pro",
+  cycle: "monthly", // daily · weekly · monthly · quarterly · half_yearly · yearly
+})
+
+await meterbase.plans.update(plan.id, { name: "Pro Plus" })
+await meterbase.plans.archive(plan.id) // stops new assignments, keeps existing ones
+```
+
+`cycle` is not patchable. Changing it would re-date every period the plan's
+customers were already measured against, so a different cadence is a different
+plan — move a customer with `customers.plan.assign`.
+
+### Plan allowances
+
+What a plan grants, one meter at a time. An allowance says _how much_, never
+_how often_: the period is the plan's cycle. There is no update and no delete —
+an edit appends the next version, so which amount applied when stays derivable.
+
+```ts
+// The recurring cap, refreshed every period.
+await meterbase.plans.allowances.set(plan.id, {
+  meter_id: meter.id,
+  amount: 1_000_000, // or no_cap: true
+})
+
+// A signup bonus beside it, minted once when the plan is assigned.
+await meterbase.plans.allowances.set(plan.id, {
+  meter_id: meter.id,
+  amount: 500,
+  kind: "one_time",
+  valid_for: { months: 3, days: 0 },
+})
+
+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 customer's plan
+
+Append-only: assigning is the only write, and it serves both a first plan and
+a later change.
+
+```ts
+await meterbase.customers.plan.assign(customer.id, {
+  plan_id: plan.id,
+  effective: "next_cycle", // or "immediate"
+})
+
+const current = await meterbase.customers.plan.retrieve(customer.id)
+const { data } = await meterbase.customers.plan.history(customer.id)
+```
+
+A first assignment is always recorded as `immediate` — there is no period to
+wait out — so read `effective` on the response rather than assuming it took
+what you asked for. `next_cycle` lands on the first boundary the two plans'
+cycles share; a weekly plan meeting a month-based one shares none and answers
+`422 cycle_change_requires_reset`.
+
+### A customer's allowances
+
+Capacity on top of whatever the plan gives.
+
+```ts
+const grant = await meterbase.customers.allowances.grant(customer.id, {
+  meter_id: meter.id,
+  amount: 500,
+  source: "purchased", // or "bonus" · "manual"
+})
+
+const { data } = await meterbase.customers.allowances.list(customer.id, {
+  include_closed: true,
+})
+
+await meterbase.customers.allowances.revoke(customer.id, grant.id)
+```
+
+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`.
+
+## 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"
+
+try {
+  await meterbase.customers.create({ external_id: "acct_1" })
+} catch (error) {
+  if (error instanceof ConflictError) {
+    // error.code === "customer_external_id_taken"
+  }
+  if (error instanceof RateLimitError) {
+    // error.retryAfter, in seconds
+  }
+  throw error
+}
+```
+
+| 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                                                          |
+| `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.
+
+## Options
+
+```ts
+new Meterbase({
+  apiKey: "mb_sk_live_…",
+  baseUrl: "https://api.meterbase.dev",
+  timeout: 10_000, // per attempt
+  maxRetries: 2,
+  fetch: customFetch,
+})
+```
+
+Per-call overrides, including cancellation:
+
+```ts
+await meterbase.meters.list({}, { signal: controller.signal, timeout: 2_000 })
+```
+
+**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,
+because a retried create could produce a second row.
+
+`track` is the exception because it carries an idempotency key, and because the
+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.
+
+## Types
+
+Types mirror the wire exactly, `snake_case` included, so this SDK reads the
+same as the API reference and cannot drift from it through a translation layer.
+
+## Versioning
+
+**0.2.0 is a breaking change.** `CheckResult` lost `remaining` and `breakdown`
+and gained `available: number | null`, following the engine's `check`, which
+now answers from one cached integer and returns a single figure. Read
+`available`, and take `null` under `no_cap` as "capacity is not a number here"
+rather than as a 0. The per-grant detail moved to
+`customers.allowances.list()`.
+
+Additive in the same release: `thresholds` on `Meter` and `Customer`, and on
+their create and update params.
+
+Pre-1.0, the minor version is where breaking changes land — deliberately, so a
+change that will not compile against your code cannot arrive as a patch.
+
+## Development
+
+```bash
+npm install
+npm test          # vitest, against a local test double
+npm run check     # typecheck, lint, format, test, build, publint, attw
+```
+
+### Two layers of tests
+
+**`npm test`** runs against a real `node:http` server on an ephemeral port
+rather than a stubbed `fetch`, so request building, headers, status handling
+and the retry loop are exercised for real. It can make the server drop a
+socket or stall, which is the only way to test the retry and timeout paths.
+
+What it cannot check is whether those scripted responses match the engine: a
+route that does not exist, a renamed field or a changed error code all pass
+here and fail in production.
+
+**`npm run test:contract`** closes that gap by running against a live engine.
+
+```bash
+cp .env.example .env   # then fill in a key, or export the two variables
+METERBASE_BASE_URL=http://localhost:8080 \
+METERBASE_API_KEY=mb_sk_live_… \
+npm run test:contract
+```
+
+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 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.
+
+> **It creates and deletes real data.** Point it at a test workspace. It only
+> touches resources it created, tagging each with a per-run id, and cleans up
+> afterwards; soft-deleted customers and archived meters and plans remain, as
+> the engine intends. It is excluded from `npm test` on purpose — a mutating suite should
+> only run because someone asked for it.