@relume_io/partner-node 2.1.0 → 2.2.1

package/README.md

@@ -3,11 +3,11 @@
 The server SDK for Relume partners. It answers Relume's signed calls and
 serves builder sessions, so your backend never writes any cryptography.
 
-It implements the server side of the
-[Relume Partner Protocol v1](../../docs/partner-protocol/v1.md). Pair it with
-[`@relume_io/partner-embed`](../embed) on your page. The
-[partner docs](https://apis.relume.io/nova/docs/partners) have quickstarts for
-Express and Next.js, guides and the partner API reference.
+Your page needs
+[`@relume_io/partner-embed`](https://www.npmjs.com/package/@relume_io/partner-embed).
+The [partner docs](https://apis.relume.io/nova/docs/partners) have
+quickstarts, guides and the partner API reference. For Go, use
+[`github.com/relumetech/partner-sdk/go`](https://pkg.go.dev/github.com/relumetech/partner-sdk/go).
 
 ## Install
 
@@ -16,7 +16,8 @@ npm install @relume_io/partner-node
 ```
 
 Node 20 or later, or any runtime with `fetch` and Web Crypto (Cloudflare
-Workers, Bun, Deno, Next.js edge). No runtime dependencies.
+Workers, Bun, Deno, Next.js edge). No runtime dependencies. Install the same
+version as `@relume_io/partner-embed`.
 
 ## Quickstart (Express)
 
@@ -55,107 +56,93 @@ app.use('/relume', relume.express()); // before express.json()
 app.use(express.json());
 ```
 
-Then, in Relume's partner settings, set your endpoint URL to
+## Endpoint URL
+
+On the Partners page in Relume, set each environment's endpoint URL to
 `https://<your backend>/relume/calls`.
 
-## What it mounts
-
-| Route                 | Called by                  | Does                                                                                                                                |
-| --------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `GET /relume/session` | `@relume_io/partner-embed` | Refuses another site, resolves the user with `getUserIdFromRequest`, calls `POST /sessions`, returns `{ clientSecret, expiresAt }`. |
-| `POST /relume/calls`  | Relume                     | Verifies `Relume-Signature` and the 5-minute window, routes by `type`, runs your callback, validates what it returns.               |
-
-`relume.express()` answers exactly `/session` and `/calls` under its mount
-path (`app.use('/relume', …)`), or `/relume/session` and `/relume/calls` when
-mounted at the root, and passes everything else on. `relume.fetchHandler`
-answers any path ending in `/session` or `/calls`, because your framework has
-already routed the request to it.
-
-CORS preflights (`OPTIONS`) are left to your app: `express()` passes them on
-to the next middleware, and `fetchHandler` answers `204` with no CORS headers.
-
-If your backend is on another origin from your page, pass `sessionUrl` to
-`Relume.init` in the embed and allow your page's origin, with credentials and
-the `Relume-Embed` header, in that route's CORS response. Use an exact
-allowlist: never reflect the request `Origin` and never use `*`.
-
-Any site can make a signed-in user's browser call the session route, so it
-refuses two things before it looks at the user: a request with
-`Sec-Fetch-Site: cross-site`, which only another site's page sends, and one
-without the `Relume-Embed: 1` header `@relume_io/partner-embed` sends. The
-header makes a cross-origin request need a CORS preflight, so a link or form
-on another site can't get one. Neither helps against a script on your own
-page: any script there can ask the route for a session for the signed-in
-user, or answer the builder's session request with a client secret for
-another of your users, which opens the builder as them. Load only scripts you
-trust where the builder is embedded.
-
-| Situation                                    | Answer                                                       |
-| -------------------------------------------- | ------------------------------------------------------------ |
-| Bad or missing signature, or stale `t`       | `401 invalid_signature`; your callback isn't called          |
-| Unknown `type`, or no callback registered    | `400 unsupported_call_type`                                  |
-| Body that isn't valid for its `type`         | `400 invalid_request`                                        |
-| `environment` isn't your secret key's        | `400 environment_mismatch`; your callback isn't called       |
-| `onGetUser` returns `null`                   | `404 user_not_found`                                         |
-| `onChargeCredits` returns `{ ok: false }`    | `402 insufficient_credits`, with `balance`                   |
-| A callback throws, or returns a bad shape    | `500 internal_error`, and `onHandlerError` gets the error    |
-| No `Relume-Embed: 1` header (session route)  | `400 embed_header_missing`, and `onHandlerError` says why    |
-| `Sec-Fetch-Site: cross-site` (session route) | `403 cross_site_request`                                     |
-| Nobody signed in (session route)             | `401 not_signed_in`                                          |
-| `POST /sessions` refused (session route)     | Relume's status and `{ error }`, e.g. `403 user_deactivated` |
-
-Every response is JSON with `Cache-Control: no-store`.
-
-## The callbacks
-
-Each callback gets a second argument, `{ type, environment, requestId }`.
-Quote the `requestId` to Relume support. `environment` is always your secret
-key's (`'test'` for `sk_test_…`, `'live'` for `sk_live_…`): every call Relume
-signs says which environment it is for, and one for the other environment is
-refused before a callback runs, so a test call can never move a live wallet.
-Still give test and live their own endpoint URLs, each with its own client.
+- Relume's servers call it, so it must be reachable from the internet. On
+  `localhost`, use a tunnel such as `cloudflared tunnel --url http://localhost:3000`
+  or `ngrok http 3000`.
+- Give test and live their own URLs, each served with that environment's
+  secret key. Live URLs must be `https`.
+- The builder can't open for a new user until the endpoint answers: Relume
+  calls `user.get` before their first session.
+
+## Routes
+
+| Route                 | Called by     | Does                                                                                                       |
+| --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
+| `GET /relume/session` | the embed SDK | Finds the user with `getUserIdFromRequest`, calls `POST /sessions`, returns `{ clientSecret, expiresAt }`. |
+| `POST /relume/calls`  | Relume        | Verifies `Relume-Signature`, runs your callback for the call's `type`, checks what it returns.             |
+
+`relume.express()` answers `/session` and `/calls` under its mount path
+(`/relume/session` and `/relume/calls` when mounted at the root), and passes
+everything else on. `relume.fetchHandler` answers any path ending in
+`/session` or `/calls`.
+
+| Situation                                                   | Answer                                                       |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| Bad or missing signature, or a timestamp over 5 minutes off | `401 invalid_signature`; your callback isn't called          |
+| Unknown `type`, or no callback registered                   | `400 unsupported_call_type`                                  |
+| A body that isn't valid for its `type`                      | `400 invalid_request`                                        |
+| `environment` isn't your secret key's                       | `400 environment_mismatch`; your callback isn't called       |
+| `onGetUser` returns `null`                                  | `404 user_not_found`                                         |
+| `onChargeCredits` returns `{ ok: false }`                   | `402 insufficient_credits`, with `balance`                   |
+| A callback throws, or returns a bad shape                   | `500 internal_error`; `onHandlerError` gets the error        |
+| Session route: no `Relume-Embed: 1` header                  | `400 embed_header_missing`                                   |
+| Session route: `Sec-Fetch-Site: cross-site`                 | `403 cross_site_request`                                     |
+| Session route: nobody signed in                             | `401 not_signed_in`                                          |
+| Session route: Relume unreachable or timed out              | `502 session_failed`, or `504` on a timeout                  |
+| Session route: `POST /sessions` refused                     | Relume's status and `{ error }`, e.g. `403 user_deactivated` |
+
+CORS preflights are left to your app: `express()` passes them to the next
+middleware, and `fetchHandler` answers `204` with no CORS headers, so put your
+CORS handling in front of it. If your page is on another origin from this
+backend, pass `sessionUrl` to the embed SDK, and allow your page's exact
+origin, with credentials and the `Relume-Embed` header, on the session route.
+Never answer with `*` and never echo the request's `Origin`.
+
+## Callbacks
+
+- **`getUserIdFromRequest(request) → userId | null`**: read the user from your
+  own session. Never take a user id from the query string or body. Pass your
+  framework's request type to `Relume.init<…>` to type `request`.
+
+The four `on…` callbacks below answer Relume's calls. Each gets a second
+argument, `{ type, environment, requestId }`. `environment` is always your
+secret key's: `'test'` or `'live'`. Quote `requestId` to Relume support.
+
+- **`onGetUser(userId) → { name?, email?, avatarUrl? } | null`**: `name` at
+  most 200 characters, `email` a valid address, `avatarUrl` an `https` URL.
+  `null` for a user you don't know.
+- **`onGetCredits(userId) → { balance }`**: a whole number of your own
+  credits, zero or more.
 
 ### `onChargeCredits(charge) → { ok, balance? }`
 
-- **Debit `partnerCredits` only.** `relumeCredits` is what Relume charges you
-  for the action, for your records. Never debit it from the user's wallet.
+- **Debit `partnerCredits` only.** `relumeCredits` is what Relume charges
+  you. Never debit it from the user.
 - **Idempotent on `chargeId`.** Relume retries a charge with the same
   `chargeId`. Debit at most once, and answer a repeat with the same result.
-- Return `ok: false` when the user can't afford it; the builder asks them to
-  top up.
-- Throwing (or timing out) makes the outcome unknown. Relume then never does
-  the work and always sends `credits.reverse` for that `chargeId`.
+- Return `ok: false` when the user can't afford it. The builder then asks
+  them to top up.
+- If you throw or time out, Relume doesn't do the work, and sends a reversal
+  for that `chargeId`.
+- A build of several pages is one charge, with `pageIds` instead of `pageId`
+  and both prices covering every page. Debit it like any other.
 
 ### `onReverseCharge(reversal) → { balance? } | void`
 
-- **Credit back `partnerCredits` only**, at most once per `reversalId`.
-- If `chargeId` names a charge you never debited (one that timed out before
-  reaching your wallet), credit nothing and return normally, and record that
-  `chargeId` as declined: an attempt can still reach your wallet after the
-  reversal (if your wallet stalled and caught up), and `onChargeCredits` must
-  then return `ok: false` for it without debiting. Recording it as a declined
-  charge lets your idempotency on `chargeId` do that.
+- **Credit back the reversal's `partnerCredits` only**, at most once per
+  `reversalId`. A reversal can cover part of a charge.
+- **If `chargeId` names a charge you never debited**, credit nothing, return
+  normally, and record that `chargeId` as declined. If the charge reaches you
+  later, `onChargeCredits` must return `ok: false` without debiting.
 - `chargeId` is absent for a staff refund. `reason` is `work_failed`,
   `charge_unknown` or `staff_refund`; accept new values.
 - Accept reversals for users you have since deactivated.
 
-### `onGetUser(userId) → { name?, email?, avatarUrl? } | null`
-
-`name` at most 200 characters, `email` a valid address, `avatarUrl` an
-`https` URL. Return `null` for an unknown user.
-
-### `onGetCredits(userId) → { balance }`
-
-A whole number of your own credits, zero or more.
-
-### `getUserIdFromRequest(request) → userId | null`
-
-Read the user from your own session. Never take a user id from the query
-string or body. Gets the Express/Node request for `express()`, or the
-`Request` for `fetchHandler`. Pass that type to `Relume.init<…>` to type
-`req`; it must have `headers` (`SessionRequest`), which every framework's
-request does, and is `{ headers: unknown }` otherwise.
-
 ## Other frameworks
 
 `relume.fetchHandler` is a `(Request) => Promise<Response>`.
@@ -175,30 +162,36 @@ export const POST = relume.fetchHandler;
 app.all('/relume/*', (c) => relume.fetchHandler(c.req.raw));
 ```
 
-**Cloudflare Workers:**
+**Cloudflare Workers:** a Worker reads its secrets from `env` on each request,
+so create the client there (`Relume.init` is cheap and holds no connection):
 
 ```ts
-export default { fetch: (request: Request) => relume.fetchHandler(request) };
+export default {
+  fetch(request: Request, env: Env) {
+    const relume = Relume.init<Request>({ secretKey: env.RELUME_SECRET_KEY });
+    // …register getUserIdFromRequest and the four callbacks…
+    return relume.fetchHandler(request);
+  },
+};
 ```
 
 **Anything else:** call `relume.handleCall({ rawBody, signatureHeader, requestId })`
 and `relume.handleSession(request)`. Each returns `{ status, headers, body }`.
-`handleSession` reads the request's headers, so pass it the fetch `Request`,
-the Node request, or an object with `headers`.
-
-### Raw bodies
+Pass `handleSession` the fetch `Request`, the Node request, or an object with
+`headers`.
 
-The signature covers the raw bytes, so a re-serialised body never verifies.
-Mount `relume.express()` before `express.json()`, or give it
-`express.raw({ type: 'application/json' })`. If a parser already consumed the
-body, the call is answered `500` and `onHandlerError` explains why.
+**Raw bodies:** the signature covers the raw bytes, so a parsed body never
+verifies. Mount `relume.express()` before `express.json()`, or give it
+`express.raw({ type: 'application/json' })`. Add nothing that parses the
+body in front of `fetchHandler`. If a parser got there first, the call is
+answered `500` and `onHandlerError` says why.
 
 ## Options
 
 ```ts
 Relume.init({
   secretKey: 'sk_test_…', // required; sk_test_… or sk_live_…
-  apiBaseUrl: 'https://…', // defaults to production; http only for localhost
+  apiBaseUrl: 'https://…', // default: production's; http only for localhost
   apiTimeoutMs: 15_000, // per partner API request attempt
   maxRetries: 2, // retries for 429s, 5xx answers and failed connections
   fetch, // custom fetch for partner API requests
@@ -206,16 +199,13 @@ Relume.init({
 });
 ```
 
-`Relume.init` returns a new client every time, with no global state, so test
-and live clients can run side by side. It throws for an `apiBaseUrl` that
-isn't `https`, except `http://localhost`, `127.0.0.1` and `[::1]`: every request
-carries your secret key.
+`Relume.init` throws for a missing key, or one that isn't `sk_test_…` or
+`sk_live_…`. It returns a new client every time, so test and live clients can
+run side by side.
 
 ## Calling the partner API
 
-Every partner API endpoint has a typed method. Each throws a `RelumeError`
-when the API refuses, with `status`, `code` (safe to switch on) and
-`requestId` (quote it to Relume support).
+Every partner API endpoint has a typed method.
 
 ```ts
 const { clientSecret } = await relume.sessions.create({ userId: '42' });
@@ -226,12 +216,26 @@ await relume.users.reactivate('42');
 
 const { siteId } = await relume.sites.create('42', { name: 'Bloom Florist' });
 const site = await relume.sites.get(siteId);
-const exported = await relume.exports.get(siteId, exportId); // not available yet: not_implemented
+const exported = await relume.exports.get(siteId, exportId); // not available yet: 501 not_implemented
 
 const entry = await relume.ledger.get('ch_…'); // with partnerResponse
-const prices = await relume.prices.list();
+
+const { data, creditUnit } = await relume.prices.get();
+// data: [{ action, partnerCredits (null until Relume sets it), relumeCredits }]
+// creditUnit: { singular: 'coin', plural: 'coins', iconUrl? }
 ```
 
+- `prices.get()` returns your prices and `creditUnit`: what the builder calls
+  your credits, and the icon it shows beside amounts. `prices.list()` returns
+  the prices alone.
+- A user who has never opened the builder has no Relume account, so
+  `sites.list` and `sites.create` answer `user_not_found`. Before creating a
+  site for them, call `sessions.create({ userId })`: it creates the account.
+- `sites.create` isn't idempotent, so it retries only a `429`.
+
+Each method throws a `RelumeError` when the API refuses, with `status`,
+`code` (safe to switch on) and `requestId` (quote it to Relume support):
+
 ```ts
 try {
   await relume.users.reactivate('42');
@@ -244,18 +248,12 @@ try {
 
 ### Lists
 
-`sites.list`, `ledger.list` and `usage.get` follow the cursor for you, a page
-at a time as you iterate:
-
-```ts
-for await (const site of relume.sites.list('42')) {
-  console.log(site.name);
-}
-```
+`sites.list`, `ledger.list` and `usage.get` follow the cursor for you: iterate
+items with `for await`, pages with `.pages()`, or collect them with
+`.toArray()`.
 
 To reconcile your wallet, poll the ledger from the cursor you stored last
-time. Entries come in change order and appear again when their status
-changes, so upsert on `id`:
+time. An entry appears again when its status changes, so upsert on `id`:
 
 ```ts
 const entries = relume.ledger.list({ after: await loadCursor() });
@@ -265,113 +263,54 @@ for await (const page of entries.pages()) {
 }
 ```
 
-`entries.nextCursor` is also there after a plain `for await`: the cursor of
-the last page you finished, so breaking out early never skips an entry.
-Site lists can't be polled this way (new sites sort to the front): list them
-from the beginning instead.
-
-```ts
-const rows = await relume.usage
-  .get({ from: '2026-10-01', to: '2026-11-01', groupBy: ['user'] })
-  .toArray(); // [{ userId, partnerCredits: { net, … }, relumeCredits: { net, … } }]
-```
+After a plain `for await`, `entries.nextCursor` is the cursor of the last
+page you finished, so breaking out early never skips an entry. Site lists
+can't be polled this way, because new sites sort to the front: list them from
+the beginning each time.
 
 ### Retries
 
-A `429` is retried after its `Retry-After` (unless that's over a minute).
-A `5xx` (other than `501` and `505`) or a failed connection is retried with
-exponential backoff, except on
-`sites.create`, which isn't idempotent: a retry could create a second site.
-A `Retry-After` on a `5xx` is honoured up to 8 seconds.
-`maxRetries` (default 2) sets how many retries follow the first attempt.
-The session route makes one attempt, without retries, because a browser is
-waiting on it.
-
-The request and response types (`User`, `Site`, `LedgerEntry`, `UsageRow`, …)
-are exported, and the Relume API is type-checked against the same
-definitions, so they match what the API sends.
+A `429` is retried after its `Retry-After`, unless that's over a minute. A
+`5xx` (except `501` and `505`) or a failed connection is retried with
+exponential backoff. `maxRetries` (default 2) sets how many retries follow the
+first attempt. The session route makes one attempt, because a browser is
+waiting.
 
 ## Checking your endpoint
 
-Before going live, run the conformance checker against your test endpoint.
-It works on any endpoint, whether or not it uses this SDK:
+Before going live, run the conformance checker against your test endpoint. It
+works on any endpoint, whether or not it uses this SDK:
 
 ```sh
 RELUME_SECRET_KEY=sk_test_… npx @relume_io/partner-node check \
   --url https://partner.example/relume/calls --user 42
 ```
 
-It calls your endpoint the way Relume does, and checks that it:
-
-- accepts a correctly signed call, including a rotation header with two
-  `v1=` values;
-- rejects another key's signature, a body changed after signing, a timestamp
-  more than 5 minutes off either way, and a call with no signature, with
-  `401`;
-- refuses a correctly signed call whose `environment` isn't the key's, with
-  `400`;
-- answers `user.get` and `credits.get` with bodies Relume accepts, and
-  `user.get` with `404` for a user id it has never seen;
-- debits a charge, and only once when the same `chargeId` comes again, with
-  the same answer as the first time;
-- answers `402` to a charge the user can't afford;
-- changes nothing when a charge it never debited is reversed, and debits
-  nothing if that charge arrives afterwards (record a reversed `chargeId` as
-  declined, see `onReverseCharge` above);
-- credits a reversal, and only once per `reversalId`;
-- doesn't let another site read the session route: it asks for a session from
-  `https://evil.example`, preflight and `GET`, and fails if the CORS response
-  grants that origin;
-- refuses a session request without the `Relume-Embed` header with `400`, and
-  one with `Sec-Fetch-Site: cross-site` with `403`, before looking for a
-  signed-in user.
-
-It finds the session route next to a `--url` ending in `/calls`; pass
-`--session-url` if yours is elsewhere. If a login answers that route before
-the SDK does, give the check a test user's cookie so it gets past it: in
-`RELUME_SESSION_HEADERS` (one `Name: value` a line), or with
-`--session-header "Cookie: …"` (repeatable). Prefer the variable: a cookie on
-the command line leaks like a key does.
-
-Give it the key in `RELUME_SECRET_KEY`, not `--secret-key`: a key on the
-command line lands in your shell history, CI logs and the process list.
-`--user` must be a user your wallet knows, holding at least 2 credits. The
-check charges them 2 and reverses everything it charged, and it prints a
-`NOTE` if the balance doesn't end where it started. Each check prints `PASS`,
-`FAIL` with the reason, or `SKIP` when an earlier failure means it can't run.
-It exits `0` only when every check passes, so you can run it in CI. A live key
-is refused unless you pass `--live`, because the check moves real credits.
-
-Inside this repo, `npm run check -- --url … --user …` runs it from source.
+It calls your endpoint the way Relume does, and checks signatures,
+environments, idempotency on `chargeId` and `reversalId`, the
+unknown-charge rule and the session route's refusals. The
+[partner docs](https://apis.relume.io/nova/docs/partners#tag/checking-your-endpoint)
+list every check.
+
+- `--user` must be a user your wallet knows, holding at least 2 credits. The
+  check charges them 2 and reverses everything it charged.
+- Pass the key in `RELUME_SECRET_KEY`, not `--secret-key`: a key on the
+  command line lands in shell history and CI logs.
+- It finds the session route next to a `--url` ending in `/calls`; otherwise
+  pass `--session-url`. If a login guards that route, give the check a test
+  user's cookie in `RELUME_SESSION_HEADERS` (one `Name: value` a line) or with
+  `--session-header "Cookie: …"` (repeatable). Prefer the variable: a cookie
+  on the command line leaks like a key does.
+- It exits `0` only when every check passes, so you can run it in CI. A live
+  key is refused unless you pass `--live`, because the check moves real
+  credits.
 
 ## Signing helpers
 
 For your own tests, or another runtime: `verifySignature`, `signCall`,
 `parseSignatureHeader` and `computeSignature`. They pass the protocol's
-[test vectors](../../docs/partner-protocol/test-vectors.json).
-
-## Examples
-
-[`examples/`](./examples) has the same partner on Express and on Hono, with
-an in-memory wallet that shows the idempotency rules:
-
-```sh
-RELUME_SECRET_KEY=sk_test_… npm run example:express   # :4600
-RELUME_SECRET_KEY=sk_test_… npm run example:fetch     # :4601
-```
-
-## Developing
-
-```sh
-npm ci
-npm run typecheck
-npm test            # unit, vectors and both sample servers
-npm run test:dist   # builds, then loads the ESM and CJS output
-```
-
-Releases go out from CI on a `partner-sdk/v*` tag, together with
-`@relume_io/partner-embed`: see [Releasing](../README.md#releasing).
+[test vectors](https://apis.relume.io/nova/docs/partners/test-vectors.json).
 
 ## License
 
-MIT. See [LICENSE](./LICENSE).
+MIT