@nohead/sdk 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,102 @@ 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.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
+  filename, and for video and audio `media_url`, which plays it inline (in
+  `<video>` and `<audio>`, with range requests). Both are open, never expire
+  and are cached on a CDN, like `image_url`.
+
+- `assets.downloadUrl` is removed, with the API's
+  `GET /v1/assets/{asset_id}/download-url` and its 2-minute links: use the
+  asset's `file_url`.
+
+- An upload larger than the plan allows (10 MB a file on Free, 100 MB on paid
+  plans) is refused with a `PlanLimitExceededError` when it starts.
+
 ## 0.7.0
 
 - `assets.list({ q, kind })`: `q` finds assets whose filename or alt text

package/README.md

@@ -40,28 +40,39 @@ 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).                        |
+
+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` or `onRetry`, 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.
 
@@ -190,6 +201,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 +256,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 +321,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.
 
@@ -372,22 +391,26 @@ Verify a webhook request, then use its event:
 
 ```ts
 // e.g. a Next.js route handler
+import { revalidateTag } from "next/cache"
+
 export async function POST(request: Request) {
   const event = await nohead.webhooks.unwrap(
     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) {
-    revalidateTag(event.data.record.collection)
+    revalidateTag(event.data.record.collection, "max")
   }
   return new Response(null, { status: 204 })
 }
 ```
 
-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.
+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, 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.
 
@@ -414,7 +437,7 @@ response.headers.get("RateLimit-Remaining")
 | `collections.searchIndex`   | `get`, `rebuild`                                                                                                                                                                                        |
 | `fields`                    | `list`, `get`, `create`, `update`, `delete`, `restore`, `order`, `reorder`, `removeAlias`                                                                                                               |
 | `migrations`                | `create`, `list`, `get`, `cancel`                                                                                                                                                                       |
-| `assets`                    | `upload`, `createUpload`, `complete`, `list`, `get`, `update`, `delete`, `restore`, `purge`, `usage`, `downloadUrl`                                                                                     |
+| `assets`                    | `upload`, `createUpload`, `complete`, `list`, `get`, `update`, `delete`, `restore`, `purge`, `usage`                                                                                                    |
 | `webhooks`                  | `list`, `get`, `create`, `update`, `delete`, `restore`, `rotateSecret`, `test`, `unwrap`                                                                                                                |
 | `webhooks.secrets`          | `list`, `retire`                                                                                                                                                                                        |
 | `webhooks.deliveries`       | `list`, `get`, `retry`                                                                                                                                                                                  |
@@ -430,28 +453,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 RequestOptions } 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,6 +31,14 @@ export declare class Nohead {
     readonly me: Me;
     readonly health: Health;
     constructor(options?: ClientOptions);
+    /**
+     * A copy of the client with another `timeout`, `maxRetries` or `onRetry`,
+     * 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.

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` or `onRetry`,
+     * 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

@@ -9,13 +9,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;
@@ -26,6 +32,8 @@ export interface ClientOptions {
     /** Called before each retry, for example to report it. */
     onRetry?: (retry: RetryEvent) => void;
 }
+/** What `withOptions` changes in a client's copy. */
+export type CopyOptions = Pick<ClientOptions, "timeout" | "maxRetries" | "headers" | "onRetry">;
 /** A retry about to happen (`onRetry`). */
 export interface RetryEvent {
     /** 1 for the first retry of the request, 2 for the second… */
@@ -43,7 +51,7 @@ 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;
@@ -92,15 +100,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. */
+    /**
+     * `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>;
 }
 /**