mbase-sdk 0.0.2

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,497 @@
+# @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,
+  idempotency_key: "req_9f3a", // generated when you omit it
+})
+
+event.replayed // false the first time, true for a retry of the same call
+```
+
+**The engine dates the event, not you.** There is no `occurred_at` to send: an
+event is stamped by the database clock the write runs under, which is what
+chooses the period it counts against. `occurred_at` and `recorded_at` come back
+on the receipt as the same instant, both on the wire so a reader of either
+keeps working. Nothing can be dated into a period that has already closed, so a
+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.
+
+**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; a retry after that records a second event, which is not a
+case this API sets out to serve.
+
+### 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
+```
+
+**Reading one customer tells you their plan.** `retrieve` and
+`retrieveByExternalId` carry `plan` — the one in force now — and
+`pending_plan`, the change waiting to land, each `null` when there is none:
+
+```ts
+const acme = await meterbase.customers.retrieve(customer.id)
+
+acme.plan?.key //        "pro"
+acme.plan?.cycle //      "monthly" — what their period is measured in
+acme.plan?.anchor_at //  what it is measured from
+acme.pending_plan //     null, or the plan they move to and when
+```
+
+`plan.id` is the **plan's** id, not the assignment's: what you want from an
+embed is which plan, and `customers.plan.retrieve` is where instructions are
+identified. `null` means they hold no plan, which is a default deny — a
+customer with no plan and no grant is denied.
+
+`customers.list` stays lean and does not embed, along with `create`, `update`
+and `delete`; the same read would run per row for an answer most callers of a
+list do not want.
+
+### 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
+
+A customer's plan is an append-only history, not a field: assigning is the only
+write, and it serves both a first plan and every later change. What differs
+between the changes is **when** the new plan starts and **what happens to the
+period the change lands in** — so each of those is its own call.
+
+#### Putting them on a plan
+
+```ts
+await meterbase.customers.plan.assign(customer.id, { plan_id: plan.id })
+```
+
+A first assignment is always recorded as `immediate`: there is no period to
+wait out. It is the one call that takes `cycle_anchor`, which puts their
+billing periods on a date they already have — migrating them from another
+system, say. Their renewal day is fixed from here and does not move again
+unless you `restart` them.
+
+#### Moving them to another plan
+
+| Call                      | The new plan starts | This period's cap                                |
+| ------------------------- | ------------------- | ------------------------------------------------ |
+| `changeAtNextCycle`       | at their renewal    | untouched — they keep what they paid for         |
+| `changeNow`               | now                 | the new plan's amount, for the whole period      |
+| `changeNow` + `"prorate"` | now                 | the two plans weighted by how long each was held |
+| `restart`                 | now                 | a **fresh period** starts today                  |
+
+```ts
+// Upgrade them at their renewal. Nothing is split, so nothing is pro-rated.
+await meterbase.customers.plan.changeAtNextCycle(customer.id, { plan: pro.id })
+
+// Move them now. Usage already spent still counts, so a downgrade can deny
+// until the period ends.
+await meterbase.customers.plan.changeNow(customer.id, { plan: starter.id })
+
+// Move them now and split the period fairly: 1,000/mo held for half a month
+// then 400/mo for the other half is a cap of 700.
+await meterbase.customers.plan.changeNow(customer.id, {
+  plan: starter.id,
+  reconciliation: "prorate",
+})
+
+// Start over today: the running period closes where the change lands and
+// keeps its usage, and the new plan's full amount opens at once.
+await meterbase.customers.plan.restart(customer.id, { plan: pro.id })
+```
+
+**`restart` is the one that moves their renewal day**, because it re-anchors
+them to today. The other three leave it exactly where it was.
+
+`change(customerId, { plan, effective, reconciliation })` is the same call with
+both knobs in the open, for when they are chosen at runtime. `assign` is the
+wire shape underneath all four, and still takes `plan_id`.
+
+#### Two plans on different cycles
+
+A weekly plan and a monthly one share no boundary to wait for and no period to
+weight, so `changeAtNextCycle` and `changeNow` + `"prorate"` both answer
+`CycleChangeRequiresResetError`. `restart` is the move that works, and plain
+`changeNow` is the other way out — it keeps the period that is running.
+
+```ts
+import { CycleChangeRequiresResetError } from "@meterbase/sdk"
+
+try {
+  await meterbase.customers.plan.changeAtNextCycle(customer.id, {
+    plan: weekly.id,
+  })
+} catch (error) {
+  if (error instanceof CycleChangeRequiresResetError) {
+    await meterbase.customers.plan.restart(customer.id, { plan: weekly.id })
+  } else throw error
+}
+```
+
+#### Reading where they stand
+
+```ts
+const current = await meterbase.customers.plan.retrieve(customer.id) // or null
+const scheduled = await meterbase.customers.plan.pending(customer.id) // or null
+const { data } = await meterbase.customers.plan.history(customer.id)
+```
+
+`retrieve` is the plan **in force now**, which is not always the newest
+instruction — a change dated ahead does not govern yet — and is `null` for a
+customer holding no plan. That is a default deny rather than a failure, so it
+is an answer here rather than a thrown `NotFoundError`; a customer who does not
+exist at all still throws one.
+
+`pending` is the change waiting to land, and at most one ever is: a newer
+instruction supersedes the one before it. `history` is the whole trail,
+superseded rows included, newest first — it is the audit log of what was asked
+for, not only of what happened.
+
+To call off a change that has not landed:
+
+```ts
+await meterbase.customers.plan.cancelScheduledChange(customer.id)
+```
+
+Naming the plan a customer already holds is what supersedes a pending
+instruction, and writes no new row of its own — so this reads the plan in force
+and names it back. It returns the assignment still in force, or `null` for a
+customer holding no plan, who can have nothing pending.
+
+### 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                                                          |
+| `CycleChangeRequiresResetError`    | 422 — an `InvalidRequestError`: the two plans' cycles differ, so use `restart`           |
+| `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.3.0 is a breaking change**, following the engine's own.
+
+- `track` no longer takes `occurred_at`. The engine dates every event by the
+  database clock the write runs under, and refuses the field outright. The
+  receipt still carries `occurred_at` and `recorded_at`, now the same instant.
+  `occurred_at_out_of_window` no longer exists.
+- `Reconciliation` is `none | prorate | reset`. `rebalance` is gone from what
+  you can send; it survives on historical assignment rows, which read as
+  `RecordedReconciliation`. `reconciliation_already_applied` and
+  `reconciliation_unsupported` no longer exist.
+- Plan allowances have no `reconciliation`, on the way in or out.
+- `customers.plan.retrieve` returns `Assignment | null` rather than throwing a
+  `NotFoundError` for a customer holding no plan.
+- `customers.retrieve` and `retrieveByExternalId` return a `CustomerWithPlan`:
+  the same customer with `plan` and `pending_plan` embedded. `customers.list`,
+  `create`, `update` and `delete` still answer a plain `Customer`.
+
+Additive in the same release: the plan-change helpers — `change`, `changeNow`,
+`changeAtNextCycle`, `restart`, `cancelScheduledChange` and `pending` — and
+`CycleChangeRequiresResetError`.
+
+**0.2.0 was 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 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.
+
+> **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.