@relume_io/partner-node 0.0.0-stage → 2.0.0

package/README.md

@@ -1,3 +1,362 @@
-# Temporary Holding Version
+# @relume_io/partner-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## Install
+
+```sh
+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.
+
+## Quickstart (Express)
+
+```ts
+import express from 'express';
+import { Relume } from '@relume_io/partner-node';
+
+const relume = Relume.init<express.Request>({
+  secretKey: process.env.RELUME_SECRET_KEY!,
+});
+
+// Who is signed in, for the builder's GET /relume/session
+relume.getUserIdFromRequest((req) => req.session?.userId ?? null);
+
+relume.onGetUser(async (userId) => {
+  const user = await db.users.find(userId);
+  return user ? { name: user.name, email: user.email } : null; // null → 404
+});
+relume.onGetCredits(async (userId) => ({
+  balance: await wallet.balance(userId),
+}));
+relume.onChargeCredits(
+  async ({ userId, chargeId, partnerCredits }) =>
+    wallet.debit(userId, partnerCredits, { ref: chargeId }), // → { ok, balance }
+);
+relume.onReverseCharge(
+  async ({ userId, reversalId, chargeId, partnerCredits }) =>
+    wallet.credit(userId, partnerCredits, {
+      ref: reversalId,
+      reverses: chargeId,
+    }),
+);
+
+const app = express();
+app.use('/relume', relume.express()); // before express.json()
+app.use(express.json());
+```
+
+Then, in Relume's partner settings, set your 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`                                        |
+| `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, requestId }`. Quote the
+`requestId` to Relume support.
+
+### `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.
+- **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`.
+
+### `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.
+- `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>`.
+
+**Next.js** (`app/relume/[route]/route.ts`):
+
+```ts
+import { relume } from '@/lib/relume';
+
+export const GET = relume.fetchHandler;
+export const POST = relume.fetchHandler;
+```
+
+**Hono:**
+
+```ts
+app.all('/relume/*', (c) => relume.fetchHandler(c.req.raw));
+```
+
+**Cloudflare Workers:**
+
+```ts
+export default { fetch: (request: Request) => 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
+
+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.
+
+## Options
+
+```ts
+Relume.init({
+  secretKey: 'sk_test_…', // required; test or live
+  apiBaseUrl: 'https://…', // defaults to production; 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
+  onHandlerError: (error, info) => logger.error({ error, ...info }),
+});
+```
+
+`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.
+
+## 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).
+
+```ts
+const { clientSecret } = await relume.sessions.create({ userId: '42' });
+
+const user = await relume.users.get('42'); // { userId, status, siteCount, … }
+await relume.users.deactivate('42');
+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 entry = await relume.ledger.get('ch_…'); // with partnerResponse
+const prices = await relume.prices.list();
+```
+
+```ts
+try {
+  await relume.users.reactivate('42');
+} catch (error) {
+  if (error instanceof RelumeError && error.code === 'user_suspended') {
+    // Only Relume staff can reactivate this user.
+  }
+}
+```
+
+### 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);
+}
+```
+
+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`:
+
+```ts
+const entries = relume.ledger.list({ after: await loadCursor() });
+for await (const page of entries.pages()) {
+  await upsertEntries(page.data);
+  await saveCursor(page.nextCursor); // checkpoint after each page
+}
+```
+
+`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, … } }]
+```
+
+### 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.
+
+## 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:
+
+```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`;
+- 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.
+
+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.
+
+## 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).