@nohead/sdk 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.7.0
+
+- `assets.list({ q, kind })`: `q` finds assets whose filename or alt text
+  has every word, ignoring case; `kind` lists only `image`, `video`,
+  `audio`, `document` or `other` assets, or several kinds as a list.
+
+- `assets.upload` types a file by its filename's extension when the Blob has
+  no type, as Node's `openAsBlob` makes them: `cover.jpg` is now an
+  `image/jpeg` asset, not `application/octet-stream`.
+
+## 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, AssetKind, 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";