@nohead/sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,118 @@ 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.3.0
+
+- **Breaking:** 0.1.0 and 0.2.0 no longer work with the API: its paths and
+  shapes changed (below), so upgrading is required.
+- `changeNote` is sent percent-encoded (UTF-8), so change notes work in any
+  language: a note outside ASCII used to fail the request.
+- Drafts: changes to a record that wait until they are merged into it, now
+  or at a set time. `drafts.create`, `list`, `get` (with `expand`, for
+  previews), `update`, `discard`, `merge`, `schedule` and `unschedule`, and
+  `records.drafts`. Drafts take the type of their data as records do
+  (`drafts.get<Post>(id)` is a `NoheadDraft<Post>`, also `Nohead.Draft`),
+  and `drafts.create(record)` needs no params to start from the record's
+  values. `records.publish` on a live record with a pending draft is a
+  `ConflictError` (`draft_pending`). Webhook events gain `DraftEvent`
+  (`draft.*`), and a merge's `record.updated` carries its `draft_id`.
+- **Breaking:** request options follow what each operation takes, by type:
+  `changeNote` only on writes that change records or the schema
+  (`WriteOptions`: record writes, `drafts.merge`, collection and field
+  writes), not on assets, webhooks, schedules, search index rebuilds or
+  other draft writes, which never kept a note. `ifMatch` on
+  `records.update`, `delete`, `restore` (new), `publish`, `unpublish` and
+  `revisions.revert` (`ConditionalWriteOptions`) and on `drafts.update`,
+  `discard` and `merge`. `ConditionalRequestOptions` no longer includes
+  `changeNote`.
+- **Breaking:** `records.schedule` sets the whole schedule: a time left out
+  is cleared (it used to keep its value), and `{}` clears both, as
+  `unschedule` does.
+- `fields.get()`: one field by ID.
+- **Breaking:** the types for what only the web app can do (organizations,
+  projects, members and invitations, billing, API keys, usage, account
+  changes and redaction, such as `Organization`, `Project`, `ApiKey`, `Billing`) are gone. Those
+  operations need a signed-in person, so an API key could never call them,
+  and the API reference no longer lists them.
+- **Breaking:** the API is resource-oriented. Method names stay; what they
+  return and take follows it:
+  - Records have no `status`, `schedule` or `deleted`: a record is published
+    when `published_at` is set, and has `deleted_at` and `purge_after`.
+    Filter with `{ published_at: { exists: true } }`. `records.get` returns
+    deleted records too (no `include_deleted`).
+  - `records.schedule` and `unschedule` return the schedule, and
+    `records.getSchedule`, `records.publication` and
+    `records.scheduledChanges` are new. `records.bulk` returns a
+    `record_batch`: `BulkRecordsResult` and `BulkRecordsRequest` are now
+    `RecordBatch` and `RecordBatchRequest`.
+  - Project search takes `filter: { published_at: { exists: true } }`
+    instead of `filter: { status }`.
+  - Collections, fields, assets and webhooks have `deleted_at` and
+    `purge_after` instead of `deleted`, and migrations
+    `cancel_requested_at`.
+  - `assets.createUpload` returns the asset with its `upload`
+    (`AssetWithUpload`, was `AssetUpload`).
+  - `fields.reorder` returns the `field_order`; `fields.order` reads it.
+  - Webhook event types are those of the activity log (`record.restored`,
+    `field.updated`, …, and wildcards such as `record.*`), and event
+    payloads carry `actor` and `via`. `SchemaChangedEvent`
+    (`schema.changed`) is now `SchemaEvent` (`collection.*` and `field.*`,
+    with the `collection`, its `object`, the `schema_change` and, for a
+    field, its `field_id`), and `FieldAliasRemovedEvent` is new
+    (`field.alias_removed`). There is no `record.imported`. The event data
+    types are exported too (`RecordEventData`, `DraftEventData`,
+    `AssetEventData`, `SchemaEventData`, `FieldAliasEventData`,
+    `WebhookTestEventData`).
+  - `webhooks.rotateSecret` returns a `webhook_secret`
+    (`WebhookSecretWithValue`, was `WebhookWithSecret`); the old secret
+    signs for 24 hours more. `webhooks.secrets.list`,
+    `webhooks.secrets.retire`, `webhooks.restore` and
+    `webhooks.list({ deleted })` are new. `webhooks.deliveries.retry`
+    calls the API's new path.
+  - Audit events are `object: "event"`, and name what happened in `type`
+    (was `action`). `auditEvents.list` filters by `type`, `resource_type`
+    (one, or a list of them), `resource_id`, `actor_type`, `actor_id` and
+    `created_at: { gte, gt, lte, lt }` (was `action`, `since` and
+    `until`); an unknown filter is an `InvalidRequestError`. Field events
+    have the resource type `field`.
+  - `records.revisions.list` filters `created_at` by range (was `since`
+    and `until`), and revisions' `operation` can be `merge` (not `import`).
+  - `ScheduledChange` has no `last_error`, and `SchemaChange` no `status`.
+    `ChangeVia` is gone: `Via` names the client a change came through.
+  - Exported types for the params that were inline:
+    `ScheduledChangeListParams`, `DraftScheduleParams`,
+    `FieldReorderParams`, and the filters `AuditEventFilter`,
+    `RevisionFilter` and `TimeRange`.
+- **Breaking:** the `datetime` field type is now `date`. A plain date field holds
+  `YYYY-MM-DD`; with `include_time` it holds a moment, written in the field's
+  `time_zone` when it has one. Field migrations take `time_zone`, the zone
+  whose day each moment falls on when the time is removed.
+- Boolean fields can't be `required`: a boolean is true or false, and no
+  value reads as false.
+- Text fields take a `format` (`email`, `url`, `slug`; slugs are always
+  unique) and text and integer fields `unique`; a taken value's error detail
+  has the `record_id` that has it (`code: "taken"`).
+- Filters take operators: `{ price: { lt: 50 } }`, with `eq`, `ne`, `gt`,
+  `gte`, `lt`, `lte`, `in` (a list) and `exists`, and record lists sort by a
+  field's value. Commas and backslashes in list values are escaped, so a
+  value can hold a comma.
+- Date filters take `today`, and dates with a time `now`.
+- `assets.usage()`: where an asset is used, as counts of the records that use
+  it (and of those, the published ones) and the 10 most recently updated with
+  the fields that use it. Needs the `records:read` scope too.
+- `assets.purge()`: permanently deletes a deleted asset now, instead of at
+  its `purge_after`, and frees its storage.
+- An error reads only the fields of the API's error envelope that have the
+  right type, so JSON from a proxy or gateway that merely looks like one no
+  longer gives it a non-string `message`, `type` or `requestId`.
+- `APIError.type` is typed as the known error types or any string: the API
+  can add types, and one newer than the SDK is kept as is. Code that checks
+  it exhaustively needs a default branch.
+- An error whose type names a built-in property (`constructor`,
+  `toString`) is an `APIError`; it used to throw a value that wasn't one.
+- An error's `details` keep only entries that are objects, so
+  `currentRevision` no longer throws on a `null` one.
+
 ## 0.2.0
 
 - `onRetry` client option: called before each retry with the attempt, the
@@ -12,7 +124,8 @@ section is its GitHub release's notes.
 - `assets.upload()` with an `idempotencyKey` no longer fails when it
   completes the upload: the key only starts it. Running the same upload again
   resumes it, and returns an asset that is already `ready` without sending the
-  bytes again.
+  bytes again; once the upload's URL has expired it throws `UploadError`
+  (start over with a new key).
 - Types follow the API's current contract. They add types only for
   operations an API key can't call, so no method changed.
 

package/README.md

@@ -8,7 +8,7 @@ import { Nohead } from "@nohead/sdk"
 const nohead = new Nohead() // reads NOHEAD_API_KEY
 
 for await (const post of nohead.records.list("posts", {
-  filter: { status: "published" },
+  filter: { published_at: { exists: true } },
 })) {
   console.log(post.data.title)
 }
@@ -21,6 +21,7 @@ for await (const post of nohead.records.list("posts", {
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Records](#records)
+- [Drafts](#drafts)
 - [Pagination](#pagination)
 - [Errors](#errors)
 - [Retries and idempotency](#retries-and-idempotency)
@@ -67,16 +68,19 @@ API keys belong to a project, so methods like `collections.list()` need no proje
 ## Records
 
 ```ts
-const draft = await nohead.records.create("posts", {
+const created = await nohead.records.create("posts", {
   data: { title: "Hello", author: "rec_01J9…" },
 })
-const post = await nohead.records.get(draft.id, { expand: ["author"] })
+const post = await nohead.records.get(created.id, { expand: ["author"] })
 await nohead.records.update(post.id, { data: { title: "Hello again" } })
 await nohead.records.publish(post.id)
+await nohead.records.publication(post.id) // since when, by whom, which revision
 await nohead.records.schedule(post.id, { unpublish_at: new Date("2027-01-01") })
 await nohead.records.delete(post.id) // soft delete; records.restore() undoes it
 ```
 
+`schedule` sets the whole schedule: a time left out is cleared, so `{ unpublish_at }` alone drops a pending publish.
+
 Methods return the resource and throw on failure. Field names stay as the API sends them (`published_at`, `data`), so the API reference applies as-is.
 
 **Typed data.** Describe a collection's fields and pass the type:
@@ -95,6 +99,29 @@ The type is a promise you make; nothing is checked at runtime. The record type i
 
 **More:** `count`, `bulk` (up to 100 records at once), `diff`, `revisions.list`, `revisions.get` and `revisions.revert` (with `{ dry_run: true }` for a preview).
 
+## Drafts
+
+A draft holds changes to a record until they are merged, now or at a set time, while the record keeps its current content: changes to review before they go live, or changes due later.
+
+```ts
+const draft = await nohead.drafts.create(post.id, {
+  data: { title: "Hello, revised" },
+})
+await nohead.drafts.update(
+  draft.id,
+  { data: { summary: "…" } },
+  { ifMatch: draft }
+)
+const preview = await nohead.drafts.get(draft.id, { expand: ["author"] }) // data as it would read
+await nohead.drafts.merge(draft.id) // or drafts.schedule(draft.id, { merge_at })
+```
+
+- A record has at most one draft; starting a second is a `ConflictError` (detail code `draft_exists`, with its `draft_id`).
+- A merge changes content only: a live record stays live, an unpublished one unpublished. Publishing a live record with a pending draft is a `ConflictError` (`draft_pending`).
+- `records.drafts(id)` lists a record's draft, and `drafts.list(collection, { record_id })` a collection's (`record_id` takes up to 100 IDs).
+- `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`).
+
 ## Pagination
 
 List methods return a promise of the first page that you can also loop over:
@@ -113,14 +140,27 @@ while (page.hasNextPage()) page = await page.getNextPage()
 await nohead.records.list("posts", { cursor: page.meta.next_cursor! })
 ```
 
-Filters are equality filters (for fields with several values: "contains"), and accept strings, numbers, booleans and dates:
+Filters take a value to equal, or operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in` (a list) and `exists`. They combine with AND. On fields with several values, equal means "contains". Values are strings, numbers, booleans and dates. A `Date` is sent as a moment, for date fields with a time; a plain date field takes its `YYYY-MM-DD` string, and both take `"today"` (dates with a time `"now"` too). Lists sort by a field too, with records that have no value last:
 
 ```ts
 nohead.records.list("posts", {
-  filter: { status: "published", featured: true, author: "rec_01J9…" },
+  filter: {
+    published_at: { exists: true },
+    featured: true,
+    author: "rec_01J9…",
+  },
   sort: "-published_at",
   expand: ["author", "tags"],
 })
+
+nohead.records.list("products", {
+  filter: {
+    price: { lt: 50 },
+    category: { in: ["shoes", "bags"] },
+    cover: { exists: true },
+  },
+  sort: "price",
+})
 ```
 
 ## Errors
@@ -188,10 +228,10 @@ await nohead.records.create(
 Every method takes request options as its last argument:
 
 - `idempotencyKey`
-- `ifMatch` (record writes)
-- `changeNote`, a reason shown in history
 - `signal`, `timeout`, `maxRetries` and `headers`
 
+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)).
+
 ## Concurrency
 
 Pass the revision you read to make sure nobody changed the record since:
@@ -207,7 +247,7 @@ try {
 }
 ```
 
-`ifMatch` takes a record or a revision number, on `update`, `delete`, `publish`, `unpublish` and `revisions.revert`.
+`ifMatch` takes a record or a revision number, on `records.update`, `delete`, `restore`, `publish`, `unpublish` and `revisions.revert`, and a draft or its revision on `drafts.update`, `discard` and `merge`.
 
 ## Assets
 
@@ -235,10 +275,18 @@ const { url } = await nohead.assets.imageUrl(asset.id, {
 
 **Errors:** `UploadError` if storage refuses the bytes; `ValidationError` if the file fails the checks.
 
-**Resuming:** pass an `idempotencyKey` (`upload(file, {}, { idempotencyKey })`) and running the same upload again picks up where it stopped. An asset that is already `ready` comes back without sending the bytes again.
+**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.
 
 **Uploading from a browser:** create the upload on your server with `createUpload`, `PUT` the file from the browser, then `complete` it.
 
+**Deleting:** `delete` keeps a deleted asset until its `purge_after` (30 days), and `restore` brings it back. To remove it for good now, `purge` it after the delete. Records that use it keep an ID that no longer resolves, so check `usage` first:
+
+```ts
+const usage = await nohead.assets.usage(asset.id)
+usage.records // how many records use it, usage.published of them published
+usage.uses // the 10 most recently updated, with the fields that use it
+```
+
 ## Search
 
 ```ts
@@ -291,14 +339,14 @@ export async function POST(request: Request) {
       secret: process.env.NOHEAD_WEBHOOK_SECRET!,
     }
   )
-  if (event.type === "record.published") {
+  if (event.type === "record.published" && event.data.record) {
     revalidateTag(event.data.record.collection)
   }
   return new Response(null, { status: 204 })
 }
 ```
 
-`unwrap` checks the signature and the timestamp (Standard Webhooks), and throws `WebhookVerificationError` if either is off. 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. 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.
 
@@ -313,23 +361,25 @@ response.headers.get("RateLimit-Remaining")
 
 ## Reference
 
-| Resource                    | Methods                                                                                                                                     |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `records`                   | `list`, `get`, `create`, `update`, `delete`, `restore`, `publish`, `unpublish`, `schedule`, `unschedule`, `count`, `bulk`, `diff`, `search` |
-| `records.revisions`         | `list`, `get`, `revert`                                                                                                                     |
-| `search`                    | across the project                                                                                                                          |
-| `collections`               | `list`, `get`, `create`, `update`, `delete`, `restore`, `schema`                                                                            |
-| `collections.schemaChanges` | `list`, `get`                                                                                                                               |
-| `collections.searchIndex`   | `get`, `rebuild`                                                                                                                            |
-| `fields`                    | `list`, `create`, `update`, `delete`, `restore`, `reorder`, `removeAlias`, `migrate`                                                        |
-| `migrations`                | `list`, `get`, `cancel`                                                                                                                     |
-| `assets`                    | `upload`, `createUpload`, `complete`, `list`, `get`, `delete`, `restore`, `imageUrl`, `downloadUrl`                                         |
-| `webhooks`                  | `list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test`, `unwrap`                                                               |
-| `webhooks.deliveries`       | `list`, `get`, `retry`                                                                                                                      |
-| `auditEvents`               | `list`                                                                                                                                      |
-| `featureFlags`              | `list`                                                                                                                                      |
-| `me`                        | `get`                                                                                                                                       |
-| `health`                    | `check`                                                                                                                                     |
+| Resource                    | Methods                                                                                                                                                                                                 |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `records`                   | `list`, `get`, `create`, `update`, `delete`, `restore`, `publish`, `unpublish`, `publication`, `getSchedule`, `schedule`, `unschedule`, `scheduledChanges`, `drafts`, `count`, `bulk`, `diff`, `search` |
+| `drafts`                    | `create`, `list`, `get`, `update`, `discard`, `merge`, `schedule`, `unschedule`                                                                                                                         |
+| `records.revisions`         | `list`, `get`, `revert`                                                                                                                                                                                 |
+| `search`                    | across the project                                                                                                                                                                                      |
+| `collections`               | `list`, `get`, `create`, `update`, `delete`, `restore`, `schema`                                                                                                                                        |
+| `collections.schemaChanges` | `list`, `get`                                                                                                                                                                                           |
+| `collections.searchIndex`   | `get`, `rebuild`                                                                                                                                                                                        |
+| `fields`                    | `list`, `get`, `create`, `update`, `delete`, `restore`, `order`, `reorder`, `removeAlias`, `migrate`                                                                                                    |
+| `migrations`                | `list`, `get`, `cancel`                                                                                                                                                                                 |
+| `assets`                    | `upload`, `createUpload`, `complete`, `list`, `get`, `delete`, `restore`, `purge`, `usage`, `imageUrl`, `downloadUrl`                                                                                   |
+| `webhooks`                  | `list`, `get`, `create`, `update`, `delete`, `restore`, `rotateSecret`, `test`, `unwrap`                                                                                                                |
+| `webhooks.secrets`          | `list`, `retire`                                                                                                                                                                                        |
+| `webhooks.deliveries`       | `list`, `get`, `retry`                                                                                                                                                                                  |
+| `auditEvents`               | `list`                                                                                                                                                                                                  |
+| `featureFlags`              | `list`                                                                                                                                                                                                  |
+| `me`                        | `get`                                                                                                                                                                                                   |
+| `health`                    | `check`                                                                                                                                                                                                 |
 
 The SDK covers every operation an API key can call. Organizations, projects, members and API keys are managed in the web app. The full API is documented at [docs.nohead.io](https://docs.nohead.io).
 
@@ -350,7 +400,7 @@ NOHEAD_API_URL=http://localhost:3000 NOHEAD_API_KEY=sk_live_… npm run smoke
   - the types, in `src/generated/types.gen.ts` (hey-api)
   - the operation table, in `src/generated/operations.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.
+- `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.
 
@@ -360,7 +410,7 @@ The smoke test (`smoke/smoke.ts`) runs the core flow against a real API, using t
 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.
-5. The tag starts `.github/workflows/release.yml`. 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 checks the version and its notes, tests, and stages the package on npm with provenance through trusted publishing (no token). Then it creates a draft GitHub release.
+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.
 
 ## License

package/dist/client.d.ts

@@ -2,11 +2,12 @@ import type { PagePromise } from "./api-promise.ts";
 import { type ClientOptions, 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";
 import { AuditEvents, FeatureFlags, Health, Me } from "./resources/other.ts";
 import { Records } from "./resources/records.ts";
 import { Collections, Fields, Migrations } from "./resources/schema.ts";
 import { Webhooks } from "./resources/webhooks.ts";
-import type { NoheadRecord, ProjectSearchParams, RecordData, SearchMeta } from "./types.ts";
+import type { NoheadDraft, NoheadRecord, ProjectSearchParams, RecordData, SearchMeta } from "./types.ts";
 /**
  * A client for the Nohead API, authenticated with a project API key.
  *
@@ -18,6 +19,7 @@ import type { NoheadRecord, ProjectSearchParams, RecordData, SearchMeta } from "
 export declare class Nohead {
     #private;
     readonly records: Records;
+    readonly drafts: Drafts;
     readonly collections: Collections;
     readonly fields: Fields;
     readonly migrations: Migrations;
@@ -37,6 +39,7 @@ export declare class Nohead {
 /** The main types, also reachable as `Nohead.Record`, `Nohead.Collection`… */
 export declare namespace Nohead {
     type Record<D = RecordData> = NoheadRecord<D>;
+    type Draft<D = RecordData> = NoheadDraft<D>;
     type Collection = G.Collection;
     type Field = G.Field;
     type Asset = G.Asset;

package/dist/client.js

@@ -1,5 +1,6 @@
 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";
 import { Records } from "./resources/records.js";
 import { Collections, Fields, Migrations } from "./resources/schema.js";
@@ -14,6 +15,7 @@ import { Webhooks } from "./resources/webhooks.js";
  */
 export class Nohead {
     records;
+    drafts;
     collections;
     fields;
     migrations;
@@ -28,6 +30,7 @@ export class Nohead {
         const core = new Core(options);
         this.#core = core;
         this.records = new Records(core);
+        this.drafts = new Drafts(core);
         this.collections = new Collections(core);
         this.fields = new Fields(core);
         this.migrations = new Migrations(core);
@@ -43,6 +46,16 @@ export class Nohead {
      * collections), most relevant first, through the first 1,000 hits.
      */
     search(query, params = {}, options) {
-        return this.#core.paginate("projects_search", { query: { q: query, ...params } }, options);
+        const { collections, filter, ...rest } = params;
+        return this.#core.paginate("projects_search", {
+            query: {
+                q: query,
+                ...rest,
+                filter: {
+                    ...filter,
+                    ...(collections ? { collection: { in: collections } } : {}),
+                },
+            },
+        }, options);
     }
 }

package/dist/core.d.ts

@@ -39,8 +39,6 @@ export interface RetryEvent {
 export interface RequestOptions {
     /** Sent as `Idempotency-Key` on writes. Generated when omitted. */
     idempotencyKey?: string;
-    /** A reason for the change, shown in history (`Nohead-Change-Note`). */
-    changeNote?: string;
     signal?: AbortSignal;
     /** Milliseconds per attempt, overriding the client's. */
     timeout?: number;
@@ -48,28 +46,53 @@ export interface RequestOptions {
     maxRetries?: number;
     headers?: Record<string, string>;
 }
-/** Options of record writes that accept `If-Match`. */
+/** Options of writes that change records or the schema. */
+export interface WriteOptions extends RequestOptions {
+    /**
+     * A reason for the change, kept with the revision, schema change or
+     * migration it makes (`Nohead-Change-Note`).
+     */
+    changeNote?: string;
+}
+/** Options of draft writes that accept `If-Match`. */
 export interface ConditionalRequestOptions extends RequestOptions {
     /**
-     * Only write if the record is still at this revision; otherwise the API
-     * answers `412` (`PreconditionFailedError`). A record works too.
+     * Only write if the record (or the draft) is still at this revision;
+     * otherwise the API answers `412` (`PreconditionFailedError`). A record
+     * or a draft works too.
      */
     ifMatch?: number | {
         revision: number;
     };
 }
+/** Options of record writes, which accept `If-Match` and a change note. */
+export interface ConditionalWriteOptions extends WriteOptions, ConditionalRequestOptions {
+}
+/** The request headers an operation declares. */
+type HeadersOf<Op extends OperationId> = Operations[Op]["data"] extends {
+    headers?: infer H;
+} ? keyof NonNullable<H> : 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.
+ */
+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;
+});
 export interface RequestInput {
     path?: Record<string, string | number | undefined>;
     query?: object;
     body?: unknown;
 }
-type AllOptions = ConditionalRequestOptions;
 export declare class Core {
     #private;
     constructor(options: ClientOptions);
     /** The API key's project, from `GET /v1/me` the first time. */
     projectId(): Promise<string>;
-    request<Op extends OperationId>(operation: Op, input?: RequestInput, options?: AllOptions): APIPromise<Operations[Op]["response"]>;
+    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. */
@@ -79,8 +102,9 @@ export declare class Core {
 }
 /**
  * Query parameters as the API reads them: objects become `key[sub]=…`
- * (`filter[status]=published`), arrays are comma-separated
- * (`expand=author,tags`), dates are ISO 8601.
+ * (`filter[price][lt]=50`), arrays are comma-separated (`expand=author,tags`)
+ * with `\,` for a comma inside a value and `\\` for a backslash, dates are
+ * ISO 8601.
  */
 export declare function appendQuery(params: URLSearchParams, value: unknown, key?: string): void;
 export {};

package/dist/core.js

@@ -3,6 +3,12 @@ import { AbortError, ConnectionError, NoheadError, TimeoutError, apiError, retry
 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;
 const warnedDeprecations = new Set();
@@ -25,8 +31,7 @@ export class Core {
             throw new NoheadError("Missing API key: pass `apiKey` or set NOHEAD_API_KEY");
         }
         this.#apiKey = apiKey;
-        this.#baseUrl = (options.baseUrl ??
-            (env.NOHEAD_API_URL || DEFAULT_BASE_URL)).replace(/\/+$/, "");
+        this.#baseUrl = withoutTrailingSlashes(options.baseUrl ?? (env.NOHEAD_API_URL || DEFAULT_BASE_URL));
         this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
         this.#headers = options.headers ?? {};
         this.#maxRetries = options.maxRetries ?? 2;
@@ -109,8 +114,10 @@ export class Core {
                 : options.ifMatch;
             headers["If-Match"] = `"${revision}"`;
         }
+        // Percent-encoded UTF-8: header values are bytes, and fetch refuses
+        // anything past Latin-1 (the API decodes it).
         if (options.changeNote)
-            headers["Nohead-Change-Note"] = options.changeNote;
+            headers["Nohead-Change-Note"] = encodeURIComponent(wellFormed(options.changeNote));
         Object.assign(headers, options.headers);
         const init = {
             method,
@@ -252,8 +259,9 @@ async function parseBody(response) {
 }
 /**
  * Query parameters as the API reads them: objects become `key[sub]=…`
- * (`filter[status]=published`), arrays are comma-separated
- * (`expand=author,tags`), dates are ISO 8601.
+ * (`filter[price][lt]=50`), arrays are comma-separated (`expand=author,tags`)
+ * with `\,` for a comma inside a value and `\\` for a backslash, dates are
+ * ISO 8601.
  */
 export function appendQuery(params, value, key) {
     if (value === undefined || value === null)
@@ -262,8 +270,10 @@ export function appendQuery(params, value, key) {
         params.append(key, value.toISOString());
     }
     else if (Array.isArray(value)) {
-        if (value.length > 0)
-            params.append(key, value.map(scalar).join(","));
+        // Missing items are left out, as missing values are.
+        const items = value.filter((item) => item !== undefined && item !== null);
+        if (items.length > 0)
+            params.append(key, items.map((item) => scalar(item).replace(/[\\,]/g, "\\$&")).join(","));
     }
     else if (typeof value === "object") {
         for (const [name, inner] of Object.entries(value)) {
@@ -293,6 +303,13 @@ 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) {
+    let end = url.length;
+    while (end > 0 && url[end - 1] === "/")
+        end--;
+    return url.slice(0, end);
+}
 function environment() {
     const process = globalThis.process;
     return process?.env ?? {};

package/dist/errors.d.ts

@@ -8,8 +8,11 @@ export declare class APIError extends NoheadError {
     name: string;
     /** The HTTP status. */
     readonly status: number;
-    /** The error `type`, e.g. `validation_error`; undefined if the body had none. */
-    readonly type: ErrorType | undefined;
+    /**
+     * The error `type`, e.g. `validation_error`; undefined if the body had
+     * none. A type newer than this SDK is kept as its string.
+     */
+    readonly type: ErrorType | (string & {}) | undefined;
     /** The request's ID (`req_…`), for support requests and logs. */
     readonly requestId: string | undefined;
     /** Field-level details, e.g. `[{ field: "title", code: "required", … }]`. */