@nohead/sdk 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,88 @@ 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

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.
 
@@ -379,7 +398,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 +410,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 +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>;
 }
 /**

package/dist/core.js

@@ -1,16 +1,12 @@
 import { APIPromise, Page, PagePromise, } from "./api-promise.js";
-import { AbortError, ConnectionError, NoheadError, TimeoutError, apiError, retryAfterSeconds, } from "./errors.js";
+import { AbortError, ConnectionError, NoheadError, TimeoutError, apiError, isObject, retryAfterSeconds, } from "./errors.js";
 import { OPERATIONS, } from "./generated/operations.gen.js";
 import { VERSION } from "./version.js";
 export const DEFAULT_BASE_URL = "https://api.nohead.io";
-/**
- * The string with lone surrogates (half an emoji, from cutting a string)
- * replaced by U+FFFD, as `String.prototype.toWellFormed` does, so
- * `encodeURIComponent` can encode it.
- */
-const wellFormed = (text) => text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "\uFFFD");
 const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
 const MAX_RETRY_AFTER_SECONDS = 60;
+// Once per process, not per client: an app that makes a client per request
+// (as on Workers) would otherwise warn on every one.
 const warnedDeprecations = new Set();
 let warnedUsage = false;
 export class Core {
@@ -22,37 +18,51 @@ export class Core {
     #timeout;
     #warnings;
     #onRetry;
-    #projectId;
-    constructor(options) {
-        const env = environment();
-        // Empty environment variables count as unset.
-        const apiKey = options.apiKey ?? (env.NOHEAD_API_KEY || undefined);
+    // The project lookup, shared with the client's copies (`withOptions`).
+    #project;
+    constructor(options, project = {}) {
+        // Empty options and environment variables count as unset.
+        const apiKey = options.apiKey || environment().NOHEAD_API_KEY;
         if (!apiKey) {
             throw new NoheadError("Missing API key: pass `apiKey` or set NOHEAD_API_KEY");
         }
         this.#apiKey = apiKey;
-        this.#baseUrl = withoutTrailingSlashes(options.baseUrl ?? (env.NOHEAD_API_URL || DEFAULT_BASE_URL));
+        this.#baseUrl = baseUrlOf(options.baseUrl || DEFAULT_BASE_URL);
         this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
         this.#headers = options.headers ?? {};
         this.#maxRetries = options.maxRetries ?? 2;
         this.#timeout = options.timeout ?? 60_000;
         this.#warnings = options.warnings ?? true;
         this.#onRetry = options.onRetry;
+        this.#project = project;
         if (options.projectId)
-            this.#projectId = Promise.resolve(options.projectId);
+            project.id ??= Promise.resolve(options.projectId);
+    }
+    /** A copy with other settings, sharing the project lookup. */
+    withOptions(options) {
+        return new Core({
+            apiKey: this.#apiKey,
+            baseUrl: this.#baseUrl,
+            fetch: this.#fetch,
+            headers: { ...this.#headers, ...options.headers },
+            maxRetries: options.maxRetries ?? this.#maxRetries,
+            timeout: options.timeout ?? this.#timeout,
+            warnings: this.#warnings,
+            onRetry: options.onRetry ?? this.#onRetry,
+        }, this.#project);
     }
     /** The API key's project, from `GET /v1/me` the first time. */
     projectId() {
-        this.#projectId ??= this.request("me_get", {}).then((me) => {
+        this.#project.id ??= this.request("me_get", {}).then((me) => {
             if (!me.api_key) {
                 throw new NoheadError("The credentials are not a project API key");
             }
             return me.api_key.project_id;
         }, (error) => {
-            this.#projectId = undefined;
+            this.#project.id = undefined;
             throw error;
         });
-        return this.#projectId;
+        return this.#project.id;
     }
     request(operation, input = {}, options = {}) {
         return new APIPromise(this.#send(operation, input, options));
@@ -63,21 +73,32 @@ export class Core {
             const query = { ...input.query, ...(cursor ? { cursor } : {}) };
             const result = await this.#send(operation, { ...input, query }, options);
             const list = result.data;
+            // A proxy's page, say, rather than the API's list.
+            if (!isObject(list) ||
+                !Array.isArray(list.data) ||
+                !isObject(list.meta)) {
+                throw new NoheadError(`The API's response could not be read (HTTP ${result.response.status})`);
+            }
             const page = new Page(list.data, list.meta, (next) => fetchPage(next).then((r) => r.data));
             return { ...result, data: page };
         };
         const first = input.query?.cursor;
         return new PagePromise(fetchPage(first));
     }
-    /** `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.
+     */
     async fetchWithRetries(url, init, options) {
         const maxRetries = options.retry
             ? (options.maxRetries ?? this.#maxRetries)
             : 0;
+        const timeout = Math.max(options.timeout ?? this.#timeout, (options.byteSize / 65_536) * 1000);
         for (let attempt = 0;; attempt++) {
             let failed;
             try {
-                const { response } = await this.#attempt(url, init, options, false);
+                const { response } = await this.#attempt(url, init, { ...options, timeout }, false);
                 if (!RETRYABLE_STATUSES.has(response.status) || attempt >= maxRetries) {
                     return response;
                 }
@@ -96,33 +117,39 @@ export class Core {
         const { method, path } = OPERATIONS[operation];
         const url = new URL(this.#baseUrl + (await this.#path(path, input.path)));
         appendQuery(url.searchParams, input.query);
-        const headers = {
+        // Each name once, whatever its case: the defaults, then the client's
+        // headers, the call's, and those of the request options, which win.
+        const headers = {};
+        setHeaders(headers, {
             Accept: "application/json",
             Authorization: `Bearer ${this.#apiKey}`,
             "Nohead-Client": `sdk-typescript/${VERSION}`,
             ...USER_AGENT,
-            ...this.#headers,
-        };
+        });
+        setHeaders(headers, this.#headers);
+        setHeaders(headers, options.headers);
+        const own = {};
         if (input.body !== undefined)
-            headers["Content-Type"] = "application/json";
+            own["Content-Type"] = "application/json";
         if (method !== "GET") {
-            headers["Idempotency-Key"] = options.idempotencyKey ?? crypto.randomUUID();
+            own["Idempotency-Key"] = options.idempotencyKey || crypto.randomUUID();
         }
-        if (options.ifMatch !== undefined) {
-            const revision = typeof options.ifMatch === "object"
-                ? options.ifMatch.revision
-                : options.ifMatch;
-            headers["If-Match"] = `"${revision}"`;
+        if (options.ifMatch !== undefined && options.ifMatch !== null) {
+            own["If-Match"] = `"${revisionOf(options.ifMatch)}"`;
         }
         // Percent-encoded UTF-8: header values are bytes, and fetch refuses
-        // anything past Latin-1 (the API decodes it).
+        // anything past Latin-1 (the API decodes it). Lone surrogates (half an
+        // emoji, from cutting a string) become U+FFFD, so encodeURIComponent
+        // can encode them.
         if (options.changeNote)
-            headers["Nohead-Change-Note"] = encodeURIComponent(wellFormed(options.changeNote));
-        Object.assign(headers, options.headers);
+            own["Nohead-Change-Note"] = encodeURIComponent(options.changeNote.toWellFormed());
+        setHeaders(headers, own);
         const init = {
             method,
             headers,
-            body: input.body === undefined ? undefined : JSON.stringify(input.body),
+            body: input.body === undefined
+                ? undefined
+                : JSON.stringify(input.body, finiteNumbers),
         };
         const maxRetries = options.maxRetries ?? this.#maxRetries;
         for (let attempt = 0;; attempt++) {
@@ -154,14 +181,32 @@ export class Core {
         return sleep(delay, signal);
     }
     async #attempt(url, init, options, readBody) {
+        // The timeout is the longest wait for progress, so a response that
+        // keeps arriving never times out: the timer starts again when the
+        // response comes, and with each chunk of its body.
         const timeout = options.timeout ?? this.#timeout;
-        const timer = AbortSignal.timeout(timeout);
+        const timer = new AbortController();
+        let timeoutId;
+        const progress = () => {
+            clearTimeout(timeoutId);
+            timeoutId = setTimeout(() => timer.abort(), timeout);
+        };
         const signal = options.signal
-            ? AbortSignal.any([options.signal, timer])
-            : timer;
+            ? AbortSignal.any([options.signal, timer.signal])
+            : timer.signal;
         try {
-            const response = await this.#fetch(url, { ...init, signal });
-            const body = readBody ? await parseBody(response) : undefined;
+            progress();
+            // Redirects aren't followed: one would send the API key to another
+            // host, or a write as a GET.
+            const response = await this.#fetch(url, {
+                ...init,
+                redirect: "manual",
+                signal,
+            });
+            progress();
+            const body = readBody
+                ? await parseBody(response, signal, progress)
+                : undefined;
             return { response, body };
         }
         catch (error) {
@@ -170,11 +215,14 @@ export class Core {
                     cause: options.signal.reason,
                 });
             }
-            if (timer.aborted) {
+            if (timer.signal.aborted) {
                 throw new TimeoutError(`The request timed out after ${timeout} ms`);
             }
             throw new ConnectionError(`Could not reach ${new URL(url).host}: ${error.message}`, { cause: error });
         }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
     async #path(template, values = {}) {
         let path = template;
@@ -183,7 +231,7 @@ export class Core {
         for (const name of Object.keys(values))
             if (!names.includes(name))
                 throw new TypeError(`${name} is not a path parameter of ${template}`);
-        for (const [, name] of template.matchAll(/\{(\w+)\}/g)) {
+        for (const name of names) {
             let value = values[name];
             if (value === undefined && name === "project_id") {
                 value = await this.projectId();
@@ -191,6 +239,10 @@ export class Core {
             if (value === undefined || value === "") {
                 throw new NoheadError(`Missing ${name}`);
             }
+            // Encoding leaves these as they are, and URLs resolve them.
+            if (value === "." || value === "..") {
+                throw new NoheadError(`Invalid ${name}: "${value}"`);
+            }
             path = path.replace(`{${name}}`, encodeURIComponent(String(value)));
         }
         return path;
@@ -249,8 +301,8 @@ function sleep(seconds, signal) {
         signal?.addEventListener("abort", aborted, { once: true });
     });
 }
-async function parseBody(response) {
-    const text = await response.text();
+async function parseBody(response, signal, progress) {
+    const text = await readText(response, signal, progress);
     if (!text)
         return undefined;
     if (!response.headers.get("content-type")?.includes("json"))
@@ -262,6 +314,31 @@ async function parseBody(response) {
         return text;
     }
 }
+/** The body's text, calling `progress` for each chunk that arrives. */
+async function readText(response, signal, progress) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    // A fetch ends the body when the signal aborts, but not every fetch is
+    // the platform's.
+    const cancel = () => void reader.cancel().catch(() => undefined);
+    signal.addEventListener("abort", cancel, { once: true });
+    const decoder = new TextDecoder();
+    let text = "";
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            signal.throwIfAborted();
+            if (done)
+                return text + decoder.decode();
+            progress();
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    finally {
+        signal.removeEventListener("abort", cancel);
+    }
+}
 /**
  * Query parameters as the API reads them: objects become `key[sub]=…`
  * (`filter[price][lt]=50`), arrays are comma-separated (`expand=author,tags`)
@@ -308,12 +385,48 @@ function runtimeVersion() {
         return `node/${g.process.versions.node}`;
     return undefined;
 }
-/** `url` without trailing slashes; a loop, as a regex backtracks on long runs of them. */
-function withoutTrailingSlashes(url) {
+/** `url` without trailing slashes, if it is an http or https URL. */
+function baseUrlOf(url) {
+    // A loop, as a regex backtracks on long runs of slashes.
     let end = url.length;
     while (end > 0 && url[end - 1] === "/")
         end--;
-    return url.slice(0, end);
+    const base = url.slice(0, end);
+    let protocol;
+    try {
+        protocol = new URL(base).protocol;
+    }
+    catch {
+        // Not a URL at all.
+    }
+    if (protocol !== "http:" && protocol !== "https:") {
+        throw new NoheadError("baseUrl must be an http or https URL");
+    }
+    return base;
+}
+/** Sets each header, replacing one of the same name in any case. */
+function setHeaders(headers, values = {}) {
+    for (const [name, value] of Object.entries(values)) {
+        for (const key of Object.keys(headers))
+            if (key.toLowerCase() === name.toLowerCase())
+                delete headers[key];
+        headers[name] = value;
+    }
+}
+/** `ifMatch`'s revision: a number, or a record's or a draft's. */
+function revisionOf(ifMatch) {
+    const revision = isObject(ifMatch) ? ifMatch.revision : ifMatch;
+    if (!Number.isInteger(revision)) {
+        throw new TypeError("ifMatch takes a revision number, or a record, draft or object with a revision");
+    }
+    return revision;
+}
+// JSON has no NaN or Infinity, which JSON.stringify would send as null.
+function finiteNumbers(key, value) {
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        throw new TypeError(`JSON can't carry ${value}${key ? ` (in ${key})` : ""}`);
+    }
+    return value;
 }
 function environment() {
     const process = globalThis.process;

package/dist/errors.d.ts

@@ -3,7 +3,11 @@ import type { ErrorDetail, ErrorType } from "./generated/types.gen.ts";
 export declare class NoheadError extends Error {
     name: string;
 }
-/** The API answered with an error status. Subclasses follow the error `type`. */
+/**
+ * The API answered with an error status. Subclasses follow the error `type`.
+ * Its `message` names the status, the type and the request's ID along with
+ * the API's message: `422 validation_error: Title is required (request req_…)`.
+ */
 export declare class APIError extends NoheadError {
     name: string;
     /** The HTTP status. */
@@ -13,6 +17,8 @@ export declare class APIError extends NoheadError {
      * none. A type newer than this SDK is kept as its string.
      */
     readonly type: ErrorType | (string & {}) | undefined;
+    /** The API's own message, without the status, type and ID `message` adds. */
+    readonly apiMessage: string;
     /** The request's ID (`req_…`), for support requests and logs. */
     readonly requestId: string | undefined;
     /** Field-level details, e.g. `[{ field: "title", code: "required", … }]`. */
@@ -85,4 +91,10 @@ export declare class WebhookVerificationError extends NoheadError {
 }
 /** The error for a response, by its `type`, or by status when it has none. */
 export declare function apiError(status: number, body: unknown, headers: Headers): APIError;
+/**
+ * `Retry-After` in seconds: a number of seconds (`120`, `1.5`), or an HTTP
+ * date. Anything else (`-1`, `1e3`, `0x10`, an ISO 8601 time) is undefined,
+ * as the Python and Ruby SDKs read it.
+ */
 export declare function retryAfterSeconds(headers: Headers): number | undefined;
+export declare const isObject: (value: unknown) => value is Record<string, unknown>;

package/dist/errors.js

@@ -2,7 +2,11 @@
 export class NoheadError extends Error {
     name = "NoheadError";
 }
-/** The API answered with an error status. Subclasses follow the error `type`. */
+/**
+ * The API answered with an error status. Subclasses follow the error `type`.
+ * Its `message` names the status, the type and the request's ID along with
+ * the API's message: `422 validation_error: Title is required (request req_…)`.
+ */
 export class APIError extends NoheadError {
     name = "APIError";
     /** The HTTP status. */
@@ -12,6 +16,8 @@ export class APIError extends NoheadError {
      * none. A type newer than this SDK is kept as its string.
      */
     type;
+    /** The API's own message, without the status, type and ID `message` adds. */
+    apiMessage;
     /** The request's ID (`req_…`), for support requests and logs. */
     requestId;
     /** Field-level details, e.g. `[{ field: "title", code: "required", … }]`. */
@@ -20,12 +26,17 @@ export class APIError extends NoheadError {
     /** The parsed response body, or its text when it was not JSON. */
     body;
     constructor(status, body, headers) {
-        const error = errorEnvelope(body);
-        super(error?.message ?? `Request failed with status ${status}`);
+        // Below 400 (and not 2xx) is a redirect, which the SDK doesn't follow:
+        // `0` is a browser's, which shows nothing of it.
+        const error = status < 400 ? redirect(headers) : errorEnvelope(body);
+        const requestId = error?.request_id ?? headers.get("x-request-id") ?? undefined;
+        const apiMessage = error?.message || `Request failed with status ${status}`;
+        super(`${status} ${error?.type || "error"}: ${apiMessage}` +
+            (requestId ? ` (request ${requestId})` : ""));
         this.status = status;
+        this.apiMessage = apiMessage;
         this.type = error?.type;
-        this.requestId =
-            error?.request_id ?? headers.get("x-request-id") ?? undefined;
+        this.requestId = requestId;
         this.details = error?.details ?? [];
         this.headers = headers;
         this.body = body;
@@ -118,6 +129,8 @@ const CLASSES = new Map(Object.entries({
 }));
 /** The error for a response, by its `type`, or by status when it has none. */
 export function apiError(status, body, headers) {
+    if (status < 400)
+        return new APIError(status, body, headers);
     const type = errorEnvelope(body)?.type;
     const Class = (type && CLASSES.get(type)) ||
         (status === 503
@@ -127,18 +140,49 @@ export function apiError(status, body, headers) {
                 : APIError);
     return new Class(status, body, headers);
 }
+/**
+ * `Retry-After` in seconds: a number of seconds (`120`, `1.5`), or an HTTP
+ * date. Anything else (`-1`, `1e3`, `0x10`, an ISO 8601 time) is undefined,
+ * as the Python and Ruby SDKs read it.
+ */
 export function retryAfterSeconds(headers) {
-    const value = headers.get("retry-after");
+    const value = headers.get("retry-after")?.trim();
     if (!value)
         return undefined;
-    const seconds = Number(value);
-    if (Number.isFinite(seconds))
-        return Math.max(0, seconds);
-    const date = Date.parse(value);
-    return Number.isNaN(date)
+    if (/^\d+(\.\d+)?$/.test(value))
+        return Number(value);
+    const date = httpDate(value);
+    return date === undefined
         ? undefined
         : Math.max(0, (date - Date.now()) / 1000);
 }
+// The three forms of an HTTP date (RFC 9110), all in GMT. Not Date.parse,
+// which takes more than these, and asctime's in the local time zone.
+const HTTP_DATES = [
+    // IMF-fixdate: Sun, 06 Nov 1994 08:49:37 GMT
+    /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (?<day>\d{2}) (?<month>\w{3}) (?<year>\d{4}) (?<time>\d{2}:\d{2}:\d{2}) GMT$/,
+    // RFC 850: Sunday, 06-Nov-94 08:49:37 GMT
+    /^(?:Mon|Tues|Wednes|Thurs|Fri|Satur|Sun)day, (?<day>\d{2})-(?<month>\w{3})-(?<year>\d{2}) (?<time>\d{2}:\d{2}:\d{2}) GMT$/,
+    // asctime: Sun Nov  6 08:49:37 1994
+    /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (?<month>\w{3}) (?<day>[ \d]\d) (?<time>\d{2}:\d{2}:\d{2}) (?<year>\d{4})$/,
+];
+const MONTHS = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
+/** An HTTP date in milliseconds, or undefined if `value` isn't one. */
+function httpDate(value) {
+    const date = HTTP_DATES.map((pattern) => pattern.exec(value)?.groups).find(Boolean);
+    const month = MONTHS.indexOf(date?.month ?? "");
+    if (!date || month < 0)
+        return undefined;
+    let year = Number(date.year);
+    // RFC 850's two digits: the latest such year not over 50 years ahead.
+    if (date.year.length === 2) {
+        year += 2000;
+        if (year > new Date().getUTCFullYear() + 50)
+            year -= 100;
+    }
+    const [hours, minutes, seconds] = date.time.split(":").map(Number);
+    return Date.UTC(year, month, Number(date.day), hours, minutes, seconds);
+}
 // The error envelope's fields that have the right type: a proxy or gateway
 // in front of the API may answer with any JSON.
 function errorEnvelope(body) {
@@ -149,10 +193,24 @@ function errorEnvelope(body) {
         type: typeof type === "string" ? type : undefined,
         message: typeof message === "string" ? message : undefined,
         request_id: typeof request_id === "string" ? request_id : undefined,
-        // Only objects: currentRevision reads each detail's fields.
-        details: Array.isArray(details)
-            ? details.filter(isObject)
-            : undefined,
+        details: Array.isArray(details) ? details.map(errorDetail) : undefined,
+    };
+}
+// A detail that isn't an object is kept as its text, so currentRevision can
+// read every detail's fields.
+function errorDetail(detail) {
+    if (isObject(detail) && !Array.isArray(detail))
+        return detail;
+    const message = typeof detail === "string" ? detail : JSON.stringify(detail);
+    return { code: "unknown", message: String(message) };
+}
+// A redirect's error: following one would send the API key elsewhere, or a
+// write as a GET.
+function redirect(headers) {
+    const location = headers.get("location");
+    return {
+        type: "redirect",
+        message: `The API answered with a redirect${location ? ` to ${location}` : ""}; check the base URL`,
     };
 }
-const isObject = (value) => typeof value === "object" && value !== null;
+export const isObject = (value) => typeof value === "object" && value !== null;

package/dist/generated/types.gen.d.ts

@@ -1,5 +1,5 @@
 export type ClientOptions = {
-    baseUrl: 'https://api.nohead.io' | 'http://localhost:3000' | (string & {});
+    baseUrl: 'https://api.nohead.io' | (string & {});
 };
 export type Webhooks = WebhookEventWebhookRequest;
 export type RequestId = string;
@@ -1129,7 +1129,7 @@ export type Principal = {
         email: string;
         name: string | null;
         /**
-         * Nohead staff (internal tooling access).
+         * Whether the user is Nohead staff.
          */
         staff: boolean;
     };
@@ -1550,7 +1550,10 @@ export type AssetProperties = {
     /**
      * The URL that plays a ready video or audio file inline, for
      * `<video>` and `<audio>` (with range requests, so players can seek),
-     * deleted ones included until they are purged; null for other types.
+     * deleted ones included until they are purged: MP4, QuickTime, M4A,
+     * 3GP, WebM, Matroska, MP3, AAC, FLAC, WAV and Ogg (whose content is
+     * checked when the upload completes). Null for other types, which
+     * `file_url` downloads.
      * Open, never expiring and cached on a CDN, like `file_url`.
      *
      */
@@ -1619,7 +1622,7 @@ export type AssetUploadTarget = {
     expires_at: Timestamp;
 };
 /**
- * What a project API key may do. `records:write` also publishes, unpublishes and schedules records (the `records:publish` permission). `webhooks:read` includes delivery payloads and `webhooks:write` can subscribe an endpoint to every event, so both give access to the record, schema and asset data in events, unpublished records included; published-only keys cannot have them.
+ * What a project API key may do. `records:write` also publishes, unpublishes and schedules records. `webhooks:read` includes delivery payloads and `webhooks:write` can subscribe an endpoint to every event, so both give access to the record, schema and asset data in events, unpublished records included; published-only keys cannot have them.
  */
 export type ApiKeyScope = 'records:read' | 'records:write' | 'schema:read' | 'schema:write' | 'assets:read' | 'assets:write' | 'search:read' | 'webhooks:read' | 'webhooks:write' | 'audit:read';
 /**

package/dist/images.js

@@ -16,8 +16,13 @@ export function imageUrl(image, options = {}) {
     const at = base.indexOf("/plain/");
     if (at < 0)
         throw new TypeError(`Not a Nohead image URL: ${base}`);
-    const { width, height, fit = "contain", format, quality, dpr, gravity, } = options;
-    for (const option of [gravity, ...(options.options ?? [])])
+    // Empty options count as unset.
+    const { width, height, format, quality, dpr, gravity } = options;
+    const fit = options.fit || "contain";
+    if (!Object.hasOwn(FITS, fit))
+        throw new TypeError(`fit must be one of ${Object.keys(FITS).join(", ")}`);
+    const others = (options.options ?? []).filter(Boolean);
+    for (const option of [gravity, ...others])
         if (option && /[/@?#]/.test(option))
             throw new TypeError(`Not an imgproxy option: ${option}`);
     const segments = [];
@@ -29,7 +34,7 @@ export function imageUrl(image, options = {}) {
         segments.push(`dpr:${dpr}`);
     if (quality)
         segments.push(`q:${quality}`);
-    segments.push(...(options.options ?? []));
+    segments.push(...others);
     // The source comes last; a format replaces any the URL already names.
     let source = base.slice(at);
     if (format)

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Nohead } from "./client.ts";
 export { APIPromise, Page, PagePromise, type APIResponse, } from "./api-promise.ts";
-export type { ClientOptions, ConditionalRequestOptions, ConditionalWriteOptions, RequestOptions, RetryEvent, WriteOptions, } from "./core.ts";
+export { DEFAULT_BASE_URL, type ClientOptions, type ConditionalRequestOptions, type ConditionalWriteOptions, type CopyOptions, type RequestOptions, type RetryEvent, type WriteOptions, } from "./core.ts";
 export { APIError, AbortError, AuthenticationError, AuthorizationError, ConflictError, ConnectionError, InternalServerError, InvalidRequestError, NoheadError, NotFoundError, PlanLimitExceededError, PreconditionFailedError, RateLimitError, ServiceUnavailableError, TimeoutError, UploadError, ValidationError, WebhookVerificationError, } from "./errors.ts";
 export type { Uploadable, UploadParams } from "./resources/assets.ts";
 export type * from "./types.ts";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { Nohead } from "./client.js";
 export { APIPromise, Page, PagePromise, } from "./api-promise.js";
+export { DEFAULT_BASE_URL, } from "./core.js";
 export { APIError, AbortError, AuthenticationError, AuthorizationError, ConflictError, ConnectionError, InternalServerError, InvalidRequestError, NoheadError, NotFoundError, PlanLimitExceededError, PreconditionFailedError, RateLimitError, ServiceUnavailableError, TimeoutError, UploadError, ValidationError, WebhookVerificationError, } from "./errors.js";
 export { unwrapWebhook, } from "./webhooks.js";
 export { VERSION } from "./version.js";

package/dist/resources/assets.d.ts

@@ -8,11 +8,15 @@ export type Uploadable = Blob | ArrayBuffer | Uint8Array | ReadableStream;
 export interface UploadParams {
     /** Defaults to a `File`'s name, else `upload`. */
     filename?: string;
-    /** Defaults to the `Blob`'s type, else `application/octet-stream`. */
+    /**
+     * Defaults to the `Blob`'s type, else the filename's extension's for
+     * common files, else `application/octet-stream`.
+     */
     content_type?: string;
     /** Required for a `ReadableStream`; known for everything else. */
     byte_size?: number;
 }
+/** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 export declare class Assets extends Resource {
     /**
      * Uploads a file and returns the `ready` asset: creates the upload, sends

package/dist/resources/assets.js

@@ -1,6 +1,5 @@
 import { AbortError, UploadError } from "../errors.js";
 import { listQuery, Resource } from "./resource.js";
-/** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 /** Common files' types by extension, as the other SDKs guess them. */
 const CONTENT_TYPES = {
     avif: "image/avif",
@@ -26,6 +25,7 @@ function contentTypeOf(filename) {
         ? CONTENT_TYPES[filename.slice(dot + 1).toLowerCase()]
         : undefined;
 }
+/** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 export class Assets extends Resource {
     /**
      * Uploads a file and returns the `ready` asset: creates the upload, sends
@@ -45,23 +45,28 @@ export class Assets extends Resource {
      * extension's for common files.
      */
     async upload(file, params = {}, options) {
+        // Never a path: the Python and Ruby SDKs take one, so it would be easy
+        // to send its text instead.
+        if (typeof file === "string") {
+            throw new TypeError("upload takes a Blob, File, ArrayBuffer, Uint8Array or ReadableStream; to upload a file from disk, pass await fs.openAsBlob(path)");
+        }
         const byteSize = params.byte_size ?? sizeOf(file);
         if (byteSize === undefined) {
             throw new UploadError("Uploading a stream needs `byte_size`");
         }
-        const filename = params.filename ??
-            (typeof File !== "undefined" && file instanceof File
-                ? file.name
-                : "upload");
+        // Empty ones count as unset.
+        const filename = params.filename ||
+            (typeof File !== "undefined" && file instanceof File && file.name) ||
+            "upload";
         const { upload, ...asset } = await this.createUpload({
             filename,
             // The Blob's own type, or one the filename's extension implies (a
             // Blob from Node's openAsBlob has none), as the Python and Ruby
             // SDKs do.
-            content_type: params.content_type ??
-                ((file instanceof Blob && file.type) ||
-                    contentTypeOf(filename) ||
-                    "application/octet-stream"),
+            content_type: params.content_type ||
+                (file instanceof Blob && file.type) ||
+                contentTypeOf(filename) ||
+                "application/octet-stream",
             byte_size: byteSize,
         }, options);
         // A replayed start returns the first run's asset, which may be done.
@@ -74,24 +79,28 @@ export class Assets extends Resource {
                 return current;
             // The key replays the first run's upload URL, which expires sooner.
             if (Date.parse(upload.expires_at) <= Date.now()) {
-                throw new UploadError(`The upload of ${asset.filename} expired: start it again with a new idempotencyKey`);
+                throw new UploadError(`The upload of ${filename} expired: start it again with a new idempotencyKey`);
             }
         }
         const stream = file instanceof ReadableStream;
         const response = await this.core
             .fetchWithRetries(upload.url, {
             method: upload.method,
-            headers: upload.headers,
+            // The URL is signed for this size; fetch would send a stream
+            // in chunks, without one.
+            headers: stream
+                ? { ...upload.headers, "Content-Length": String(byteSize) }
+                : upload.headers,
             body: file,
             ...(stream ? { duplex: "half" } : {}),
-        }, { ...options, retry: !stream })
+        }, { ...options, retry: !stream, byteSize })
             .catch((error) => {
             if (error instanceof AbortError)
                 throw error;
-            throw new UploadError(`Could not upload ${asset.filename}: ${error.message}`, undefined, { cause: error });
+            throw new UploadError(`Could not upload ${filename}: ${error.message}`, undefined, { cause: error });
         });
         if (!response.ok) {
-            throw new UploadError(`Storage refused the upload of ${asset.filename} (${response.status})`, response.status);
+            throw new UploadError(`Storage refused the upload of ${filename} (${response.status})`, response.status);
         }
         // The key belongs to the start: the API refuses one key on two requests.
         return this.complete(asset.id, { ...options, idempotencyKey: undefined });

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.8.0";
+export declare const VERSION = "0.9.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.8.0";
+export const VERSION = "0.9.0";

package/dist/webhooks.d.ts

@@ -49,8 +49,9 @@ export interface UnwrapOptions {
     /**
      * The webhook's signing secret (`whsec_…`). While a rotation overlaps,
      * requests carry a signature for each secret, so either one verifies.
+     * An unset one (as from a missing environment variable) throws.
      */
-    secret: string;
+    secret: string | undefined;
     /** Seconds a timestamp may be off from now. Default 300. */
     tolerance?: number;
 }

package/dist/webhooks.js

@@ -24,7 +24,11 @@ export async function unwrapWebhook(body, headers, { secret, tolerance = 300 })
         throw new WebhookVerificationError("The webhook timestamp is too far from the current time");
     }
     const text = typeof body === "string" ? body : new TextDecoder().decode(body);
-    const key = await crypto.subtle.importKey("raw", decodeBase64(secret.replace(/^whsec_/, ""), "secret"), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+    const keyBytes = decodeBase64((secret ?? "").replace(/^whsec_/, ""), "secret");
+    if (keyBytes.length === 0) {
+        throw new WebhookVerificationError("The webhook secret is empty");
+    }
+    const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
     const signed = new TextEncoder().encode(`${id}.${timestamp}.${text}`);
     for (const entry of signatures.split(" ")) {
         const [version, signature] = entry.split(",", 2);
@@ -63,8 +67,5 @@ function decodeBase64(value, what) {
     catch {
         throw new WebhookVerificationError(`The webhook ${what} is not base64`);
     }
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++)
-        bytes[i] = binary.charCodeAt(i);
-    return bytes;
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",
@@ -61,6 +61,7 @@
     "eslint": "^10.12.0",
     "globals": "^17.13.0",
     "prettier": "^3.9.9",
+    "standardwebhooks": "^1.1.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.71.0",
     "vitest": "^5.0.3"