@mdrnio/sdk 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MDRN
+
+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

@@ -1,3 +1,218 @@
-# Temporary Holding Version
+# MDRN SDK for JavaScript
 
-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.
+`@mdrnio/sdk` is the client for the products a deployed MDRN app has (Database, Files, Mail) and
+for who is calling it (Auth), for Workers and Node.js 20+. It has no dependencies. The same
+surface exists for [Python, Go and Rust](https://mdrn.io/docs/sdk/).
+
+## Install
+
+```sh
+npm install @mdrnio/sdk
+```
+
+## Quickstart
+
+```javascript
+import { Mdrn } from "@mdrnio/sdk";
+
+export default {
+  async fetch(request, env) {
+    const mdrn = Mdrn.fromEnv(env);
+    const user = mdrn.auth.user(request);
+    if (!user) return new Response("Sign in first", { status: 401 });
+    const note = await mdrn.db.create("notes", { owner: user.id, text: "hello" });
+    const me = await mdrn.auth.me(request);
+    if (me?.email) await mdrn.mail.send({ to: me.email, subject: "Saved", text: `Note ${note.id} saved.` });
+    return Response.json(note);
+  },
+};
+```
+
+## Where the values come from
+
+MDRN injects everything `fromEnv` reads into a release's environment: `MDRN_PROJECT_ID`,
+`MDRN_ENVIRONMENT` (`sandbox` or `production`), one `MDRN_<PRODUCT>_URL` and
+`MDRN_<PRODUCT>_TOKEN` per product switched on for the app (`DATABASE`, `STORAGE` for Files,
+`MAIL`), and the `MDRN_PRODUCTS` service binding, which `fromEnv` sends product requests
+through (a Worker cannot reach its own hostname with a global `fetch`). Anywhere else, give the
+values yourself; requests then go through the global `fetch`:
+
+```javascript
+const mdrn = new Mdrn({ origin: "https://your-app.apps.mdrn.io", project, environment: "sandbox", tokens: { database, storage, mail } });
+```
+
+The tokens are workload credentials, never for a browser. `mdrn.enabled` lists the products
+the client has (`db`, `files`, `mail`); a call on another throws `PRODUCT_NOT_ENABLED` with the
+variable that is missing. Options: `fetcher` (replaces the binding or global fetch),
+`timeoutMs` (10 000).
+
+Every write takes `{ idempotencyKey, signal }`. A key is generated when you give none; give
+one when you retry a change yourself and want it to happen once.
+
+## Database
+
+A record is a JSON object in a named collection, with an id MDRN assigns and a version that
+grows by one on every change.
+
+```javascript
+const task = await mdrn.db.create("tasks", { title: "Write docs", done: false });
+const same = await mdrn.db.get("tasks", task.id);              // null when there is none
+const page = await mdrn.db.list("tasks", { limit: 50, cursor }); // { items, nextCursor }
+const done = await mdrn.db.update("tasks", task.id, { done: true });
+await mdrn.db.delete("tasks", task.id);
+```
+
+`update` merges the fields you give into the record (a shallow merge). Without `version` it
+reads the record first, sends the change with the version it read as `If-Match`, and if the
+record changed in between (409 `CONFLICT`) it reads and tries again, up to three more times.
+With `{ version }` the change is sent once with that `If-Match` and a `CONFLICT` is yours to
+handle; that is the right choice when the user saw the version they are changing. `delete`
+works the same way. Keep cursors exactly as returned.
+
+## Files
+
+```javascript
+const file = await mdrn.files.upload({ name: "photo.jpg", type: "image/jpeg", bytes });
+const info = await mdrn.files.get(file.id);                   // null when there is none
+const page = await mdrn.files.list({ limit: 50, cursor });
+const { url, expiresAt } = await mdrn.files.downloadUrl(file.id); // a plain URL, 15 minutes
+await mdrn.files.delete(file.id);
+```
+
+`upload` does the whole upload: the file's SHA-256, an upload session, one part of 16 MiB after
+another sent to a grant URL with the grant's own headers (through the global `fetch`, never the
+binding and never with the token), completion, and then waits for MDRN to verify the bytes
+(polled every second, a minute at most) and answers the file in state `ready`. Pass
+`{ wait: false }` to get it back after one read instead (usually still `verifying`) and check
+`files.get` later. Bytes that do not match throw `FILE_REJECTED`.
+
+The session itself is there too, for resuming an upload or for letting a browser PUT the
+bytes: `mdrn.files.uploads.create`, `mdrn.files.uploads.get`, `mdrn.files.uploads.list`,
+`mdrn.files.uploads.parts`, `mdrn.files.uploads.part`, `mdrn.files.uploads.complete`,
+`mdrn.files.uploads.abort` and `mdrn.files.operation(id)`. Ask for a part grant in your
+backend and hand the browser the grant's `url`, `method` and `headers`.
+
+## Mail
+
+```javascript
+await mdrn.mail.send({ to: "ada@example.com", subject: "Welcome", text: "Hello Ada", html: "<p>Hello Ada</p>" });
+await mdrn.mail.send({ to: "ada@example.com", template: "welcome" });
+```
+
+A message is either your own content (`subject` and `text`, `html` if wanted) or a `template`
+of the project and environment, which supplies all three; giving a template together with
+any of them throws a `TypeError` before anything is sent. `attachments` (up to four,
+`{ filename, type, content }` with base64 content) and `senderId` (a verified sender domain;
+omit it when the workspace has one) go with either. The answer is `{ id, state: "queued" }`:
+accepted, not yet delivered. A Sandbox environment delivers like Production: to anyone, from
+a verified sender.
+
+## Auth
+
+MDRN's Proxy deletes every `x-mdrn-*` header a client sent and, for a signed-in visitor, adds
+`x-mdrn-user-id` and `x-mdrn-identity-token`. Your Worker is reachable only through the Proxy,
+so these can be trusted there (not under `wrangler dev`, where anyone can send them).
+
+```javascript
+const user = mdrn.auth.user(request);   // { id, token } or null
+const me = await mdrn.auth.me(request); // { id, email?, name?, metadataState, ... } or null
+```
+
+`me` asks MDRN Identity (`GET /v1/auth/me` through the binding, with the visitor's short-lived
+token) and answers null when nobody is signed in or the session has ended.
+
+### Sign-in from the browser
+
+With `loginPage` set to `own` in the Auth configuration, your app serves the sign-in page
+itself, and `@mdrnio/sdk/browser` makes that page's calls: no dependencies, nothing of the
+server-side client, so it runs in any browser, bundled with your page or served from
+`node_modules/@mdrnio/sdk/src/browser.js`.
+
+```javascript
+import { signIn, session, signOut } from "@mdrnio/sdk/browser";
+
+const auth = signIn({ returnPath: "/" }); // reads ?transactionId= and ?reason= from the address, and removes them
+auth.message;                             // a sentence to show when MDRN sent the visitor back, else null
+await auth.sendCode(email);               // starts the sign-in unless one is resumed, emails a six-digit code
+await auth.resendCode();                  // the same address again; MDRN allows one code a minute
+await auth.verifyCode(code);              // signs in and goes to returnPath; { navigate: false } answers { redirectUrl }
+await auth.continueWith("google");        // or "github": the browser goes to the provider and comes back signed in
+await session();                          // { state: "authenticated", user, expiresAt } or { state: "anonymous", user: null }
+await signOut();                          // ends the session on this address
+```
+
+A refused call throws a `SignInError`: `code` is MDRN's (`RATE_LIMITED`, `ACCOUNT_DISABLED`,
+`EMAIL_UNDELIVERABLE`, `EMAIL_PAUSED`, …) and `message` a sentence for the visitor. The calls go
+to the app's own address with the browser's cookies and the CSRF tokens MDRN asks for; a test
+gives `signIn`, `session` and `signOut` their own `fetch`, `location` and `history`.
+
+## Schedules
+
+A schedule declared in `mdrn.jsonc` arrives as a `POST` to its path. `scheduledRun(request)`
+returns the run, or `null` for any other request. The run id is the same on every attempt of
+one run, so use it as the idempotency key of the work.
+
+```javascript
+import { scheduledRun } from "@mdrnio/sdk";
+const run = scheduledRun(request);
+if (url.pathname === "/tasks/digest" && run) await sendDigest(run.runId);
+```
+
+## Errors
+
+Every failed call throws `MdrnError` with `status` (the HTTP status, 0 when no response was
+received), `code`, `message` (MDRN's, for your logs) and `details` (the response body).
+
+| `code` | `status` | When |
+| --- | --- | --- |
+| `PRODUCT_NOT_ENABLED` | 0 | The product has no URL or token in this environment |
+| `TIMEOUT` | 0 | No answer within 10 seconds (`timeoutMs`) |
+| `NETWORK_ERROR` | 0 | The request could not be sent |
+| `UNEXPECTED_REDIRECT` | 3xx | MDRN answered with a redirect, which is never followed |
+| `HTTP_ERROR` | 4xx, 5xx | A failure without MDRN's error envelope |
+| `INVALID_REQUEST`, `CONFLICT`, `NOT_FOUND`, `TEMPLATE_NOT_FOUND`, ... | 4xx, 5xx | The code from MDRN's envelope |
+| `UPLOAD_FAILED`, `FILE_REJECTED` | 0 | An upload did not accept parts, or MDRN rejected the bytes |
+
+`get` methods answer `null` for a 404 instead of throwing. `code` comes from MDRN's envelope
+(`{ error: { code, message } }`), or is `HTTP_ERROR` when the body is not one. A redirect is
+`UNEXPECTED_REDIRECT`: never followed, so the token cannot reach another origin. Nothing is
+retried except the conflict loop of `update` and `delete`. The product URLs must be https;
+plain http is accepted only to `localhost`, `127.0.0.1` or `[::1]`.
+
+```javascript
+try { await mdrn.db.update("tasks", id, patch, { version }); }
+catch (error) { if (error instanceof MdrnError && error.code === "CONFLICT") { /* reload */ } else throw error; }
+```
+
+## Testing
+
+`@mdrnio/sdk/fake` is an in-memory MDRN: the 19 operations with the real response shapes, status
+codes and error codes, idempotent replay, upload sessions with grants, a mail queue with the
+template rule, `/v1/auth/me` for a signed-in user, and a log of every request.
+
+```javascript
+import { createFakeMdrn } from "@mdrnio/sdk/fake";
+const fake = createFakeMdrn();
+const mdrn = Mdrn.fromEnv(fake.env, { transfer: fake.fetch }); // transfer: grant URLs, in Node
+const headers = fake.signIn("user_1", "user@example.com");       // the two Proxy headers
+await worker.fetch(new Request("https://app.example/", { headers }), fake.env);
+fake.collections.get("notes"); fake.sent; fake.log;
+```
+
+In workerd (Miniflare) give `fake.fetch` as the `MDRN_PRODUCTS` service binding and as the
+`outboundService`. Three collection names reach error paths: `broken` (502 without an
+envelope), `redirected` (307), `contended` (every read bumps the version).
+[`examples/round-trip.js`](examples/round-trip.js) is a Worker that uses most of the SDK;
+`npm test` runs it in Node and in workerd against the fake.
+
+## Versions
+
+`0.3.0`, shared with the other languages (`sdk/VERSION`, `sdk/CHANGELOG.md`). All four SDKs
+produce the same transcript against the same scenarios: `sdk/conformance/`.
+
+## Contributing
+
+This repository is a mirror: the code is published here from MDRN's main repository on every
+release, where it is tested against the API contract together with the other SDKs. Issues are
+welcome here. Pull requests are reviewed here and merged in the main repository, from where the
+next release brings them back.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@mdrnio/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "The MDRN SDK for JavaScript: Database, Files, Mail and Auth from a Worker or Node.js, sign-in from the browser, with an in-memory fake for tests",
+  "license": "MIT",
+  "homepage": "https://mdrn.io/docs/sdk/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdrn-io/mdrn.git",
+    "directory": "sdk/javascript"
+  },
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./fake": {
+      "types": "./src/fake.d.ts",
+      "default": "./src/fake.js"
+    },
+    "./browser": {
+      "types": "./src/browser.d.ts",
+      "default": "./src/browser.js"
+    }
+  },
+  "types": "./src/index.d.ts",
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/browser.d.ts

@@ -0,0 +1,72 @@
+/** Sign-in from the browser, for an app that serves its own sign-in page (`loginPage` set to
+ * `own`): the calls MDRN's hosted page makes, on the app's own address, with the browser's
+ * cookies. No dependencies and nothing from `@mdrnio/sdk`; it runs in any browser. */
+
+/** A sign-in call that did not succeed. `code` is MDRN's error code (ACCOUNT_DISABLED,
+ * RATE_LIMITED, EMAIL_UNDELIVERABLE, EMAIL_PAUSED, invalid_session, …), HTTP_ERROR for an answer
+ * without one, NETWORK_ERROR when nothing answered, INVALID_DESTINATION for a redirect off this
+ * origin; `status` the HTTP status, 0 for none. The message is a sentence to show the visitor. */
+export class SignInError extends Error {
+  constructor(status: number, code: string, message: string);
+  status: number;
+  code: string;
+}
+
+export type Provider = "google" | "github";
+
+/** Why MDRN sent the visitor back to the page. `provider_cancelled` and `unavailable` keep the
+ * sign-in, which the next call resumes; the others drop it, so the next call starts afresh. */
+export type SignInReason = "provider_cancelled" | "unavailable" | "provider_attempts_exhausted" | "transaction_expired" | "transaction_already_proved" | "account_disabled";
+
+/** The browser's own fetch, location and history unless given (a test gives its own). */
+export interface BrowserOptions {
+  fetch?: typeof fetch;
+  location?: Pick<Location, "href" | "origin" | "assign">;
+  history?: Pick<History, "replaceState">;
+}
+
+export interface SignInOptions extends BrowserOptions {
+  /** Where the visitor goes once signed in; "/" unless given. */
+  returnPath?: string;
+}
+
+export interface SignIn {
+  /** The reason the address carried, or null. */
+  readonly reason: SignInReason | null;
+  /** A sentence to show for `reason`, or null. */
+  readonly message: string | null;
+  /** Starts a sign-in unless one is being resumed, and emails `email` a six-digit code. */
+  sendCode(email: string): Promise<void>;
+  /** Emails a new code to the address `sendCode` was given; MDRN allows one a minute. */
+  resendCode(): Promise<void>;
+  /** Verifies the code and finishes the sign-in: the browser goes to `redirectUrl`, unless
+   * `navigate` is false; the answer is returned either way. */
+  verifyCode(code: string, options?: { navigate?: boolean }): Promise<{ redirectUrl: string }>;
+  /** Starts a sign-in unless one is being resumed, then sends the browser to the provider; the
+   * visitor comes back signed in at `returnPath`, or to this page with a `reason`. */
+  continueWith(provider: Provider): Promise<void>;
+}
+
+/** The sign-in of the page this is called on: it reads `?transactionId=` (a sign-in to resume)
+ * and `?reason=` (why the visitor is back) from the address and removes them from it. One per
+ * page load. */
+export function signIn(options?: SignInOptions): SignIn;
+
+export interface SessionUser {
+  id: string;
+  email?: string;
+  name?: string;
+}
+
+export interface Session {
+  state: "authenticated" | "anonymous";
+  user: SessionUser | null;
+  expiresAt?: string | null;
+}
+
+/** Whether the browser is signed in on this address (`GET /_mdrn/v1/auth/session`). */
+export function session(options?: BrowserOptions): Promise<Session>;
+
+/** Ends the browser's session on this address (`DELETE /_mdrn/v1/auth/session`, with the CSRF
+ * token); resolves once it has. */
+export function signOut(options?: BrowserOptions): Promise<void>;

package/src/browser.js

@@ -0,0 +1,190 @@
+// Sign-in from the browser, for an app that serves its own sign-in page (loginPage set to own):
+// the calls MDRN's hosted page makes (identity/web/login.js), on the app's own address, with the
+// browser's cookies. Nothing from index.js, no dependencies: fetch, URL, location and history,
+// each injectable for a test.
+
+/** A sign-in call that did not succeed. `code` is MDRN's error code (ACCOUNT_DISABLED,
+ * RATE_LIMITED, EMAIL_UNDELIVERABLE, EMAIL_PAUSED, invalid_session, …), HTTP_ERROR for an answer
+ * without one, NETWORK_ERROR when nothing answered; `status` the HTTP status (0 for none). The
+ * message is a sentence for the visitor. */
+export class SignInError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.name = "SignInError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+const PLATFORM_CSRF = "/_mdrn/v1/platform/csrf";
+const START = "/_mdrn/v1/auth/start";
+const SESSION = "/_mdrn/v1/auth/session";
+const PROVIDERS = ["google", "github"];
+const TRANSACTION = /^[a-f0-9]{64}$/;
+// Why MDRN sent the browser back here. A declined provider page, or one MDRN could not serve just
+// then, keeps its sign-in; a used-up, expired or finished one is dropped, so the next step starts
+// a new one. A Map, so a reason named like an Object property (constructor) is no reason at all.
+const REASONS = new Map([
+  ["provider_cancelled", "Sign-in was cancelled. Choose a way to sign in."],
+  ["unavailable", "Sign-in is unavailable right now. Try again in a moment."],
+  ["provider_attempts_exhausted", "That sign-in was tried too many times. Choose a way to sign in to start again."],
+  ["transaction_expired", "That sign-in expired. Choose a way to sign in to start again."],
+  ["transaction_already_proved", "That sign-in already finished in another tab or window. Choose a way to sign in to start again."],
+  ["account_disabled", "Account disabled"],
+]);
+const KEPT = new Set(["provider_cancelled", "unavailable"]);
+const WORDING = new Map([
+  ["ACCOUNT_DISABLED", "Account disabled"],
+  ["RATE_LIMITED", "Please wait before trying again."],
+  ["EMAIL_UNDELIVERABLE", "That address cannot receive email. Check it and try again."],
+  ["EMAIL_PAUSED", "This app cannot send sign-in emails right now. Try another way to sign in, or contact the app."],
+]);
+const FALLBACK = "Unable to continue. Check your code or restart sign-in.";
+const OFFLINE = "Could not reach the app. Check your connection and try again.";
+
+// The browser's own fetch, location and history unless a test injects its own.
+function browser(options = {}) {
+  const fetcher = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  if (typeof fetcher !== "function") throw new TypeError("fetch is required");
+  return { fetch: fetcher, location: options.location ?? globalThis.location, history: options.history ?? globalThis.history };
+}
+
+// One call on the app's own address: a GET, or `method` with a JSON body and the CSRF token.
+// The pre-sign-in cookie can be stale, so a 401 on the platform token is read once more, as
+// the hosted page does. A failure is a SignInError with MDRN's code and the visitor's sentence.
+async function request(env, path, { method = "GET", body, csrf } = {}) {
+  const init = { method, credentials: "same-origin", headers: {} };
+  if (method !== "GET") init.headers["X-CSRF-Token"] = csrf;
+  if (body !== undefined) { init.headers["Content-Type"] = "application/json"; init.body = JSON.stringify(body); }
+  let response;
+  try {
+    response = await env.fetch(path, init);
+    if (path === PLATFORM_CSRF && response.status === 401) response = await env.fetch(path, { credentials: "same-origin" });
+  } catch {
+    throw new SignInError(0, "NETWORK_ERROR", OFFLINE);
+  }
+  let value = null;
+  const text = await response.text();
+  if (text) { try { value = JSON.parse(text); } catch { value = null; } }
+  if (!response.ok) {
+    const code = typeof value?.error?.code === "string" ? value.error.code : "HTTP_ERROR";
+    throw new SignInError(response.status, code, WORDING.get(code) ?? FALLBACK);
+  }
+  return value;
+}
+
+const text = (value, what) => {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${what} is required`);
+  return value.trim();
+};
+
+class SignIn {
+  #env;
+  #returnPath;
+  #transaction;
+  #csrf;
+  #email;
+  reason;
+  message;
+
+  constructor(options) {
+    this.#env = browser(options);
+    this.#returnPath = options.returnPath ?? "/";
+    if (typeof this.#returnPath !== "string" || !this.#returnPath.startsWith("/")) throw new TypeError("returnPath must be a path starting with /");
+    const { location, history } = this.#env;
+    if (!location?.href) throw new TypeError("signIn runs in a browser, on the page MDRN sends visitors to");
+    const opened = new URL(location.href);
+    const reason = opened.searchParams.get("reason");
+    const given = opened.searchParams.get("transactionId");
+    this.reason = reason !== null && REASONS.has(reason) ? reason : null;
+    this.message = this.reason ? REASONS.get(this.reason) : null;
+    // An unknown reason drops the sign-in too: only a kept one is worth resuming.
+    this.#transaction = (reason === null || KEPT.has(reason)) && given !== null && TRANSACTION.test(given) ? given : null;
+    this.#csrf = null;
+    this.#email = null;
+    if ((reason !== null || given !== null) && history?.replaceState) {
+      opened.searchParams.delete("reason");
+      opened.searchParams.delete("transactionId");
+      history.replaceState(null, "", opened.href);
+    }
+  }
+
+  // The sign-in to prove, started unless one is being resumed, and its own CSRF token.
+  async #ready(method) {
+    if (!this.#transaction) {
+      const { csrfToken } = await request(this.#env, PLATFORM_CSRF);
+      const started = await request(this.#env, START, { method: "POST", body: { returnPath: this.#returnPath, method }, csrf: csrfToken });
+      this.#transaction = started.transactionId;
+      this.#csrf = null;
+    }
+    if (!this.#csrf) this.#csrf = (await request(this.#env, `/v1/auth/transactions/${this.#transaction}/csrf`)).csrfToken;
+  }
+
+  #post(action, body) {
+    return request(this.#env, `/v1/auth/transactions/${this.#transaction}/${action}`, { method: "POST", body, csrf: this.#csrf });
+  }
+
+  #go(url) {
+    const target = new URL(url, this.#env.location.origin);
+    if (target.origin !== this.#env.location.origin) throw new SignInError(0, "INVALID_DESTINATION", "Invalid sign-in destination.");
+    this.#env.location.assign(target.href);
+  }
+
+  /** Starts a sign-in unless one is being resumed, and emails `email` a six-digit code. */
+  async sendCode(email) {
+    const address = text(email, "email");
+    await this.#ready("email_otp");
+    await this.#post("email-otp/send", { email: address });
+    this.#email = address;
+  }
+
+  /** Emails a new code to the address sendCode was given; MDRN allows one a minute. */
+  async resendCode() {
+    if (!this.#email) throw new TypeError("sendCode first");
+    await this.sendCode(this.#email);
+  }
+
+  /** Verifies the code and finishes the sign-in: the browser goes to the answer's redirectUrl,
+   * unless `navigate` is false; the answer is returned either way. A code already verified (a
+   * second submit, say) is finished through `complete`, as the hosted page does. */
+  async verifyCode(code, { navigate = true } = {}) {
+    const digits = text(code, "code");
+    await this.#ready("email_otp");
+    let result;
+    try {
+      result = await this.#post("email-otp/verify", { code: digits });
+    } catch (error) {
+      try { result = await this.#post("complete", {}); } catch { throw error; }
+    }
+    if (navigate) this.#go(result.redirectUrl);
+    return { redirectUrl: result.redirectUrl };
+  }
+
+  /** Starts a sign-in unless one is being resumed, then sends the browser to Google or GitHub;
+   * the visitor comes back signed in at returnPath, or here with a reason. */
+  async continueWith(provider) {
+    if (!PROVIDERS.includes(provider)) throw new TypeError(`provider must be one of ${PROVIDERS.join(", ")}`);
+    await this.#ready(provider);
+    this.#go(`/v1/auth/transactions/${this.#transaction}/${provider}`);
+  }
+}
+
+/** The sign-in of the page this is called on: it reads `?transactionId=` (a sign-in to resume)
+ * and `?reason=` (why the visitor is back; `reason` and `message` say) from the address and
+ * removes them from it. One per page load. */
+export function signIn(options = {}) {
+  return new SignIn(options);
+}
+
+/** Whether the browser is signed in on this address: `state` authenticated with `user` and
+ * `expiresAt`, or anonymous. */
+export function session(options) {
+  return request(browser(options), SESSION);
+}
+
+/** Ends the browser's session on this address; resolves once it has. */
+export async function signOut(options) {
+  const env = browser(options);
+  const { csrfToken } = await request(env, PLATFORM_CSRF);
+  await request(env, SESSION, { method: "DELETE", csrf: csrfToken });
+}

package/src/fake.d.ts

@@ -0,0 +1,63 @@
+import type { MdrnEnv, Record } from "./index.js";
+
+export interface FakeOptions {
+  /** The origin the product URLs are under; https://app.example by default. */
+  origin?: string;
+  /** Where grant URLs point; the origin by default. */
+  filesOrigin?: string;
+  project?: string;
+  environment?: string;
+  /** The size of an upload part, 16 MiB by default; small in tests to get several parts. */
+  partBytes?: number;
+  tokens?: { database?: string; storage?: string; mail?: string };
+}
+
+export interface LogEntry {
+  method: string;
+  /** Path and query. */
+  path: string;
+  /** authorization, mdrn-project, mdrn-environment, idempotency-key, if-match, content-type
+   * and x-mdrn-grant, when sent. */
+  headers: { [name: string]: string };
+  /** The JSON body of a mutation; `{bytes}` for a part PUT; null otherwise. */
+  body: unknown;
+  status: number;
+}
+
+export interface SentMessage {
+  id: string;
+  recipient: string;
+  subject: string;
+  text: string;
+  html: string | null;
+  attachments: { filename: string; type: string; content: string }[];
+  senderId: string | null;
+  templateId: string | null;
+}
+
+export interface FakeMdrn {
+  /** What MDRN injects into a release, with MDRN_PRODUCTS answered by this fake. */
+  env: MdrnEnv & { MDRN_PRODUCTS: { fetch: typeof fetch } };
+  /** Serves a product request, a grant URL or /v1/auth/me. */
+  fetch: typeof fetch;
+  collections: Map<string, Map<string, Record>>;
+  uploads: Map<string, unknown>;
+  objects: Map<string, unknown>;
+  operations: Map<string, unknown>;
+  /** Mail templates by id; `welcome` exists. */
+  templates: Map<string, { subject: string; text: string; html: string | null }>;
+  /** Every message queued, in order. */
+  sent: SentMessage[];
+  /** Every request served, in order. */
+  log: LogEntry[];
+  /** Makes `id` a signed-in user and gives the two headers MDRN's Proxy adds to their requests. */
+  signIn(id: string, email?: string, token?: string): { "x-mdrn-user-id": string; "x-mdrn-identity-token": string };
+  /** Sends bytes to a part grant's URL as a browser would. */
+  putBytes(grantUrl: string, bytes: Uint8Array | ArrayBuffer): Promise<{ partNumber: number; bytes: number; etag: string }>;
+  /** Fetches a download grant's URL. */
+  getBytes(grantUrl: string): Promise<Uint8Array>;
+  /** Forgets every record, upload, object, message, replay and log entry. */
+  reset(): void;
+}
+
+export function createFakeMdrn(options?: FakeOptions): FakeMdrn;