@beakr/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,531 @@
-# Temporary Holding Version
+# @beakr/sdk
 
-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 TypeScript SDK for the Beakr public API. No runtime dependencies: it uses
+`fetch` and Web Crypto, so it runs in Node 18+, Deno, Bun, browsers and edge
+runtimes. Ships ESM and CommonJS with type definitions generated from the
+published API contract.
+
+```sh
+npm install @beakr/sdk   # not on npm yet; see "Installing before the first release"
+```
+
+The [Python SDK](https://github.com/BeakrHub/beakr-python) (`beakr-sdk`) has the
+same resources, and the [Beakr CLI](https://github.com/BeakrHub/beakr-cli) is
+built on it.
+
+## Quickstart
+
+Create a key in the Beakr web app (Settings, API keys; keys are created only
+there) and keep it in `BEAKR_API_KEY`.
+
+```ts
+import { Beakr } from "@beakr/sdk";
+
+const beakr = new Beakr(); // reads BEAKR_API_KEY, or pass { apiKey }
+// The API: `baseUrl`, else BEAKR_BASE_URL, else BEAKR_API_URL, else production.
+
+const me = await beakr.me.get();
+const projects = await beakr.projects.list(); // one page; beakr.projects.iter() follows every page
+
+// Read Knowledge through the same door Beakr's own agents use.
+const page = await beakr.knowledge.command("cat", { page: "Pump calibration" }, { scope: "Assay Lab" });
+
+// Context for an agent starting work, ready to drop into CLAUDE.md.
+const context = await beakr.engine.context({ projectId: "...", format: "claude_md" });
+```
+
+### Where the credential comes from
+
+The same order as the Python SDK, first match wins:
+
+1. `apiKey` or `tokens` passed to the client;
+2. `BEAKR_API_KEY`;
+3. `serviceAccount` passed to the client (a parsed file or its path);
+4. in Node.js, the Beakr CLI's sign-in for this API (`beakr auth login`): read
+   from `~/.beakr/credentials` (`$BEAKR_HOME/credentials`) when that holds a
+   current one, otherwise asked of the installed CLI (`beakr auth token --json`);
+5. in Node.js, the key saved by `beakr auth login --with-api-key`, when it was saved
+   for this API;
+6. the service account file named by `BEAKR_SERVICE_ACCOUNT_FILE`, else
+   `~/.beakr/service-account.json` when it exists.
+
+A stored sign-in or saved key is only used by a client pointed at the API that
+issued it. Pass `cliLogin: false` to skip links 4 and 5. Links 4 to 6 are
+resolved at the client's first request and work on every supported Node
+version (18 and later).
+
+The CLI keeps its sign-in in the OS keychain when one is available (the
+default on macOS), and refreshes it under a lock that only the CLI takes:
+refreshing rotates the pair, and presenting a spent refresh token revokes the
+login everywhere. So the SDK never reads the keychain or refreshes the sign-in
+itself. When the credentials file has no current sign-in for the API -- it is
+in the keychain, or its access token has expired -- the SDK runs the CLI
+(`BEAKR_CLI_PATH`, else `beakr` on the `PATH`), which reads it the way every
+`beakr` command does and refreshes it if needed, and keeps the access token it
+prints in memory until it expires. After a 401 on that token the SDK asks the
+CLI once more (naming the refused token by its SHA-256, never on the command
+line) and resends once. The refresh token never leaves the CLI. Without the
+CLI installed, an expired stored sign-in fails with `cli_login_expired`, and a
+keychain sign-in is not found; pass a credential instead.
+
+### Use a token pair you already hold
+
+```ts
+const signedIn = new Beakr({
+  // An OAuth pair from Beakr's sign-in issuer, with where it refreshes.
+  tokens, // { accessToken, refreshToken, expiresAt, tokenEndpoint, clientId }
+  onTokens: (rotated) => saveSomewhere(rotated), // a refresh may rotate; persist each pair
+});
+```
+
+The pair is refreshed at its issuer's `tokenEndpoint` (as the public client
+`clientId`) before it expires and on a 401; a pair without a `tokenEndpoint` is
+used until it expires and is not refreshed. To sign a person in, use the CLI
+(`beakr auth login`); the SDK then finds that sign-in on its own (above).
+
+### Upload a folder, download a file
+
+```ts
+// Node: walk a directory; sub-directories become folders, dotfiles are skipped.
+const uploaded = await beakr.uploads.uploadFolder("./docs", { projectId });
+
+// Browser or edge: the same, from entries (e.g. an <input webkitdirectory> list).
+await beakr.uploads.uploadEntries(
+  [...input.files].map((file) => ({ path: file.webkitRelativePath, data: file })),
+  { projectId, ingest: false }, // ingest: false keeps the files out of Knowledge
+);
+
+const { data, filename } = await beakr.files.download(artifactId); // any runtime
+await beakr.files.downloadTo(artifactId, "./downloads/"); // Node; a trailing / means a folder, created if missing
+
+// Search the original documents by meaning, then download a result in one step.
+const found = await beakr.knowledge.documentsSearch("who covers losses from defects");
+const link = await beakr.files.downloadLink(found.results![0]!.source_ref!);
+```
+
+Many files or whole directories go up as one batch with one indexing job:
+`const batch = await beakr.uploads.uploadMany(["results", "summary.pdf"], { projectId })`,
+then `await beakr.jobs.wait(batch)` (or pass `wait: true`).
+
+### Tell Knowledge what a project is about
+
+A project's Knowledge profile steers how Beakr compiles its files: what the
+project is for, the people, organizations and topics that matter, and the kinds
+of things to build pages for. Only the project's owners may set it.
+
+```ts
+await beakr.projects.setKnowledgeProfile(projectId, {
+  description: "Batch records, deviations and CAPAs for the Basel site",
+  goals: ["Track deviations to closure"],
+  entity_types: ["batch", "deviation", "capa", "supplier"],
+  core_people: [{ name: "Priya Natarajan", role: "Batch owner" }],
+});
+await beakr.projects.updateKnowledgeProfile(projectId, { focus_areas: ["pH excursions"] });
+const profile = await beakr.projects.knowledgeProfile(projectId);
+```
+
+`knowledgeProfile` throws `NotFoundError` (`code === "knowledge_profile_not_found"`)
+while the project has none.
+
+### Skills
+
+A skill is a SKILL.md folder your agent loads on demand. `skills.list` covers
+your own skills, your organization's, the built-in ones and public skills from
+anywhere; each carries `visibility`, `owner` (`me`, `org`, `system`, `anyone`),
+`origin` (`created`, `mined`, `imported`, `system`) and `installed`, and each
+is also a filter.
+
+```ts
+const mine = await beakr.skills.list({ owner: "me" });
+const toInstall = await beakr.skills.list({ visibility: "public", installed: false });
+for await (const skill of beakr.skills.iter({ owner: ["org", "system"] })) console.log(skill.slug);
+
+const skill = await beakr.skills.createFromFolder("skills/plate-reader"); // or a .zip (Node)
+await beakr.skills.download(skill.id, "exported/");                       // exported/plate-reader/ (created if missing)
+const [installable] = toInstall.data;
+if (installable) await beakr.skills.install(installable.id);
+for (const proposal of (await beakr.skills.proposals.list()).data) {
+  await beakr.skills.proposals.accept(proposal.id);
+}
+```
+
+`skills.get` takes an id or a slug; a slug resolves to your own skill first,
+then a built-in, then one you installed, then your organization's.
+`uploadBundle(skillId, files, { expectedSha256: bundle.files_sha256 })` throws
+`ConflictError` (`code === "skill_conflict"`) when the skill changed since you
+read it. The digest is the bundle's `files_sha256`; passing `expectedSha256:
+undefined` throws a `TypeError` rather than silently writing without the check.
+
+### Know when Knowledge is ready
+
+Uploaded files reach a project's Knowledge in the background after indexing. Wait for it
+before asking questions that depend on those files, and retry what failed:
+
+```ts
+import { KnowledgeFailedError } from "@beakr/sdk";
+
+// The batch's own files: indexing, then Knowledge.
+const result = await beakr.uploads.uploadMany("./docs", {
+  projectId,
+  wait: "knowledge",
+  knowledgeWait: { timeoutMs: 30 * 60_000 },
+});
+console.log(result.batch?.knowledge); // { queued: 0, running: 0, created: 41, failed: 1, ... }
+
+// The whole project.
+const status = await beakr.projects.waitUntilReady(projectId, { timeoutMs: 15 * 60_000 });
+for (const failed of status.failed_files ?? []) {
+  console.log(failed.path, failed.error_code, failed.reason); // knowledgeFailures() lists all
+}
+if (status.failed) await beakr.projects.retryFailed(projectId); // or retryFailed(projectId, [id])
+
+await beakr.projects.waitUntilReady(projectId, { raiseOnFailure: true }).catch((error) => {
+  if (error instanceof KnowledgeFailedError) console.log(error.status.failed_files);
+});
+```
+
+`ready` is true when nothing is queued or running (`KnowledgeTimeoutError` at the timeout).
+Failed files never end a wait early; `error_code` is one of `processing_failed`, `timed_out`,
+`concurrent_update` or `compile_failed`, and a retry is safe to repeat.
+
+Every file goes through the resumable upload (a small file is one part); an interrupted one
+rejects with `UploadInterruptedError`, whose `uploadId` resumes it with
+`beakr.uploads.resume`. Folder uploads do not follow symbolic links. Node-only
+helpers (`uploadFolder`, `downloadTo`) load `node:` modules lazily, so the SDK still imports
+in edge and browser runtimes.
+
+### Import a coding-agent session and compound it
+
+```ts
+const result = await beakr.conversations.import({
+  client: "claude-code",
+  sessionId: "session-123",
+  baseIndex: alreadySent, // send only new messages, and say where they start
+  messages: [{ role: "user", content: "Use the April calibration from now on." }],
+  compound: true, // import and queue compounding in one request
+});
+```
+
+Message text is kept only by opt-in. `compound: true` holds it, for a bounded
+time, until the capture reads it; `holdText: true` holds it the same way for a
+later `beakr.engine.compound(...)` without queuing one now; `storeFullText:
+true` keeps it. A plain import keeps the summary and metadata only, and a later
+compound answers `nothing_to_compound`.
+
+`beakr.engine.cancelCompound(conversationId)` stops a queued or running
+compound: a batch already being read finishes and its proposals stay, no further
+batch starts, and the conversation's `compound_status` reads `cancelled`.
+`engine.compound` resumes from where it stopped.
+
+Without `baseIndex` a batch is read as the whole session from the start. A
+`baseIndex` past the number of messages already stored (a gap) rejects with a
+`ConflictError` whose `expectedBaseIndex` says where to resend from. A
+`baseIndex` below that count is not an error: the stored session is replaced
+from that position on, by design for clients that compact their transcripts,
+so a stale resend rewrites history rather than failing. Track what you sent.
+
+### Query what the caller has connected
+
+The same read-only tools Beakr's own agent uses on Slack, Drive, Jira and the
+rest, against the integrations the caller connected:
+
+```ts
+const { data: tools } = await beakr.integrations.tools({ provider: "slack" });
+const result = await beakr.integrations.callTool("slack_search_messages", { query: "calibration" });
+console.log(result.content, result.sources);
+```
+
+Tools that change data in the connected account are refused.
+
+### Send an interview, read what came back
+
+```ts
+const link = await beakr.interviews.createLink("Assay onboarding", {
+  goal: "How the team runs the plate reader",
+  recipient: { name: "Ada", email: "ada@example.com" }, // recorded only; Beakr sends nothing
+});
+sendItYourself(link.url); // the link is shown once
+const result = await beakr.interviews.linkResult(link.link_id);
+if (result.status === "completed") await beakr.interviews.sendToProjects(link.link_id, [projectId]);
+```
+
+### Tokens for the users of your own product
+
+With a service account's key, mirror your users and mint each a short-lived
+token that can never do more than the key. The service account and its key are
+made in the web app (Settings > Organization > Developer); creating either from
+an API key or token is refused with `session_required`. Add the service account
+to the projects it manages before attaching labels to them.
+
+```ts
+// Acts as the external user: its label and project memberships decide what it reaches.
+const user = await beakr.externalUsers.create({ external_id: "acme-42", name: "Ada" });
+const label = await beakr.labels.create({ name: "acme" });
+await beakr.labels.addMember(label.id, { user_id: user.user_id });
+await beakr.labels.attachProject(label.id, { project_id: projectId }); // viewer
+const { token } = await beakr.endUserTokens.mint({
+  externalUserId: user.user_id,
+  scopes: ["kb:read", "agent:run"],
+  ttlSeconds: 900,
+});
+const asUser = new Beakr({ apiKey: token });
+
+// Or: acts as your service account, confined to the projects you name.
+const scoped = await beakr.endUserTokens.mint({
+  subject: "acme-42",
+  projectIds: [projectId],
+  scopes: ["kb:read"],
+});
+```
+
+Give either `externalUserId`, or `subject` with `projectIds`; the server refuses both.
+
+### What this installation serves: `beakr.meta.capabilities()`
+
+A self-hosted Beakr installation serves only part of the documented contract
+(no organization administration, external users, end-user tokens, service
+accounts or integrations) and answers a bare 404 for the rest. Each server
+lists what it serves in its own `GET /v1/public/openapi.json`;
+`capabilities()` reads it once per base URL (cached for five minutes) so a
+client can hide what is not there instead of failing on it:
+
+```ts
+const caps = await beakr.meta.capabilities();
+if (!caps.serves("GET", "/v1/integrations")) {
+  console.log("This Beakr installation does not provide integrations");
+}
+```
+
+`serves` takes a concrete path or a contract template. A server that publishes
+no document is assumed to serve everything, and a route outside the documented
+contract is always assumed served: the document cannot speak for it.
+
+## Errors
+
+Every failure is a `BeakrError` with `status`, `code` (from the error
+envelope's `error.code`), `message` and `requestId`. Subclasses:
+`AuthenticationError` (401), `PermissionDeniedError` (403, with
+`requiredScope`; `PersonReviewRequiredError` for `person_review_required`,
+where only a person or a key holding `proposals:accept` may accept proposals
+or commit Knowledge), `NotFoundError`, `ConflictError`, `ValidationError`,
+`RateLimitError` (with `retryAfter`), `ServerError`, `APIConnectionError`,
+`KnowledgeCommandError` (a refused Knowledge command), `UnexpectedResponseError`
+(a success whose body is an HTML page where JSON was expected) and
+`DeviceLoginError`; `runs.answer()` throws `RunFailedError` for a run
+that ended `error`, `failed` or `cancelled`. An error from the API ends its
+message with `(called <baseUrl>)` and carries `baseUrl`, so a key sent to the
+wrong host reads as that. A body that is not JSON is never the message: an HTML
+page (a base URL that is not a Beakr API, or a proxy in front of it) is named by
+its title, with a `fix` saying to check the base URL, and other text is cut to a
+short excerpt. Branch on `code`, never on the message.
+
+Codes a program should expect from sensitive actions: `session_required`
+(do it in the web app), `mfa_required` (verify a second factor and retry),
+`client_not_allowed`, `insufficient_scope`. Web app only, always refused to API
+keys and tokens: creating API keys, creating a service account, minting or
+disabling its keys. Deleting a project and changing a member's role are refused
+to keys and tokens wherever the organization protects sensitive actions (SSO or
+step-up required).
+
+`KnowledgeCommandError` carries the response's `status` and `requestId` like
+every other error, the door's `outcome.error_code` as `code` when it named one
+(`invalid_arguments`, `unknown_command`, `scope_not_found`,
+`citation_not_citeable`, ...; otherwise `knowledge_command_error`), and the
+whole reply as `result`.
+
+## Retries and idempotency
+
+- 429 is retried for every request, waiting the server's `Retry-After`. The
+  header may be seconds or an HTTP-date (IMF-fixdate, or the obsolete RFC 850
+  and asctime forms); a date already past retries at once, and one that is not
+  a valid date is ignored in favor of the normal backoff. A wait beyond 60
+  seconds is not taken: the error is thrown instead, with
+  `RateLimitError.retryAfter` in seconds.
+- 500, 502, 503, 504 and connection errors are retried only where a resend
+  cannot duplicate an effect: reads, `PUT`, `DELETE`, starting an agent run
+  (the route deduplicates), and every public create.
+- Creates send an `Idempotency-Key` that stays the same across retries, and
+  the engine replays a create resent with the same key and body: the retry
+  returns the first result, never a second resource (`REPLAYING_CREATES` in
+  `src/replay.ts`). A resend that meets an earlier attempt still holding the
+  key (409 `idempotency_in_progress`) waits its `Retry-After` and tries again.
+- Other POSTs (decisions such as accept, token exchanges, reads with a body)
+  are never resent after an ambiguous failure; 501, 505 and other 4xx are
+  never retried.
+
+`maxRetries` (default 2) and `timeoutMs` (default 60 000) are client options.
+
+## Resources
+
+The client covers the documented API only:
+
+`me`, `meta` (`openapi`, `capabilities`), `projects`, `members`, `org` (`serviceAccounts`),
+`externalUsers`, `endUserTokens`, `labels`, `uploads` (one file, a folder,
+resume), `files` (downloads), `jobs` (`wait`), `knowledge` (with
+`proposals` and `pages.sources()`), `conversations`, `engine` (`context`,
+`compound`, `cancelCompound`), `runs`, `interviews`, `skills` (with `proposals`) and
+`integrations` (with `tools` / `callTool`).
+
+### Ask the agent
+
+```ts
+import { sourceWhere } from "@beakr/sdk";
+
+const { text, sources, run_id } = await beakr.runs.answer("How long is a compile lease?", { projectId });
+console.log(text); // "... lasts 300 seconds (compile-lease.md › line 4)."
+for (const source of sources) console.log(sourceWhere(source));
+```
+
+`text` shows each citation as the readable reference in parentheses, as the
+engine renders it (`(memo.pdf › p. 7)`, `(Page Title › Section)`), and
+`sources` lists the cited documents in order of first use, one public source
+record each: `filename`, `provider`, `location` (`url`/`display_path` of the
+original, or `file_id` for Beakr's copy), and the cited `evidence`.
+`knowledge.pages.sources(pageId)` returns the same records. To show the answer
+as it is written, `for await (const chunk of beakr.runs.streamText(runId))`
+yields the visible text with each citation key numbered `[n]` in order of
+first use; those numbers are for display while streaming and do not index
+`runs.answer()`'s `sources`. `runs.stream()` yields the raw server-sent
+events.
+
+A run reads the organization's Knowledge unless `knowledge: false` is passed
+to `runs.start` or `runs.answer`; the server treats a run that does not ask for
+Knowledge as one with it turned off, so the SDK always sends the toggle.
+
+Uploads use the resumable flow (`/v1/uploads`) and declare the file's
+SHA-256 (`content_hash`), hashed as a stream so no runtime holds the whole file.
+
+Every operation in the documented contract also has a typed method on
+`beakr.api`, grouped by area and generated from the contract:
+
+```ts
+const project = await beakr.api.projects.createProject(
+  { body: { name: "Assays" } },
+  { idempotencyKey: "create-assays" }, // a retry with the same key replays, never duplicates
+);
+await beakr.api.knowledge.getWikiPage({ path: { page_id: pageId } });
+for await (const conversation of beakr.api.conversations.listConversationsAll()) {
+  console.log(conversation);
+}
+```
+
+Creates send an `Idempotency-Key` (pass your own to make retries across processes
+safe); operations that page with a cursor also get an `...All()` iterator.
+`OPERATIONS` lists every method's HTTP method and path, and
+`test/contract-coverage.test.ts` fails if any contract operation lacks one.
+
+## Development
+
+```sh
+npm install
+npm run regen      # after an engine contract change: generate, typecheck, build
+npm run generate   # regenerate src/generated/ from the documented contract
+npm run build
+npm test
+npm run typecheck
+```
+
+Edge support is tested in Vercel's Edge Runtime context (`@edge-runtime/vm`,
+`test/edge-runtime.test.ts`): no `process`, `require` or `Buffer`, requests
+through a mocked `fetch`.
+
+`npm run generate` reads, in order: a path or URL argument, `BEAKR_OPENAPI`, or
+the committed `docs/api/public-openapi.json` of the engine checkout
+(`BEAKR_ENGINE_PATH`, else a sibling `beakr-engine`), else this repository's
+snapshot of it.
+
+CI reads no other repository. The files it checks against are committed under
+`snapshots/`: `snapshots/beakr-engine` (the documented contract and the API
+changelog; never the engine's internal contract) and `snapshots/beakr-python`
+(the release scripts every client repository shares, which must match ours).
+`snapshots/manifest.json` pins the commit each came from (with
+`uncommitted_changes` when taken from a working tree) and each file's SHA-256.
+After an engine or beakr-python change, refresh them from checkouts beside this
+one (or named with `--engine` / `--python`), then regenerate:
+
+```sh
+python3 scripts/refresh_snapshots.py refresh   # rewrite snapshots/ and the manifest
+python3 scripts/refresh_snapshots.py diff      # exit 1 when stale against the checkouts
+python3 scripts/refresh_snapshots.py verify    # offline: the files are the manifest's (CI)
+BEAKR_ENGINE_PATH=snapshots/beakr-engine npm run regen
+```
+
+The engine's CI checks this repository and beakr-python out on the branch named
+like its own and runs these checks against the real repositories, so drift
+shows up there before a refresh here.
+Resource methods take their request and response types from that schema, so a
+contract change that breaks a method fails `npm run typecheck`.
+
+The documented contract is the only one this package is built from: it carries
+no code for routes the API serves without documenting them (the Beakr CLI keeps
+its own private client for the few it calls). `test/shipped-surface.test.ts`
+packs the package as it would be published and fails on any route in it outside
+that contract. `CHANGELOG.md` is not in the package for that reason: it repeats
+the API changelog's history, which names routes that are now unlisted.
+
+## Installing before the first release
+
+Until `@beakr/sdk` is on npm, install a packed build of this repository:
+
+```sh
+git clone https://github.com/BeakrHub/beakr-typescript && cd beakr-typescript
+npm ci && npm run build && npm pack      # beakr-sdk-<version>.tgz
+npm install /path/to/beakr-sdk-<version>.tgz   # in your project
+```
+
+## Release
+
+Nothing publishes automatically yet. `.github/workflows/publish.yml` is
+prepared but runs only when a GitHub release is published and the repository
+variable `NPM_PUBLISH_ENABLED` is `true`.
+
+To enable it once:
+
+1. Create the `@beakr` organization (scope) on npm, if it does not exist yet,
+   and publish nothing by hand.
+2. On npmjs.com, add a Trusted Publisher for `@beakr/sdk` (package settings,
+   Trusted publishing; for a package that has never been published, follow
+   npm's instructions for a first trusted publish): GitHub Actions, owner
+   `BeakrHub`, repository `beakr-typescript`, workflow `publish.yml`,
+   environment `npm`.
+3. In this repository, create the `npm` environment (Settings, Environments),
+   ideally with required reviewers, and set the repository variable
+   `NPM_PUBLISH_ENABLED` to `true`.
+
+The workflow authenticates with GitHub's OIDC token (no npm token is stored)
+and publishes with provenance.
+
+### Versions and release notes come from the API contract
+
+`scripts/prepare_release.py` (Python 3, standard library only; identical in
+every Beakr client repository, and tested in beakr-python) compares the
+engine's contract at the last release (`release/released.json`) with the current
+one, using the engine's compatibility rules (`scripts/contract_compat.py`). A
+breaking change needs a major bump (below 1.0, a minor one), an added or changed
+operation a minor bump, a wording change a patch. `package.json`,
+`package-lock.json` and `src/version.ts` are kept in step
+(`release/config.json`). The API changelog entries added since that release
+become the release's section in `CHANGELOG.md`; `### Client changes` is
+hand-written and kept across reapplies.
+
+```sh
+python3 scripts/prepare_release.py plan     # what changed, which bump it needs
+python3 scripts/prepare_release.py apply    # bump versions, write CHANGELOG.md
+python3 scripts/prepare_release.py check    # what CI and publishing run
+# After publishing: record the engine commit it was built from, then refresh
+# the snapshot so it carries that commit's contract and changelog
+# (snapshots/beakr-engine/release-base/<sha>), which the offline release check reads.
+python3 scripts/prepare_release.py record --engine-commit <engine sha>
+python3 scripts/refresh_snapshots.py refresh --engine <engine checkout>
+```
+
+## Storing tokens
+
+The SDK keeps tokens in memory and hands every rotated pair to `onTokens`; it
+never writes them to disk (it reads the CLI's stored sign-in, above, but never
+writes or refreshes it). If your application persists them and runs more than
+one process with the same login, coordinate refresh yourself: hold a lock while
+refreshing, reload the stored pair under it, and use a pair another process
+already rotated instead of presenting the old refresh token. Beakr revokes a
+whole sign-in when a used refresh token is presented again. Store each login
+with the API origin that issued it and only send it back to that origin.