@nohead/sdk 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,97 @@ Changes to `@nohead/sdk` that you can notice. Versions follow
 releases; a change that could break your code is a major one. Each release's
 section is its GitHub release's notes.
 
+## 0.10.0
+
+- Rich text reads as HTML or Markdown: `richText: "html"` (or `"markdown"`)
+  on the client, or in a request's options, sends the API's `rich_text`
+  query parameter on the methods that return records or drafts, so a rich
+  text field's value in `data` is a string instead of the document. A
+  request's `richText` overrides the client's, and `withOptions` can change
+  it. Writing Markdown already worked: `data` is sent as it is.
+
+## 0.9.0
+
+- **Breaking:** the client no longer reads `NOHEAD_API_URL`: a stray value
+  sent requests, with the API key, to another host. The base URL is
+  `baseUrl`, else `https://api.nohead.io`; pass `baseUrl` to use another
+  API, as in `new Nohead({ baseUrl: process.env.NOHEAD_API_URL })`.
+
+- An `APIError`'s `message` names the status, the error type and the
+  request ID along with the API's message, as in the Python and Ruby SDKs:
+  `422 validation_error: Title is required (request req_…)`, where it was
+  only `Title is required`. The API's own text is `apiMessage`.
+
+- `unwrapWebhook` and `webhooks.unwrap` throw a `WebhookVerificationError`
+  for an empty secret (`""` or `"whsec_"`, as from an unset environment
+  variable), not the platform's `DOMException`.
+
+- `DEFAULT_BASE_URL` is exported: the API's address (`https://api.nohead.io`)
+  that a client uses when `baseUrl` isn't set.
+
+- `timeout` is now the longest an attempt may go without progress: to get
+  the response, then between chunks of its body. A large response that keeps
+  arriving no longer times out; one that stalls still does. An upload's bytes
+  get as long as sending them at 64 KiB/s takes, if that is longer.
+
+- `withOptions({ timeout, maxRetries, headers, onRetry })` copies a client
+  with other settings; the copy shares the key's project lookup. `headers`
+  are added to the client's.
+
+- Redirects are no longer followed, which could send the API key to another
+  host or a write as a GET: a `3xx` throws an `APIError` with `type`
+  `redirect` and the message
+  `301 redirect: The API answered with a redirect to <Location>; check the base URL`.
+  A redirect from storage fails an upload with `UploadError`.
+
+- Headers are matched by name in any case, and each is sent once. A call's
+  `headers` replace the client's, which replace the SDK's own; the headers
+  the request options set (`Idempotency-Key`, `If-Match`,
+  `Nohead-Change-Note`, `Content-Type`) always win. A client header
+  `authorization` was sent along with the SDK's `Authorization`.
+
+- Empty options count as unset: `apiKey`, `baseUrl` and `projectId` of `""`
+  fall back to `NOHEAD_API_KEY` and the defaults, an `idempotencyKey` of
+  `""` gets a generated key, an upload's `filename` and `content_type` of
+  `""` their defaults, and `imageUrl`'s empty options are left out.
+
+- A `baseUrl` that isn't an `http` or `https` URL throws a `NoheadError`
+  when the client is made, not on its first request.
+
+- A path value of `.` or `..` (`records.get("..")`) throws a `NoheadError`,
+  `Invalid record_id: ".."`, before anything is sent: URLs resolve them.
+
+- `ifMatch` that isn't a revision number, or an object with one, throws a
+  `TypeError` before anything is sent, where an object without one sent
+  `If-Match: "undefined"`.
+
+- `NaN` and `Infinity` in a body throw a `TypeError`, where they were sent as
+  `null`.
+
+- A list whose response isn't the API's list (a proxy's page, say) throws a
+  `NoheadError`, `The API's response could not be read (HTTP 200)`, not a
+  `TypeError` or a page without items.
+
+- `Retry-After` is read as a number of seconds (`120`, `1.5`) or an HTTP
+  date, in all three of its forms, in GMT. Anything else (`1e3`, `0x10`,
+  `-1`, an ISO 8601 time) is ignored and the usual backoff applies.
+
+- An error's details that aren't objects are kept, as
+  `{ code: "unknown", message: <the value as text> }`, rather than dropped.
+
+- `assets.upload` sends a stream with `Content-Length: byte_size`, which the
+  upload URL is signed for; storage could refuse it without one. Given a string,
+  it throws a `TypeError`: pass `await fs.openAsBlob(path)` for a file. Its
+  `UploadError` messages name the filename you passed (or `upload`).
+
+- `unwrapWebhook` and `webhooks.unwrap` take an unset `secret` (`undefined`,
+  as from a missing environment variable) and throw `WebhookVerificationError`
+  `The webhook secret is empty`, not a `TypeError`.
+
+- `imageUrl` throws a `TypeError` for an unknown `fit`
+  (`fit must be one of contain, cover, fill`), where it wrote `rs:undefined`
+  into the URL.
+
 ## 0.8.0
 
 - `Asset` has `file_url`, the file as uploaded, which downloads under its

package/README.md

@@ -22,6 +22,7 @@ for await (const post of nohead.records.list("posts", {
 - [Configuration](#configuration)
 - [Records](#records)
 - [Drafts](#drafts)
+- [Rich text](#rich-text)
 - [Pagination](#pagination)
 - [Errors](#errors)
 - [Retries and idempotency](#retries-and-idempotency)
@@ -40,28 +41,40 @@ for await (const post of nohead.records.list("posts", {
 npm install @nohead/sdk
 ```
 
-The package is ESM; Node 22+ can also `require()` it. It runs on Node 22, 24 and 26, Bun, Deno, Cloudflare Workers and other runtimes with `fetch` and Web Crypto. Use it on servers: API keys are secrets.
+The package is ESM; Node 22+ can also `require()` it. It runs on Node 22, 24 and 26, Bun, Deno, Cloudflare Workers and other runtimes with `fetch`, Web Crypto and ES2024. Use it on servers: API keys are secrets.
+
+Until 1.0, any release may break your code: pin a version, and read the changelog's **Breaking** entries before upgrading.
 
 ## Configuration
 
 ```ts
 const nohead = new Nohead({
-  apiKey: process.env.NOHEAD_API_KEY, // default: NOHEAD_API_KEY
-  baseUrl: "https://api.nohead.io", // default: NOHEAD_API_URL, else production
+  apiKey: process.env.NOHEAD_API_KEY, // the default
+  timeout: 10_000,
+  maxRetries: 3,
 })
 ```
 
-| Option       | Default                                        |                                                                                    |
-| ------------ | ---------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `apiKey`     | `NOHEAD_API_KEY`                               | A project API key (`nohead_sk_…`, or `nohead_pk_…` when published-only). Required. |
-| `baseUrl`    | `NOHEAD_API_URL`, else `https://api.nohead.io` |                                                                                    |
-| `projectId`  | the key's project                              | Looked up once with `GET /v1/me` when omitted.                                     |
-| `maxRetries` | `2`                                            | See [retries](#retries-and-idempotency).                                           |
-| `timeout`    | `60000`                                        | Milliseconds per attempt.                                                          |
-| `fetch`      | `globalThis.fetch`                             | For proxies, instrumentation and tests.                                            |
-| `headers`    | `{}`                                           | Added to every request.                                                            |
-| `warnings`   | `true`                                         | Logs deprecation and plan usage warnings, once each.                               |
-| `onRetry`    |                                                | Called before each retry. See [retries](#retries-and-idempotency).                 |
+| Option       | Default                 |                                                                                           |
+| ------------ | ----------------------- | ----------------------------------------------------------------------------------------- |
+| `apiKey`     | `NOHEAD_API_KEY`        | A project API key (`nohead_sk_…`, or `nohead_pk_…` when published-only). Required.        |
+| `baseUrl`    | `https://api.nohead.io` | For a proxy, or a mock server in tests.                                                   |
+| `projectId`  | the key's project       | Looked up once with `GET /v1/me` when omitted.                                            |
+| `maxRetries` | `2`                     | See [retries](#retries-and-idempotency).                                                  |
+| `timeout`    | `60000`                 | Milliseconds an attempt may go without progress. See [retries](#retries-and-idempotency). |
+| `fetch`      | `globalThis.fetch`      | For proxies, instrumentation and tests.                                                   |
+| `headers`    | `{}`                    | Added to every request.                                                                   |
+| `warnings`   | `true`                  | Logs deprecation and plan usage warnings, once each.                                      |
+| `onRetry`    |                         | Called before each retry. See [retries](#retries-and-idempotency).                        |
+| `richText`   | `"document"`            | How rich text reads: `"html"` or `"markdown"`. See [rich text](#rich-text).               |
+
+An empty option counts as unset, as an empty environment variable does: `apiKey: ""` falls back to `NOHEAD_API_KEY`, and `baseUrl: ""` to `https://api.nohead.io`. The base URL comes only from `baseUrl`, never from the environment. A `baseUrl` that isn't an `http` or `https` URL throws.
+
+`withOptions` copies a client with another `timeout`, `maxRetries`, `onRetry` or `richText`, or more `headers` (added to the client's). The copy shares the key's project, so it doesn't look it up again:
+
+```ts
+const patient = nohead.withOptions({ timeout: 120_000, maxRetries: 5 })
+```
 
 API keys belong to a project, so methods like `collections.list()` need no project ID. Collections can be named by ID or slug everywhere.
 
@@ -131,6 +144,24 @@ await nohead.drafts.merge(draft.id) // or drafts.schedule(draft.id, { merge_at }
 - `drafts.discard` deletes one for good.
 - Drafts take the type of their data as records do: `drafts.get<Post>(id)` is a `Nohead.Draft<Post>` (also exported as `NoheadDraft`).
 
+## Rich text
+
+A rich text field takes Markdown or a ProseMirror document, and reads as the document. To read it as HTML or Markdown, set `richText` on the client, or on one request:
+
+```ts
+await nohead.records.update(id, { data: { body: "Hello **world**" } })
+
+const site = nohead.withOptions({ richText: "html" })
+const post = await site.records.get<{ body: string }>(id)
+const html = `<article>${post.data.body}</article>` // safe to put in a page as it is
+
+await nohead.drafts.get(draftId, {}, { richText: "markdown" })
+```
+
+- A rich text field's value is then a string: type it as one in the data's type, as above.
+- It applies to the methods that return records or drafts, and to the records they embed with `expand`; a request's `richText` overrides the client's. History (`revisions`) and webhooks keep documents.
+- A string you write is read as Markdown, so write back Markdown or the document, never the HTML: with `richText: "html"` on the client, writes answer with HTML too.
+
 ## Pagination
 
 List methods return a promise of the first page that you can also loop over:
@@ -190,6 +221,10 @@ Every error is a `NoheadError`. API errors are `APIError`s with `status`, `type`
 | `InternalServerError`     | 500 and other 5xx       |
 | `ServiceUnavailableError` | 503                     |
 
+An API error's `message` names the status, the type and the request ID along with the API's message, so logging it is enough to look the request up: `422 validation_error: Title is required (request req_…)`. The API's own text is `apiMessage`, to show a person.
+
+The client follows no redirects: a `3xx` is an `APIError` (`type` `redirect`) that names where it pointed, which usually means the base URL is wrong.
+
 Other errors: `ConnectionError`, `TimeoutError` (a `ConnectionError`), `AbortError` (your `signal` fired), `UploadError` and `WebhookVerificationError`.
 
 ```ts
@@ -241,6 +276,10 @@ Every method takes request options as its last argument:
 
 Writes that change records or the schema also take `changeNote`, a reason kept with the revision, schema change or migration they make. Record and draft writes take `ifMatch` (see [concurrency](#concurrency)).
 
+Headers are matched by name in any case, and each is sent once: a call's `headers` replace the client's, which replace the SDK's own (`Authorization`, `User-Agent`…). The headers the request options set (`Idempotency-Key`, `If-Match`, `Nohead-Change-Note`, and `Content-Type` for a body) always win.
+
+**Timeouts:** `timeout` is the longest an attempt may go without progress: to connect and get the response, then between chunks of its body. A response that keeps arriving never times out; one that stalls for `timeout` throws `TimeoutError`, and is retried. fetch shows no progress while it sends an upload's bytes, so storage gets as long as sending them at 64 KiB/s takes, when that is longer than `timeout`.
+
 ## Concurrency
 
 Pass the revision you read to make sure nobody changed the record since:
@@ -302,11 +341,11 @@ Thumbnails: an image's `preview_url` fits in 640×640, as WebP.
 2. Sends the bytes straight to storage.
 3. Completes the upload, which checks the file, and returns the `ready` asset.
 
-**Errors:** `UploadError` if storage refuses the bytes; `ValidationError` if the file fails the checks.
+A string is neither a path nor the content: it throws `TypeError` (use `await openAsBlob(path)` from `node:fs`). A stream is sent with `Content-Length: byte_size`, which the upload URL is signed for.
 
-**Resuming:** pass an `idempotencyKey` (`upload(file, {}, { idempotencyKey })`) and running the same upload again resumes it: an asset that is already `ready` comes back without sending the bytes again. Once the upload's URL has expired (its `upload.expires_at`), it throws `UploadError`: start over with a new key.
+**Errors:** `UploadError` whenever the bytes don't reach storage: `Storage refused the upload of cover.jpg (403)` when it refuses them, with its `status`, or `Could not upload cover.jpg: …` when it can't be reached or times out, with that error as the `cause`. `ValidationError` if the file fails the checks.
 
-**Uploading from a browser:** create the upload on your server with `createUpload`, `PUT` the file from the browser, then `complete` it.
+**Resuming:** pass an `idempotencyKey` (`upload(file, {}, { idempotencyKey })`) and running the same upload again resumes it: an asset that is already `ready` comes back without sending the bytes again. Once the upload's URL has expired (its `upload.expires_at`), it throws `UploadError`: start over with a new key.
 
 **Renaming and alt text:** `update` changes an asset's `filename` and `alt` text, the default wherever the asset is used (`expand` returns it with the asset). The file itself never changes.
 
@@ -379,7 +418,7 @@ export async function POST(request: Request) {
     await request.text(),
     request.headers,
     {
-      secret: process.env.NOHEAD_WEBHOOK_SECRET!,
+      secret: process.env.NOHEAD_WEBHOOK_SECRET,
     }
   )
   if (event.type === "record.published" && event.data.record) {
@@ -391,7 +430,7 @@ export async function POST(request: Request) {
 
 With `"max"`, Next.js serves the old version to the next request while it fetches the new one; pass `{ expire: 0 }` instead to drop it at once.
 
-Event types are those of the activity log (`record.published`, `record.restored`, `field.updated`, `asset.purged`, …), and a webhook subscribes to types or wildcards (`record.*`, `*`). Narrowing by `type` types `event.data`, and `unwrap<Post>` types the records and drafts in it. `unwrap` checks the signature and the timestamp (Standard Webhooks), and throws `WebhookVerificationError` if either is off. After `rotateSecret`, requests carry a signature for the old secret and the new one for 24 hours, so switch the receiver's secret within that day (or end it sooner with `webhooks.secrets.retire`). Pass the raw body: parsing and re-serializing JSON changes the bytes.
+Event types are those of the activity log (`record.published`, `record.restored`, `field.updated`, `asset.purged`, …), and a webhook subscribes to types or wildcards (`record.*`, `*`). Narrowing by `type` types `event.data`, and `unwrap<Post>` types the records and drafts in it. `unwrap` checks the signature and the timestamp (Standard Webhooks), and throws `WebhookVerificationError` if either is off, or if the secret is empty or unset (`The webhook secret is empty`). After `rotateSecret`, requests carry a signature for the old secret and the new one for 24 hours, so switch the receiver's secret within that day (or end it sooner with `webhooks.secrets.retire`). Pass the raw body: parsing and re-serializing JSON changes the bytes.
 
 A receiver that never calls the API can use `unwrapWebhook` from `@nohead/sdk/webhooks` without a client. Events can arrive more than once, so deduplicate by the `webhook-id` header.
 
@@ -434,28 +473,37 @@ The SDK covers every operation an API key can call. Organizations, projects, mem
 ```bash
 npm install          # also builds dist/
 npm test             # unit and contract tests
-npm run lint && npm run typecheck && npm run format:check
+npm run lint && npm run typecheck && npm run typecheck:smoke && npm run format:check
 npm run generate     # after updating openapi.json
 npm run samples      # after changing test/calls.ts (the docs' code samples)
 NOHEAD_API_URL=http://localhost:3000 NOHEAD_API_KEY=nohead_sk_… npm run smoke
 ```
 
+Before pushing, also check that the generated code and the samples are current, as CI does:
+
+```bash
+npm run generate && npm run samples && git diff --exit-code src/generated samples.json
+```
+
+The unit tests' mock client (`mockClient` in `test/helpers.ts`) checks every request to the API, and every reply to one, against `openapi.json`, and fails the test on a mismatch; build replies from the contract's examples (`exampleOf`), and mark one that breaks the contract on purpose with `raw()`.
+
 **How the code is organized:**
 
-- `openapi.json` is the API's published contract. `npm run generate` derives two things from it:
+- `openapi.json` is the API's published contract. `npm run generate` derives three things from it:
   - the types, in `src/generated/types.gen.ts` (hey-api)
   - the operation table, in `src/generated/operations.gen.ts`
+  - the schema types the SDK exports, in `src/generated/schemas.gen.ts`
 - The methods in `src/resources` are written by hand.
 - `test/contract.test.ts` calls every public method. It fails when an API-key operation in the contract has no method, when a query parameter is never sent (no method takes it, or no call passes it), or when a request doesn't match its operation (method, path, query parameters and JSON body, against their schemas). Each call gets an example of its operation's response, built from the contract's schema, and must return it.
 
-The smoke test (`smoke/smoke.ts`) runs the core flow against a real API, using the built package. Nohead's own CI runs it on every API contract change.
+The smoke test (`smoke/smoke.ts`) runs the core flow against a real API, using the built package. The Nohead API repository runs it in its end-to-end tests and before every release.
 
 ## Releasing
 
-1. Bump the version in `package.json` and `src/version.ts`.
+1. Bump the version in `package.json` and `src/version.ts`, then `npm install --package-lock-only`, so `package-lock.json` records it.
 2. Add a section for it to `CHANGELOG.md` (`## 1.2.3`), which becomes the release's notes.
 3. Merge to `main`. Its ruleset requires the **CI passed** check, so the commit goes through a pull request or a branch whose CI passed, and force pushes are refused.
-4. Run the **SDK release** workflow in the Nohead API repository. It runs this commit's smoke test against the API and pushes the tag `v1.2.3`. Nobody else can push `v*` tags: a tag ruleset lets only that workflow's deploy key through.
+4. Run the **SDK release** workflow in the Nohead API repository. It runs this commit's smoke test against the API and pushes the tag `v1.2.3`. A tag ruleset lets only deploy keys push `v*` tags.
 5. The tag starts `.github/workflows/release.yml`. A build job checks the tag is on `main` and matches the version and its notes, and packs the package, with no publishing credential. Its publishing job runs in the `release` environment, which only `v*` tags can use, and the registry's trusted publisher accepts only that environment. It stages that package on npm with provenance through trusted publishing (no token), then creates a draft GitHub release.
 6. Approve the staged version with 2FA, on npmjs.com, or with `npm stage list @nohead/sdk` and `npm stage approve <stage-id>`. Only then is it installable. Publish the draft GitHub release.
 

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { PagePromise } from "./api-promise.ts";
-import { type ClientOptions, type RequestOptions } from "./core.ts";
+import { type ClientOptions, type CopyOptions, type RichTextOptions } from "./core.ts";
 import type * as G from "./generated/types.gen.ts";
 import { Assets } from "./resources/assets.ts";
 import { Drafts } from "./resources/drafts.ts";
@@ -31,11 +31,19 @@ export declare class Nohead {
     readonly me: Me;
     readonly health: Health;
     constructor(options?: ClientOptions);
+    /**
+     * A copy of the client with another `timeout`, `maxRetries`, `onRetry` or
+     * `richText`, or more `headers` (added to this client's). It shares the key's project,
+     * so it doesn't look it up again.
+     *
+     *   await nohead.withOptions({ timeout: 5_000 }).records.get(id)
+     */
+    withOptions(options: CopyOptions): Nohead;
     /**
      * Full-text search across the key's project (or some of its
      * collections), most relevant first, through the first 1,000 hits.
      */
-    search<D = RecordData>(query: string, params?: ProjectSearchParams, options?: RequestOptions): PagePromise<NoheadRecord<D>, SearchMeta>;
+    search<D = RecordData>(query: string, params?: ProjectSearchParams, options?: RichTextOptions): PagePromise<NoheadRecord<D>, SearchMeta>;
 }
 /** The main types, also reachable as `Nohead.Record`, `Nohead.Collection`… */
 export declare namespace Nohead {

package/dist/client.js

@@ -1,4 +1,4 @@
-import { Core } from "./core.js";
+import { Core, } from "./core.js";
 import { Assets } from "./resources/assets.js";
 import { Drafts } from "./resources/drafts.js";
 import { AuditEvents, FeatureFlags, Health, Me } from "./resources/other.js";
@@ -28,7 +28,7 @@ export class Nohead {
     health;
     #core;
     constructor(options = {}) {
-        const core = new Core(options);
+        const core = options[COPY_OF] ?? new Core(options);
         this.#core = core;
         this.records = new Records(core);
         this.revisions = new RevisionsById(core);
@@ -43,6 +43,16 @@ export class Nohead {
         this.me = new Me(core);
         this.health = new Health(core);
     }
+    /**
+     * A copy of the client with another `timeout`, `maxRetries`, `onRetry` or
+     * `richText`, or more `headers` (added to this client's). It shares the key's project,
+     * so it doesn't look it up again.
+     *
+     *   await nohead.withOptions({ timeout: 5_000 }).records.get(id)
+     */
+    withOptions(options) {
+        return new Nohead({ [COPY_OF]: this.#core.withOptions(options) });
+    }
     /**
      * Full-text search across the key's project (or some of its
      * collections), most relevant first, through the first 1,000 hits.
@@ -61,3 +71,5 @@ export class Nohead {
         }, options);
     }
 }
+// The core a copy is made with (`withOptions`), out of ClientOptions' sight.
+const COPY_OF = Symbol("copyOf");

package/dist/core.d.ts

@@ -2,6 +2,7 @@ import { APIPromise, PagePromise } from "./api-promise.ts";
 import { NoheadError } from "./errors.ts";
 import { type OperationId, type Operations } from "./generated/operations.gen.ts";
 import type { ListMeta } from "./generated/types.gen.ts";
+import type { RichText } from "./types.ts";
 export declare const DEFAULT_BASE_URL = "https://api.nohead.io";
 export interface ClientOptions {
     /**
@@ -9,13 +10,19 @@ export interface ClientOptions {
      * Defaults to `NOHEAD_API_KEY`.
      */
     apiKey?: string;
-    /** Defaults to `NOHEAD_API_URL`, else `https://api.nohead.io`. */
+    /**
+     * The API's address. Defaults to `https://api.nohead.io`; the environment
+     * isn't read for it, so the key only goes where the code says.
+     */
     baseUrl?: string;
     /** The key's project. Looked up once with `GET /v1/me` when omitted. */
     projectId?: string;
     /** Retries of failed requests (see README, "Retries"). Default 2. */
     maxRetries?: number;
-    /** Milliseconds per attempt. Default 60 000. */
+    /**
+     * Milliseconds an attempt may go without progress (connecting, waiting for
+     * the response, then between chunks of its body). Default 60 000.
+     */
     timeout?: number;
     /** A `fetch` implementation, for proxies, instrumentation or tests. */
     fetch?: typeof fetch;
@@ -25,7 +32,15 @@ export interface ClientOptions {
     warnings?: boolean;
     /** Called before each retry, for example to report it. */
     onRetry?: (retry: RetryEvent) => void;
+    /**
+     * How rich text fields read in the records and drafts returned: as HTML
+     * or Markdown strings, or as the stored document (the API's default). A
+     * request's `richText` overrides it.
+     */
+    richText?: RichText;
 }
+/** What `withOptions` changes in a client's copy. */
+export type CopyOptions = Pick<ClientOptions, "timeout" | "maxRetries" | "headers" | "onRetry" | "richText">;
 /** A retry about to happen (`onRetry`). */
 export interface RetryEvent {
     /** 1 for the first retry of the request, 2 for the second… */
@@ -43,12 +58,21 @@ export interface RequestOptions {
     /** Sent as `Idempotency-Key` on writes. Generated when omitted. */
     idempotencyKey?: string;
     signal?: AbortSignal;
-    /** Milliseconds per attempt, overriding the client's. */
+    /** Milliseconds without progress, overriding the client's `timeout`. */
     timeout?: number;
     /** Retries, overriding the client's. */
     maxRetries?: number;
     headers?: Record<string, string>;
 }
+/** Options of operations that return records or drafts. */
+export interface RichTextOptions extends RequestOptions {
+    /**
+     * How rich text fields read in the records or drafts returned (and in
+     * records they embed with `expand`), overriding the client's `richText`:
+     * `"html"` or `"markdown"` strings, or the stored `"document"`.
+     */
+    richText?: RichText;
+}
 /** Options of writes that change records or the schema. */
 export interface WriteOptions extends RequestOptions {
     /**
@@ -75,15 +99,21 @@ export interface ConditionalWriteOptions extends WriteOptions, ConditionalReques
 type HeadersOf<Op extends OperationId> = Operations[Op]["data"] extends {
     headers?: infer H;
 } ? keyof NonNullable<H> : never;
+/** The query parameters an operation declares. */
+type QueryOf<Op extends OperationId> = Operations[Op]["data"] extends {
+    query?: infer Q;
+} ? keyof NonNullable<Q> : never;
 /**
- * The options an operation takes: `ifMatch` and `changeNote` only where it
- * declares `If-Match` and `Nohead-Change-Note`, so a method can't offer them
- * elsewhere.
+ * The options an operation takes: `ifMatch`, `changeNote` and `richText`
+ * only where it declares `If-Match`, `Nohead-Change-Note` and `rich_text`,
+ * so a method can't offer them elsewhere.
  */
 export type OptionsOf<Op extends OperationId> = RequestOptions & ("If-Match" extends HeadersOf<Op> ? Pick<ConditionalRequestOptions, "ifMatch"> : {
     ifMatch?: never;
 }) & ("Nohead-Change-Note" extends HeadersOf<Op> ? Pick<WriteOptions, "changeNote"> : {
     changeNote?: never;
+}) & ("rich_text" extends QueryOf<Op> ? Pick<RichTextOptions, "richText"> : {
+    richText?: never;
 });
 export interface RequestInput {
     path?: Record<string, string | number | undefined>;
@@ -92,15 +122,24 @@ export interface RequestInput {
 }
 export declare class Core {
     #private;
-    constructor(options: ClientOptions);
+    constructor(options: ClientOptions, project?: {
+        id?: Promise<string>;
+    });
+    /** A copy with other settings, sharing the project lookup. */
+    withOptions(options: CopyOptions): Core;
     /** The API key's project, from `GET /v1/me` the first time. */
     projectId(): Promise<string>;
     request<Op extends OperationId>(operation: Op, input?: RequestInput, options?: OptionsOf<Op>): APIPromise<Operations[Op]["response"]>;
     /** A list operation as pages of `Item`. */
-    paginate<Item, Meta extends ListMeta = ListMeta>(operation: OperationId, input: RequestInput, options?: RequestOptions): PagePromise<Item, Meta>;
-    /** `fetch` with this client's timeout and retries, for presigned URLs. */
+    paginate<Item, Meta extends ListMeta = ListMeta, Op extends OperationId = OperationId>(operation: Op, input: RequestInput, options?: OptionsOf<Op>): PagePromise<Item, Meta>;
+    /**
+     * `fetch` with this client's retries, for an upload's presigned URL. fetch
+     * shows no upload progress, so each attempt may take as long as sending
+     * `byteSize` at 64 KiB/s, if that is longer than the timeout.
+     */
     fetchWithRetries(url: string, init: RequestInit, options: RequestOptions & {
         retry: boolean;
+        byteSize: number;
     }): Promise<Response>;
 }
 /**