@nohead/sdk 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.6.0
+
+- API keys now start `nohead_sk_`, or `nohead_pk_` for published-only keys;
+  keys in the old `sk_live_` format no longer work. The SDK sends whatever key
+  it's given, so only the docs and examples change.
+
+- `assets.update(asset, { filename?, alt? })` renames an asset and sets its
+  alt text (`PATCH /v1/assets/{asset_id}`). `Asset` has `alt` (a string or
+  `null`), and webhooks can subscribe to `asset.updated`.
+
+- Image URLs are open. `Asset` has `image_url`, the whole image, and
+  `imageUrl` from the new `@nohead/sdk/images` (no dependencies) writes any of
+  imgproxy's processing options into it, without a request. It also has
+  loaders for Next.js (`nextImageLoader`), Astro (`astroImageService`) and
+  Nuxt Image (`nuxtImageProvider`, or `getImage` on Nuxt Image 1), which leave
+  other images as they are.
+
+- **Breaking:** `assets.imageUrl` is gone, with the API's
+  `GET /v1/assets/{asset_id}/image-url`: use `imageUrl` from
+  `@nohead/sdk/images`, which needs no request.
+
+- **Breaking:** `Collection` has no `search_enabled`, and `SearchIndex` no
+  `enabled`: API keys search every collection they can read.
+
+- `revisions.get(revision)` reads a revision by its own `rev_` ID, as
+  webhooks and the activity log name it (`GET /v1/revisions/{revision_id}`).
+
+- `records.create` takes `upsert_on`, a unique field's key: the record
+  holding that value is updated instead, if one exists, and `ifMatch`
+  applies to that update.
+
+- Collections have `public_search`: whether the project's search tokens find
+  their published records. Off by default; `collections.create` and
+  `collections.update` take it. A collection's search index has `index`, the
+  name a token searches it by.
+
 ## 0.5.0
 
 - **Breaking:** field migrations are created under their collection:

package/README.md

@@ -51,17 +51,17 @@ const nohead = new Nohead({
 })
 ```
 
-| Option       | Default                                        |                                                                    |
-| ------------ | ---------------------------------------------- | ------------------------------------------------------------------ |
-| `apiKey`     | `NOHEAD_API_KEY`                               | A project API key (`sk_live_…`). 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`    | `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).                 |
 
 API keys belong to a project, so methods like `collections.list()` need no project ID. Collections can be named by ID or slug everywhere.
 
@@ -81,6 +81,15 @@ 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.
 
+**Upserts.** With `upsert_on`, the key of a `unique` field, `create` updates the record holding that value instead, if one exists, so a content sync can run again without duplicates:
+
+```ts
+await nohead.records.create("products", {
+  data: { sku: "TEE-01", title: "Tee" },
+  upsert_on: "sku",
+})
+```
+
 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:
@@ -97,7 +106,7 @@ await nohead.records.update<Post>(id, { data: { title: null } }) // null clears
 
 The type is a promise you make; nothing is checked at runtime. The record type itself is `Nohead.Record<Post>` (also exported as `NoheadRecord`).
 
-**More:** `count`, `bulk` (up to 100 records at once), `diff`, `revisions.list`, `revisions.get` and `revisions.revert` (with `{ dry_run: true }` for a preview).
+**More:** `count`, `bulk` (up to 100 records at once), `diff`, `revisions.list`, `revisions.get` and `revisions.revert` (with `{ dry_run: true }` for a preview). A revision by its own ID, as webhooks and the activity log name it: `nohead.revisions.get("rev_…")`.
 
 ## Drafts
 
@@ -258,13 +267,33 @@ const asset = await nohead.assets.upload(await openAsBlob("cover.jpg"), {
   filename: "cover.jpg",
 })
 await nohead.records.update(id, { data: { cover: asset.id } })
+```
+
+**Images.** Image URLs are open: an image's `image_url` serves the whole image, and any of [imgproxy's processing options](https://docs.imgproxy.net/usage/processing) written into it transform it. `@nohead/sdk/images` builds them without a request, and has no dependencies, so it suits browser bundles:
+
+```ts
+import { imageUrl } from "@nohead/sdk/images"
 
-const { url } = await nohead.assets.imageUrl(asset.id, {
+imageUrl(asset, {
   width: 1200,
+  height: 630,
+  fit: "cover",
+  gravity: "sm",
   format: "webp",
 })
+imageUrl(asset.image_url!, { width: 400, dpr: 2, options: ["bl:2"] })
 ```
 
+Frameworks' image components, with `srcset` and all, take a loader from it:
+
+- **Next.js:** a file named by `images.loaderFile` in next.config: `export { nextImageLoader as default } from "@nohead/sdk/images"`, then `<Image src={asset.image_url} … />`.
+- **Astro:** a module named by `image.service.entrypoint` in astro.config: `export { astroImageService as default } from "@nohead/sdk/images"`.
+- **Nuxt Image:** a custom provider file in nuxt.config's `image.providers`: `export { nuxtImageProvider as default } from "@nohead/sdk/images"` (Nuxt Image 1: `export { getImage } from "@nohead/sdk/images"`).
+
+The loaders leave other images, the site's own, as they are.
+
+Thumbnails: an image's `preview_url` fits in 640×640, as WebP.
+
 **What `upload` accepts:** a `Blob`, `File`, `ArrayBuffer`, `Uint8Array`, or a `ReadableStream` with `byte_size`.
 
 **What it does:**
@@ -279,6 +308,14 @@ const { url } = await nohead.assets.imageUrl(asset.id, {
 
 **Uploading from a browser:** create the upload on your server with `createUpload`, `PUT` the file from the browser, then `complete` it.
 
+**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.
+
+```ts
+await nohead.assets.update(asset.id, {
+  alt: "The spring menu, on a chalkboard",
+})
+```
+
 **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
@@ -298,7 +335,7 @@ const results = await nohead.search("content model", { collections: ["posts", "p
 results.meta.total_estimate
 ```
 
-Search needs `search_enabled` collections and the `search:read` scope. It pages through the first 1,000 hits.
+Search needs the `search:read` scope and covers every collection the key can read, matching their `searchable` fields. It pages through the first 1,000 hits. For search straight from a site's browser, without the API, use a search token from the web app with Meilisearch's own clients or InstantSearch.
 
 ## Schema
 
@@ -370,13 +407,14 @@ response.headers.get("RateLimit-Remaining")
 | `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`                                                                                                                                                                                 |
+| `revisions`                 | `get` (by its own `rev_` ID, as webhooks and the activity log name it)                                                                                                                                  |
 | `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`                                                                                                               |
 | `migrations`                | `create`, `list`, `get`, `cancel`                                                                                                                                                                       |
-| `assets`                    | `upload`, `createUpload`, `complete`, `list`, `get`, `delete`, `restore`, `purge`, `usage`, `imageUrl`, `downloadUrl`                                                                                   |
+| `assets`                    | `upload`, `createUpload`, `complete`, `list`, `get`, `update`, `delete`, `restore`, `purge`, `usage`, `downloadUrl`                                                                                     |
 | `webhooks`                  | `list`, `get`, `create`, `update`, `delete`, `restore`, `rotateSecret`, `test`, `unwrap`                                                                                                                |
 | `webhooks.secrets`          | `list`, `retire`                                                                                                                                                                                        |
 | `webhooks.deliveries`       | `list`, `get`, `retry`                                                                                                                                                                                  |
@@ -395,7 +433,7 @@ npm test             # unit and contract tests
 npm run lint && npm run typecheck && 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=sk_live_… npm run smoke
+NOHEAD_API_URL=http://localhost:3000 NOHEAD_API_KEY=nohead_sk_… npm run smoke
 ```
 
 **How the code is organized:**

package/dist/client.d.ts

@@ -4,7 +4,7 @@ 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 { Records, RevisionsById } from "./resources/records.ts";
 import { Collections, Fields, Migrations } from "./resources/schema.ts";
 import { Webhooks } from "./resources/webhooks.ts";
 import type { NoheadDraft, NoheadRecord, ProjectSearchParams, RecordData, SearchMeta } from "./types.ts";
@@ -19,6 +19,7 @@ import type { NoheadDraft, NoheadRecord, ProjectSearchParams, RecordData, Search
 export declare class Nohead {
     #private;
     readonly records: Records;
+    readonly revisions: RevisionsById;
     readonly drafts: Drafts;
     readonly collections: Collections;
     readonly fields: Fields;

package/dist/client.js

@@ -2,7 +2,7 @@ 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 { Records, RevisionsById } from "./resources/records.js";
 import { Collections, Fields, Migrations } from "./resources/schema.js";
 import { Webhooks } from "./resources/webhooks.js";
 /**
@@ -15,6 +15,7 @@ import { Webhooks } from "./resources/webhooks.js";
  */
 export class Nohead {
     records;
+    revisions;
     drafts;
     collections;
     fields;
@@ -30,6 +31,7 @@ export class Nohead {
         const core = new Core(options);
         this.#core = core;
         this.records = new Records(core);
+        this.revisions = new RevisionsById(core);
         this.drafts = new Drafts(core);
         this.collections = new Collections(core);
         this.fields = new Fields(core);

package/dist/core.d.ts

@@ -4,7 +4,10 @@ import { type OperationId, type Operations } from "./generated/operations.gen.ts
 import type { ListMeta } from "./generated/types.gen.ts";
 export declare const DEFAULT_BASE_URL = "https://api.nohead.io";
 export interface ClientOptions {
-    /** A project API key (`sk_live_…`). Defaults to `NOHEAD_API_KEY`. */
+    /**
+     * A project API key (`nohead_sk_…`, or `nohead_pk_…` when published-only).
+     * Defaults to `NOHEAD_API_KEY`.
+     */
     apiKey?: string;
     /** Defaults to `NOHEAD_API_URL`, else `https://api.nohead.io`. */
     baseUrl?: string;

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

@@ -16,10 +16,6 @@ export declare const OPERATIONS: {
         readonly method: "GET";
         readonly path: "/v1/assets/{asset_id}";
     };
-    readonly assets_image_url: {
-        readonly method: "GET";
-        readonly path: "/v1/assets/{asset_id}/image-url";
-    };
     readonly assets_list: {
         readonly method: "GET";
         readonly path: "/v1/projects/{project_id}/assets";
@@ -32,6 +28,10 @@ export declare const OPERATIONS: {
         readonly method: "POST";
         readonly path: "/v1/assets/{asset_id}/restore";
     };
+    readonly assets_update: {
+        readonly method: "PATCH";
+        readonly path: "/v1/assets/{asset_id}";
+    };
     readonly assets_upload: {
         readonly method: "POST";
         readonly path: "/v1/projects/{project_id}/assets";
@@ -252,6 +252,10 @@ export declare const OPERATIONS: {
         readonly method: "PATCH";
         readonly path: "/v1/records/{record_id}";
     };
+    readonly revisions_get: {
+        readonly method: "GET";
+        readonly path: "/v1/revisions/{revision_id}";
+    };
     readonly scheduled_changes_list: {
         readonly method: "GET";
         readonly path: "/v1/collections/{collection_id}/scheduled-changes";
@@ -343,10 +347,6 @@ export interface Operations {
         data: T.AssetsGetData;
         response: T.AssetsGetResponse;
     };
-    assets_image_url: {
-        data: T.AssetsImageUrlData;
-        response: T.AssetsImageUrlResponse;
-    };
     assets_list: {
         data: T.AssetsListData;
         response: T.AssetsListResponse;
@@ -359,6 +359,10 @@ export interface Operations {
         data: T.AssetsRestoreData;
         response: T.AssetsRestoreResponse;
     };
+    assets_update: {
+        data: T.AssetsUpdateData;
+        response: T.AssetsUpdateResponse;
+    };
     assets_upload: {
         data: T.AssetsUploadData;
         response: T.AssetsUploadResponse;
@@ -579,6 +583,10 @@ export interface Operations {
         data: T.RecordsUpdateData;
         response: T.RecordsUpdateResponse;
     };
+    revisions_get: {
+        data: T.RevisionsGetData;
+        response: T.RevisionsGetResponse;
+    };
     scheduled_changes_list: {
         data: T.ScheduledChangesListData;
         response: T.ScheduledChangesListResponse;

package/dist/generated/operations.gen.js

@@ -3,10 +3,10 @@ export const OPERATIONS = {
     assets_delete: { method: "DELETE", path: "/v1/assets/{asset_id}" },
     assets_download_url: { method: "GET", path: "/v1/assets/{asset_id}/download-url" },
     assets_get: { method: "GET", path: "/v1/assets/{asset_id}" },
-    assets_image_url: { method: "GET", path: "/v1/assets/{asset_id}/image-url" },
     assets_list: { method: "GET", path: "/v1/projects/{project_id}/assets" },
     assets_purge: { method: "POST", path: "/v1/assets/{asset_id}/purge" },
     assets_restore: { method: "POST", path: "/v1/assets/{asset_id}/restore" },
+    assets_update: { method: "PATCH", path: "/v1/assets/{asset_id}" },
     assets_upload: { method: "POST", path: "/v1/projects/{project_id}/assets" },
     assets_usage: { method: "GET", path: "/v1/assets/{asset_id}/usage" },
     audit_events_list: { method: "GET", path: "/v1/projects/{project_id}/audit-events" },
@@ -62,6 +62,7 @@ export const OPERATIONS = {
     records_unpublish: { method: "DELETE", path: "/v1/records/{record_id}/publication" },
     records_unschedule: { method: "DELETE", path: "/v1/records/{record_id}/schedule" },
     records_update: { method: "PATCH", path: "/v1/records/{record_id}" },
+    revisions_get: { method: "GET", path: "/v1/revisions/{revision_id}" },
     scheduled_changes_list: { method: "GET", path: "/v1/collections/{collection_id}/scheduled-changes" },
     schema_changes_get: { method: "GET", path: "/v1/schema-changes/{schema_change_id}" },
     schema_changes_list: { method: "GET", path: "/v1/collections/{collection_id}/schema-changes" },

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

@@ -1 +1 @@
-export type { Actor, ApiKeyScope, Asset, AssetEventData, AssetField, AssetFieldConfiguration, AssetFieldCreate, AssetList, AssetProperties, AssetUploadCreate, AssetUploadTarget, AssetUsage, AssetWithUpload, AuditEvent, AuditEventList, BooleanField, BooleanFieldConfiguration, BooleanFieldCreate, Change, Collection, CollectionCreate, CollectionList, CollectionUpdate, DateField, DateFieldConfiguration, DateFieldCreate, DecimalField, DecimalFieldConfiguration, DecimalFieldCreate, DownloadUrl, Draft, DraftCreate, DraftEventData, DraftList, DraftSchedule, DraftScheduleUpdate, EnumField, EnumFieldConfiguration, EnumFieldCreate, Error, ErrorDetail, ErrorType, FeatureFlags, Field, FieldAliasEventData, FieldConfiguration, FieldCreate, FieldCreateProperties, FieldDefinition, FieldList, FieldMigration, FieldMigrationCounts, FieldMigrationList, FieldMigrationPreview, FieldMigrationRequest, FieldOrder, FieldProperties, FieldType, FieldUpdate, Health, ImageUrl, IntegerField, IntegerFieldConfiguration, IntegerFieldCreate, JsonField, JsonFieldConfiguration, JsonFieldCreate, ListMeta, LongTextField, LongTextFieldConfiguration, LongTextFieldCreate, MergedDraft, NullableTimestamp, Principal, PublishedOnly, RecordBatch, RecordBatchRequest, RecordCount, RecordData, RecordDiff, RecordEventData, RecordFilterValue, RecordList, RecordPublication, RecordRevision, RecordRevisionDetail, RecordRevisionList, RecordRevisionOperation, RecordRevisionProperties, RecordSchedule, RecordScheduleUpdate, RecordWrite, RelationField, RelationFieldConfiguration, RelationFieldCreate, RequestId, RevertPreview, RichTextField, RichTextFieldConfiguration, RichTextFieldCreate, ScheduledChange, ScheduledChangeList, Schema, SchemaChange, SchemaChangeDetail, SchemaChangeList, SchemaChangeProperties, SchemaDefinition, SchemaEventData, SearchIndex, SearchResults, TextField, TextFieldConfiguration, TextFieldCreate, TimeFilter, Timestamp, Via, Webhook, WebhookCreate, WebhookDelivery, WebhookDeliveryDetail, WebhookDeliveryList, WebhookDeliveryProperties, WebhookEventPayload, WebhookEventType, WebhookList, WebhookProperties, WebhookSecret, WebhookSecretList, WebhookSecretProperties, WebhookSecretWithValue, WebhookSubscription, WebhookTestEventData, WebhookUpdate, WebhookWithSecret, } from "./types.gen.ts";
+export type { Actor, ApiKeyScope, Asset, AssetEventData, AssetField, AssetFieldConfiguration, AssetFieldCreate, AssetList, AssetProperties, AssetUpdate, AssetUploadCreate, AssetUploadTarget, AssetUsage, AssetWithUpload, AuditEvent, AuditEventList, BooleanField, BooleanFieldConfiguration, BooleanFieldCreate, Change, Collection, CollectionCreate, CollectionList, CollectionUpdate, DateField, DateFieldConfiguration, DateFieldCreate, DecimalField, DecimalFieldConfiguration, DecimalFieldCreate, DownloadUrl, Draft, DraftCreate, DraftEventData, DraftList, DraftSchedule, DraftScheduleUpdate, EnumField, EnumFieldConfiguration, EnumFieldCreate, Error, ErrorDetail, ErrorType, FeatureFlags, Field, FieldAliasEventData, FieldConfiguration, FieldCreate, FieldCreateProperties, FieldDefinition, FieldList, FieldMigration, FieldMigrationCounts, FieldMigrationList, FieldMigrationPreview, FieldMigrationRequest, FieldOrder, FieldProperties, FieldType, FieldUpdate, Health, IntegerField, IntegerFieldConfiguration, IntegerFieldCreate, JsonField, JsonFieldConfiguration, JsonFieldCreate, ListMeta, LongTextField, LongTextFieldConfiguration, LongTextFieldCreate, MergedDraft, NullableTimestamp, Principal, PublishedOnly, RecordBatch, RecordBatchRequest, RecordCount, RecordCreate, RecordData, RecordDiff, RecordEventData, RecordFilterValue, RecordList, RecordPublication, RecordRevision, RecordRevisionDetail, RecordRevisionList, RecordRevisionOperation, RecordRevisionProperties, RecordSchedule, RecordScheduleUpdate, RecordWrite, RelationField, RelationFieldConfiguration, RelationFieldCreate, RequestId, RevertPreview, RichTextField, RichTextFieldConfiguration, RichTextFieldCreate, ScheduledChange, ScheduledChangeList, Schema, SchemaChange, SchemaChangeDetail, SchemaChangeList, SchemaChangeProperties, SchemaDefinition, SchemaEventData, SearchIndex, SearchResults, TextField, TextFieldConfiguration, TextFieldCreate, TimeFilter, Timestamp, Via, Webhook, WebhookCreate, WebhookDelivery, WebhookDeliveryDetail, WebhookDeliveryList, WebhookDeliveryProperties, WebhookEventPayload, WebhookEventType, WebhookList, WebhookProperties, WebhookSecret, WebhookSecretList, WebhookSecretProperties, WebhookSecretWithValue, WebhookSubscription, WebhookTestEventData, WebhookUpdate, WebhookWithSecret, } from "./types.gen.ts";

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

@@ -574,11 +574,15 @@ export type Collection = {
      */
     purge_after: NullableTimestamp;
     /**
-     * Whether API keys can search the collection (`GET /v1/collections/{collection_id}/search`).
-     * Every collection is indexed; members can search it in the web app either way.
+     * Whether the project's search tokens (made in the web app) find
+     * its published records, from a browser or a backend. Off by
+     * default: every field of those records becomes readable by anyone
+     * with a token, so turn it on only for collections whose published
+     * records are public. A change reaches search tokens within
+     * seconds.
      *
      */
-    search_enabled: boolean;
+    public_search: boolean;
     /**
      * Active fields in position order.
      */
@@ -587,17 +591,17 @@ export type Collection = {
     updated_at: Timestamp;
 };
 export type CollectionCreate = {
-    search_enabled?: boolean;
     name: string;
     slug: string;
     description?: string | null;
+    public_search?: boolean;
     fields?: Array<FieldCreate>;
 };
 export type CollectionUpdate = {
-    search_enabled?: boolean;
     name?: string;
     slug?: string;
     description?: string | null;
+    public_search?: boolean;
 };
 export type CollectionList = {
     data: Array<Collection>;
@@ -612,7 +616,10 @@ export type SchemaDefinition = {
     slug: string;
     description: string | null;
     deleted_at: NullableTimestamp;
-    search_enabled?: boolean;
+    /**
+     * Absent from schemas before the setting existed (off).
+     */
+    public_search?: boolean;
     fields: Array<{
         id: string;
         name: string;
@@ -876,7 +883,7 @@ export type TimeFilter = {
 /**
  * The client a change came through; `scheduler` for scheduled changes.
  */
-export type Via = 'ui' | 'api' | 'cli' | 'sdk' | 'system' | 'scheduler';
+export type Via = 'ui' | 'api' | 'cli' | 'sdk' | 'mcp' | 'system' | 'scheduler';
 /**
  * Changes to a record's content that wait until they are merged into
  * it, now or at `schedule.merge_at`. Content only: whether the record
@@ -1022,6 +1029,16 @@ export type Record = {
 export type RecordWrite = {
     data: RecordData;
 };
+export type RecordCreate = {
+    data: RecordData;
+    /**
+     * The key of a `unique` field (a slug, or a field with `unique` on)
+     * whose value `data` includes: update the record that has it, or
+     * create one.
+     *
+     */
+    upsert_on?: string;
+};
 export type RecordList = {
     data: Array<Record>;
     meta: ListMeta;
@@ -1140,9 +1157,11 @@ export type SearchIndex = {
     object: 'search_index';
     collection_id: string;
     /**
-     * The collection's `search_enabled`; the index is kept up to date either way.
+     * The index's name in the search engine, which search tokens search
+     * (`indexUid` in Meilisearch's search API). Opaque; it never changes.
+     *
      */
-    enabled: boolean;
+    index: string;
     /**
      * `building` until first built; `stale` from the change that queues a rebuild until it has run; `failed` if the last rebuild failed (it is retried).
      */
@@ -1157,7 +1176,7 @@ export type SearchIndex = {
  * (`record.*`, `draft.*`, `collection.*`, `field.*`, `asset.*`) or `*` for all.
  *
  */
-export type WebhookEventType = 'record.created' | 'record.updated' | 'record.published' | 'record.unpublished' | 'record.deleted' | 'record.restored' | 'record.reverted' | 'record.redacted' | 'record.scheduled' | 'record.unscheduled' | 'record.schedule_failed' | 'draft.created' | 'draft.updated' | 'draft.discarded' | 'draft.scheduled' | 'draft.unscheduled' | 'draft.schedule_failed' | 'collection.created' | 'collection.updated' | 'collection.deleted' | 'collection.restored' | 'collection.fields_reordered' | 'field.created' | 'field.updated' | 'field.deleted' | 'field.restored' | 'field.migrated' | 'field.alias_removed' | 'asset.created' | 'asset.deleted' | 'asset.restored' | 'asset.purged';
+export type WebhookEventType = 'record.created' | 'record.updated' | 'record.published' | 'record.unpublished' | 'record.deleted' | 'record.restored' | 'record.reverted' | 'record.redacted' | 'record.scheduled' | 'record.unscheduled' | 'record.schedule_failed' | 'draft.created' | 'draft.updated' | 'draft.discarded' | 'draft.scheduled' | 'draft.unscheduled' | 'draft.schedule_failed' | 'collection.created' | 'collection.updated' | 'collection.deleted' | 'collection.restored' | 'collection.fields_reordered' | 'field.created' | 'field.updated' | 'field.deleted' | 'field.restored' | 'field.migrated' | 'field.alias_removed' | 'asset.created' | 'asset.updated' | 'asset.deleted' | 'asset.restored' | 'asset.purged';
 export type WebhookSubscription = WebhookEventType | 'record.*' | 'draft.*' | 'collection.*' | 'field.*' | 'asset.*' | '*';
 export type Webhook = WebhookProperties;
 export type WebhookProperties = {
@@ -1461,14 +1480,28 @@ export type WebhookTestEventData = {
     webhook: null | Webhook;
 };
 export type Asset = AssetProperties;
+export type AssetUpdate = {
+    /**
+     * Control characters are removed and path separators become `_`, as on upload.
+     */
+    filename?: string;
+    /**
+     * Surrounding whitespace is removed; empty or null clears it.
+     */
+    alt?: string | null;
+};
 export type AssetProperties = {
     id: string;
     object: 'asset';
     project_id: string;
     /**
-     * The original filename, any Unicode.
+     * The filename, any Unicode, as uploaded unless renamed since. Downloads use it.
      */
     filename: string;
+    /**
+     * Alternative text, saying what an image shows; null until set. The default wherever the asset is used.
+     */
+    alt: string | null;
     content_type: string;
     byte_size: number;
     /**
@@ -1489,7 +1522,20 @@ export type AssetProperties = {
      */
     purge_after: NullableTimestamp;
     /**
-     * A signed URL of a small rendition (fits in 640×640, WebP), for ready images, deleted ones included until they are purged; null otherwise.
+     * The URL of the whole image, for ready images (JPEG, PNG, GIF, WebP
+     * or AVIF), deleted ones included until they are purged; null
+     * otherwise. Image URLs are open and never expire. For a rendition,
+     * write [imgproxy processing options](https://docs.imgproxy.net/usage/processing)
+     * before `/plain/`, and a format after `@`: for example
+     * `https://images.nohead.io/rs:fill:800:600/g:sm/plain/…@webp`. Renditions
+     * are at most 4096 pixels a side, from originals of at most 50
+     * megapixels. Options that would return the file as stored (`raw`,
+     * `skip_processing`, `strip_metadata`) are refused.
+     *
+     */
+    image_url: string | null;
+    /**
+     * The URL of a small rendition (fits in 640×640, WebP), for ready images, deleted ones included until they are purged; null otherwise.
      */
     preview_url: string | null;
     uploaded_at: NullableTimestamp;
@@ -1500,16 +1546,6 @@ export type AssetList = {
     data: Array<Asset>;
     meta: ListMeta;
 };
-export type ImageUrl = {
-    object: 'image_url';
-    asset_id: string;
-    url: string;
-    width: number | null;
-    height: number | null;
-    fit: 'contain' | 'cover' | 'fill';
-    format: 'original' | 'webp' | 'avif' | 'jpeg' | 'png';
-    quality: number | null;
-};
 export type AssetUsage = {
     object: 'asset_usage';
     asset_id: string;
@@ -1632,6 +1668,7 @@ export type WebhookId = string;
 export type DeliveryId = string;
 export type RecordId = string;
 export type DraftId = string;
+export type RevisionId = string;
 /**
  * Per-record revision number.
  */
@@ -1861,7 +1898,7 @@ export type RecordsListResponses = {
 };
 export type RecordsListResponse = RecordsListResponses[keyof RecordsListResponses];
 export type RecordsCreateData = {
-    body: RecordWrite;
+    body: RecordCreate;
     headers?: {
         /**
          * A unique value (1-255 printable ASCII characters) that makes retrying
@@ -1873,6 +1910,10 @@ export type RecordsCreateData = {
          *
          */
         'Idempotency-Key'?: string;
+        /**
+         * The revision you last read (the record's, or the draft's for a draft), e.g. `"7"`. Stale writes fail with 412.
+         */
+        'If-Match'?: string;
         /**
          * First-party client identifier recorded in history (e.g. `cli/0.3.1`). Informational only.
          */
@@ -1924,6 +1965,12 @@ export type RecordsCreateErrors = {
      * The request conflicts with current state.
      */
     409: Error;
+    /**
+     * The resource changed since the revision given in `If-Match`. Nothing was
+     * written; `details` includes the current revision.
+     *
+     */
+    412: Error;
     /**
      * The request failed validation.
      */
@@ -1939,6 +1986,10 @@ export type RecordsCreateErrors = {
 };
 export type RecordsCreateError = RecordsCreateErrors[keyof RecordsCreateErrors];
 export type RecordsCreateResponses = {
+    /**
+     * The record.
+     */
+    200: Record;
     /**
      * The created record.
      */
@@ -2942,6 +2993,48 @@ export type RecordRevisionsGetResponses = {
     200: RecordRevisionDetail;
 };
 export type RecordRevisionsGetResponse = RecordRevisionsGetResponses[keyof RecordRevisionsGetResponses];
+export type RevisionsGetData = {
+    body?: never;
+    path: {
+        revision_id: string;
+    };
+    query?: never;
+    url: '/v1/revisions/{revision_id}';
+};
+export type RevisionsGetErrors = {
+    /**
+     * The request was malformed: unparseable JSON, an invalid query parameter, or a body key the operation doesn't take (detail code `unknown_parameter`, naming the key).
+     */
+    400: Error;
+    /**
+     * Authentication is missing or invalid.
+     */
+    401: Error;
+    /**
+     * The caller is not allowed to perform this action.
+     */
+    403: Error;
+    /**
+     * The resource does not exist or is not visible to the caller.
+     */
+    404: Error;
+    /**
+     * Too many requests for this API key or user (or, with failing
+     * credentials, this IP address). A published-only key is counted per
+     * client IP. Wait `Retry-After` seconds; retries with the same `Idempotency-Key`
+     * are safe.
+     *
+     */
+    429: Error;
+};
+export type RevisionsGetError = RevisionsGetErrors[keyof RevisionsGetErrors];
+export type RevisionsGetResponses = {
+    /**
+     * The revision with its snapshot and changes.
+     */
+    200: RecordRevisionDetail;
+};
+export type RevisionsGetResponse = RevisionsGetResponses[keyof RevisionsGetResponses];
 export type RecordRevisionsRevertData = {
     body?: never;
     headers?: {
@@ -5379,24 +5472,31 @@ export type AssetsGetResponses = {
     200: Asset;
 };
 export type AssetsGetResponse = AssetsGetResponses[keyof AssetsGetResponses];
-export type AssetsImageUrlData = {
-    body?: never;
-    path: {
-        asset_id: string;
-    };
-    query?: {
-        width?: number;
-        height?: number;
+export type AssetsUpdateData = {
+    body: AssetUpdate;
+    headers?: {
         /**
-         * `contain` fits inside width × height; `cover` fills it, cropping; `fill` stretches to it.
+         * A unique value (1-255 printable ASCII characters) that makes retrying
+         * this request safe. The first response (below 500) is stored for 24
+         * hours per user or API key; retries with the same key and the same
+         * request get it again with an `Idempotent-Replayed: true` header. The
+         * same key with a different request is refused with `400`; a retry while
+         * the first request is still running gets `409`.
+         *
+         */
+        'Idempotency-Key'?: string;
+        /**
+         * First-party client identifier recorded in history (e.g. `cli/0.3.1`). Informational only.
          */
-        fit?: 'contain' | 'cover' | 'fill';
-        format?: 'original' | 'webp' | 'avif' | 'jpeg' | 'png';
-        quality?: number;
+        'Nohead-Client'?: string;
+    };
+    path: {
+        asset_id: string;
     };
-    url: '/v1/assets/{asset_id}/image-url';
+    query?: never;
+    url: '/v1/assets/{asset_id}';
 };
-export type AssetsImageUrlErrors = {
+export type AssetsUpdateErrors = {
     /**
      * The request was malformed: unparseable JSON, an invalid query parameter, or a body key the operation doesn't take (detail code `unknown_parameter`, naming the key).
      */
@@ -5429,19 +5529,15 @@ export type AssetsImageUrlErrors = {
      *
      */
     429: Error;
-    /**
-     * The service is temporarily unavailable.
-     */
-    503: Error;
 };
-export type AssetsImageUrlError = AssetsImageUrlErrors[keyof AssetsImageUrlErrors];
-export type AssetsImageUrlResponses = {
+export type AssetsUpdateError = AssetsUpdateErrors[keyof AssetsUpdateErrors];
+export type AssetsUpdateResponses = {
     /**
-     * The image URL.
+     * The asset.
      */
-    200: ImageUrl;
+    200: Asset;
 };
-export type AssetsImageUrlResponse = AssetsImageUrlResponses[keyof AssetsImageUrlResponses];
+export type AssetsUpdateResponse = AssetsUpdateResponses[keyof AssetsUpdateResponses];
 export type AssetsDownloadUrlData = {
     body?: never;
     path: {

package/dist/images.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Image renditions without a request (`@nohead/sdk/images`). Image URLs are
+ * open: an image asset's `image_url` serves the whole image, and any of
+ * imgproxy's processing options written into it transform it
+ * (https://docs.imgproxy.net/usage/processing). No dependencies, so it suits
+ * browser bundles and frameworks' image components.
+ *
+ *   imageUrl(asset, { width: 800, height: 600, fit: "cover", format: "webp" })
+ */
+export interface ImageOptions {
+    width?: number;
+    height?: number;
+    /** `contain` fits inside the box (the default), `cover` fills it, cropping, `fill` stretches to it. */
+    fit?: "contain" | "cover" | "fill";
+    format?: "webp" | "avif" | "jpeg" | "png";
+    /** 1 to 100. */
+    quality?: number;
+    /** Pixel density: 2 for a 2x screen. */
+    dpr?: number;
+    /** What a crop keeps, as imgproxy's gravity: `sm` (smart), `ce`, `no`, or `fp:0.5:0.3` (a focal point). */
+    gravity?: string;
+    /** Any other processing options, as written in a URL: `["bl:2", "sh:0.5"]`. */
+    options?: string[];
+}
+/** An image asset, or its `image_url`. */
+export type ImageSource = string | {
+    image_url: string | null;
+};
+/** A rendition of an image: its `image_url` with these options. */
+export declare function imageUrl(image: ImageSource, options?: ImageOptions): string;
+/** Whether a URL is a Nohead image's: the loaders leave any other alone. */
+export declare function isImageUrl(src: unknown): src is string;
+/**
+ * A Next.js image loader. In a file named by `images.loaderFile` in
+ * next.config: `export { nextImageLoader as default } from "@nohead/sdk/images"`,
+ * then `<Image src={asset.image_url} width={…} height={…} alt={asset.alt} />`.
+ * Other images (the site's own) are left as they are.
+ */
+export declare function nextImageLoader({ src, width, quality, }: {
+    src: string;
+    width: number;
+    quality?: number;
+}): string;
+/**
+ * An Astro image service (an external one: Astro never fetches the image).
+ * In a module named by `image.service.entrypoint` in astro.config:
+ * `export { astroImageService as default } from "@nohead/sdk/images"`.
+ * Other images (the site's own, imported or remote) are served as they are.
+ */
+export declare const astroImageService: {
+    getURL(options: {
+        src: unknown;
+        width?: number;
+        height?: number;
+        format?: string;
+        quality?: number | string;
+        fit?: string;
+    }): string;
+};
+/**
+ * Nuxt Image's custom provider (`getImage`). In a file named as a provider
+ * in nuxt.config's `image.providers`: on Nuxt Image 2,
+ * `export { nuxtImageProvider as default } from "@nohead/sdk/images"`; on
+ * Nuxt Image 1, `export { getImage } from "@nohead/sdk/images"`. Other
+ * images are left as they are.
+ */
+export declare function getImage(src: string, { modifiers }?: {
+    modifiers?: Record<string, unknown>;
+}): {
+    url: string;
+};
+/** Nuxt Image 2's provider: what its `defineProvider({ getImage })` returns. */
+export declare const nuxtImageProvider: () => {
+    getImage: typeof getImage;
+};

package/dist/images.js

@@ -0,0 +1,113 @@
+/**
+ * Image renditions without a request (`@nohead/sdk/images`). Image URLs are
+ * open: an image asset's `image_url` serves the whole image, and any of
+ * imgproxy's processing options written into it transform it
+ * (https://docs.imgproxy.net/usage/processing). No dependencies, so it suits
+ * browser bundles and frameworks' image components.
+ *
+ *   imageUrl(asset, { width: 800, height: 600, fit: "cover", format: "webp" })
+ */
+const FITS = { contain: "fit", cover: "fill", fill: "force" };
+/** A rendition of an image: its `image_url` with these options. */
+export function imageUrl(image, options = {}) {
+    const base = typeof image === "string" ? image : image.image_url;
+    if (!base)
+        throw new TypeError("Not a ready image: it has no image_url");
+    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 ?? [])])
+        if (option && /[/@?#]/.test(option))
+            throw new TypeError(`Not an imgproxy option: ${option}`);
+    const segments = [];
+    if (width || height)
+        segments.push(`rs:${FITS[fit]}:${width ?? 0}:${height ?? 0}`);
+    if (gravity)
+        segments.push(`g:${gravity}`);
+    if (dpr)
+        segments.push(`dpr:${dpr}`);
+    if (quality)
+        segments.push(`q:${quality}`);
+    segments.push(...(options.options ?? []));
+    // The source comes last; a format replaces any the URL already names.
+    let source = base.slice(at);
+    if (format)
+        source = `${source.replace(/@[a-z]+$/, "")}@${format}`;
+    return `${base.slice(0, at)}${segments.map((s) => `/${s}`).join("")}${source}`;
+}
+/** Whether a URL is a Nohead image's: the loaders leave any other alone. */
+export function isImageUrl(src) {
+    return (typeof src === "string" && /^https?:\/\/[^/]+\/(.*\/)?plain\//.test(src));
+}
+/**
+ * A Next.js image loader. In a file named by `images.loaderFile` in
+ * next.config: `export { nextImageLoader as default } from "@nohead/sdk/images"`,
+ * then `<Image src={asset.image_url} width={…} height={…} alt={asset.alt} />`.
+ * Other images (the site's own) are left as they are.
+ */
+export function nextImageLoader({ src, width, quality, }) {
+    return isImageUrl(src) ? imageUrl(src, { width, quality }) : src;
+}
+const FORMATS = new Set(["webp", "avif", "jpeg", "png"]);
+// Astro's and Nuxt Image's fits, as imgproxy has them.
+const FRAMEWORK_FITS = {
+    cover: "cover",
+    contain: "contain",
+    fill: "fill",
+    inside: "contain",
+    outside: "cover",
+};
+const fitOf = (fit) => typeof fit === "string" ? FRAMEWORK_FITS[fit] : undefined;
+const formatOf = (format) => typeof format === "string" && FORMATS.has(format)
+    ? format
+    : undefined;
+/**
+ * An Astro image service (an external one: Astro never fetches the image).
+ * In a module named by `image.service.entrypoint` in astro.config:
+ * `export { astroImageService as default } from "@nohead/sdk/images"`.
+ * Other images (the site's own, imported or remote) are served as they are.
+ */
+export const astroImageService = {
+    getURL(options) {
+        const { src } = options;
+        if (!isImageUrl(src)) {
+            const own = typeof src === "string" ? src : src?.src;
+            return typeof own === "string" ? own : "";
+        }
+        return imageUrl(src, {
+            width: options.width,
+            height: options.height,
+            fit: fitOf(options.fit),
+            format: formatOf(options.format),
+            quality: typeof options.quality === "number" ? options.quality : undefined,
+        });
+    },
+};
+/**
+ * Nuxt Image's custom provider (`getImage`). In a file named as a provider
+ * in nuxt.config's `image.providers`: on Nuxt Image 2,
+ * `export { nuxtImageProvider as default } from "@nohead/sdk/images"`; on
+ * Nuxt Image 1, `export { getImage } from "@nohead/sdk/images"`. Other
+ * images are left as they are.
+ */
+export function getImage(src, { modifiers = {} } = {}) {
+    const number = (value) => typeof value === "number"
+        ? value
+        : typeof value === "string" && value
+            ? Number(value)
+            : undefined;
+    if (!isImageUrl(src))
+        return { url: src };
+    return {
+        url: imageUrl(src, {
+            width: number(modifiers.width),
+            height: number(modifiers.height),
+            fit: fitOf(modifiers.fit),
+            format: formatOf(modifiers.format),
+            quality: number(modifiers.quality),
+        }),
+    };
+}
+/** Nuxt Image 2's provider: what its `defineProvider({ getImage })` returns. */
+export const nuxtImageProvider = () => ({ getImage });

package/dist/resources/assets.d.ts

@@ -1,7 +1,7 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
 import type { RequestOptions } from "../core.ts";
-import type { Asset, AssetUploadCreate, AssetWithUpload, AssetUsage, DownloadUrl, ImageUrl } from "../generated/types.gen.ts";
-import type { AssetListParams, ImageUrlParams } from "../types.ts";
+import type { Asset, AssetUpdate, AssetUploadCreate, AssetWithUpload, AssetUsage, DownloadUrl } from "../generated/types.gen.ts";
+import type { AssetListParams } from "../types.ts";
 import { Resource } from "./resource.ts";
 /** What `assets.upload` accepts. A stream needs `byte_size`. */
 export type Uploadable = Blob | ArrayBuffer | Uint8Array | ReadableStream;
@@ -40,6 +40,13 @@ export declare class Assets extends Resource {
     complete(asset: string, options?: RequestOptions): APIPromise<Asset>;
     list({ content_type, ...params }?: AssetListParams, options?: RequestOptions): PagePromise<Asset>;
     get(asset: string, options?: RequestOptions): APIPromise<Asset>;
+    /**
+     * Renames the asset (`filename`) or sets its `alt` text (`null` or `""`
+     * clears it). The file itself can't change: upload a new asset for that.
+     * `alt` is the default wherever the asset is used. A deleted asset is a
+     * `ConflictError`: restore it first.
+     */
+    update(asset: string, params: AssetUpdate, options?: RequestOptions): APIPromise<Asset>;
     /**
      * Soft-deletes the asset: `restore` brings it back until its
      * `purge_after`, when the file is purged (or now, with `purge`).
@@ -60,8 +67,6 @@ export declare class Assets extends Resource {
      * updated with the fields that use it (`uses`). Needs `records:read` too.
      */
     usage(asset: string, options?: RequestOptions): APIPromise<AssetUsage>;
-    /** A signed, cacheable URL of an image rendition (`url`). */
-    imageUrl(asset: string, params?: ImageUrlParams, options?: RequestOptions): APIPromise<ImageUrl>;
-    /** A 15-minute link to download the original file (`url`). */
+    /** A link to download the original file (`url`), valid for 2 minutes. */
     downloadUrl(asset: string, options?: RequestOptions): APIPromise<DownloadUrl>;
 }

package/dist/resources/assets.js

@@ -87,6 +87,15 @@ export class Assets extends Resource {
     get(asset, options) {
         return this.core.request("assets_get", { path: { asset_id: asset } }, options);
     }
+    /**
+     * Renames the asset (`filename`) or sets its `alt` text (`null` or `""`
+     * clears it). The file itself can't change: upload a new asset for that.
+     * `alt` is the default wherever the asset is used. A deleted asset is a
+     * `ConflictError`: restore it first.
+     */
+    update(asset, params, options) {
+        return this.core.request("assets_update", { path: { asset_id: asset }, body: params }, options);
+    }
     /**
      * Soft-deletes the asset: `restore` brings it back until its
      * `purge_after`, when the file is purged (or now, with `purge`).
@@ -115,11 +124,7 @@ export class Assets extends Resource {
     usage(asset, options) {
         return this.core.request("assets_usage", { path: { asset_id: asset } }, options);
     }
-    /** A signed, cacheable URL of an image rendition (`url`). */
-    imageUrl(asset, params = {}, options) {
-        return this.core.request("assets_image_url", { path: { asset_id: asset }, query: params }, options);
-    }
-    /** A 15-minute link to download the original file (`url`). */
+    /** A link to download the original file (`url`), valid for 2 minutes. */
     downloadUrl(asset, options) {
         return this.core.request("assets_download_url", { path: { asset_id: asset } }, options);
     }

package/dist/resources/records.d.ts

@@ -12,8 +12,12 @@ export declare class Records extends Resource {
     /** A collection's records, newest first by default. */
     list<D = RecordData>(collection: string, params?: RecordListParams, options?: RequestOptions): PagePromise<NoheadRecord<D>>;
     get<D = RecordData>(record: string, params?: RecordGetParams, options?: RequestOptions): APIPromise<NoheadRecord<D>>;
-    /** Creates an unpublished record. */
-    create<D = RecordData>(collection: string, params: RecordCreateParams<D>, options?: WriteOptions): APIPromise<NoheadRecord<D>>;
+    /**
+     * Creates an unpublished record. With `upsert_on`, updates the record
+     * holding that unique value instead, if one exists, so a sync can run
+     * again without duplicates; `ifMatch` then applies to that update.
+     */
+    create<D = RecordData>(collection: string, params: RecordCreateParams<D>, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
     /** Sets the given fields (`null` clears one); others keep their values. */
     update<D = RecordData>(record: string, params: RecordUpdateParams<D>, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
     /**
@@ -63,7 +67,7 @@ export declare class Records extends Resource {
     /** The changes between two revisions. */
     diff(record: string, params: RecordDiffParams, options?: RequestOptions): APIPromise<RecordDiff>;
     /**
-     * Full-text search in one collection (`search_enabled` collections).
+     * Full-text search in one collection, matching its `searchable` fields.
      * Pages through the first 1,000 hits, most relevant first.
      */
     search<D = RecordData>(collection: string, query: string, params?: RecordSearchParams, options?: RequestOptions): PagePromise<NoheadRecord<D>, SearchMeta>;
@@ -79,3 +83,10 @@ export declare class Revisions extends Resource {
     }, options?: ConditionalWriteOptions): APIPromise<RevertPreview>;
     revert<D = RecordData>(record: string, revision: number, params?: DryRunParams, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
 }
+/**
+ * A revision by its own ID (`rev_…`), as webhooks and the activity log name
+ * it. Readable while its record is deleted.
+ */
+export declare class RevisionsById extends Resource {
+    get(revision: string, options?: RequestOptions): APIPromise<RecordRevisionDetail>;
+}

package/dist/resources/records.js

@@ -12,7 +12,11 @@ export class Records extends Resource {
     get(record, params = {}, options) {
         return this.core.request("records_get", { path: { record_id: record }, query: params }, options);
     }
-    /** Creates an unpublished record. */
+    /**
+     * Creates an unpublished record. With `upsert_on`, updates the record
+     * holding that unique value instead, if one exists, so a sync can run
+     * again without duplicates; `ifMatch` then applies to that update.
+     */
     create(collection, params, options) {
         return this.core.request("records_create", { path: { collection_id: collection }, body: params }, options);
     }
@@ -93,7 +97,7 @@ export class Records extends Resource {
         return this.core.request("records_diff", { path: { record_id: record }, query: params }, options);
     }
     /**
-     * Full-text search in one collection (`search_enabled` collections).
+     * Full-text search in one collection, matching its `searchable` fields.
      * Pages through the first 1,000 hits, most relevant first.
      */
     search(collection, query, params = {}, options) {
@@ -113,3 +117,12 @@ export class Revisions extends Resource {
         return this.core.request("record_revisions_revert", { path: { record_id: record, revision }, query: params }, options);
     }
 }
+/**
+ * A revision by its own ID (`rev_…`), as webhooks and the activity log name
+ * it. Readable while its record is deleted.
+ */
+export class RevisionsById extends Resource {
+    get(revision, options) {
+        return this.core.request("revisions_get", { path: { revision_id: revision } }, options);
+    }
+}

package/dist/types.d.ts

@@ -71,6 +71,11 @@ export interface RecordGetParams {
 }
 export interface RecordCreateParams<D = G.RecordData> {
     data: D;
+    /**
+     * The key of a `unique` field whose value `data` includes: the active
+     * record holding that value is updated instead, if there is one.
+     */
+    upsert_on?: string;
 }
 export interface RecordUpdateParams<D = G.RecordData> {
     data: RecordDataUpdate<D>;
@@ -169,7 +174,6 @@ export interface FieldReorderParams {
     /** Every active field of the collection, once each, in the new order. */
     field_ids: string[];
 }
-export type ImageUrlParams = NonNullable<G.AssetsImageUrlData["query"]>;
 export interface DeliveryListParams extends ListParams {
     status?: "pending" | "succeeded" | "failed";
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.6.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.5.0";
+export const VERSION = "0.6.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",
@@ -27,6 +27,10 @@
       "types": "./dist/webhooks.d.ts",
       "default": "./dist/webhooks.js"
     },
+    "./images": {
+      "types": "./dist/images.d.ts",
+      "default": "./dist/images.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [