@nohead/sdk 0.4.0 → 0.6.0

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;
@@ -683,9 +690,13 @@ export type FieldDefinition = {
     required: boolean;
 };
 /**
- * The parts of the definition to change; omitted parts stay as they are.
+ * The field, and the parts of its definition to change; omitted parts stay as they are.
  */
 export type FieldMigrationRequest = {
+    /**
+     * One of the collection's fields (`422` otherwise).
+     */
+    field_id: string;
     type?: FieldType;
     /**
      * The complete new configuration. When the type changes and this is omitted, only `description`, `searchable`, `filterable` and `sortable` carry over.
@@ -870,9 +881,9 @@ export type TimeFilter = {
     lt?: string;
 };
 /**
- * The client a change came through; `scheduler` for scheduled changes. `import` and `migration` are not sent yet.
+ * The client a change came through; `scheduler` for scheduled changes.
  */
-export type Via = 'ui' | 'api' | 'cli' | 'sdk' | 'import' | 'migration' | '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
@@ -1018,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;
@@ -1136,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).
      */
@@ -1153,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 = {
@@ -1365,16 +1388,16 @@ export type WebhookEventPayload = {
     created_at: Timestamp;
     project_id: string;
     /**
-     * Who made the change. Always sent.
+     * Who made the change.
      */
-    actor?: Actor;
+    actor: Actor;
     /**
-     * The client the change came through (null when not known). Always
-     * sent. An integration that writes back can skip changes made with its own
-     * API key (`actor`).
+     * The client the change came through (null when not known). An
+     * integration that writes back can skip changes made with its own API
+     * key (`actor`).
      *
      */
-    via?: null | Via;
+    via: null | Via;
     data: RecordEventData | DraftEventData | AssetEventData | SchemaEventData | FieldAliasEventData | WebhookTestEventData;
 };
 /**
@@ -1457,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;
     /**
@@ -1485,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;
@@ -1496,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;
@@ -1628,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.
  */
@@ -1700,7 +1741,7 @@ export type RecordRevisionFilter = {
     actor_id?: string;
     created_at?: TimeFilter;
 };
-export type AuditEventSort = 'id' | '-id';
+export type AuditEventSort = 'created_at' | '-created_at';
 /**
  * Page size.
  */
@@ -1717,14 +1758,20 @@ export type DeletedFilter = {
 };
 /**
  * `filter[deleted]=true` lists deleted assets instead.
- * `filter[content_type]` lists only assets of those types: comma-separated
- * MIME types or `type*` wildcards, for example the ones an asset field
- * accepts (its `accepted_types`).
+ * `filter[content_type]` lists only assets of a type: a MIME type or a
+ * `type*` wildcard, or several with
+ * `filter[content_type][in]=image*,application/pdf`, for example the
+ * ones an asset field accepts (its `accepted_types`).
  *
  */
 export type AssetFilter = {
     deleted?: 'true' | 'false';
-    content_type?: string;
+    content_type?: string | {
+        /**
+         * Up to 50 comma-separated MIME types or `type*` wildcards.
+         */
+        in: string;
+    };
 };
 /**
  * The revision you last read (the record's, or the draft's for a draft), e.g. `"7"`. Stale writes fail with 412.
@@ -1794,8 +1841,8 @@ export type RecordsListData = {
             [key: string]: RecordFilterValue;
         };
         /**
-         * `id`, `created_at`, `updated_at`, `published_at` (unpublished
-         * records first), or the key of a text, number, boolean, date or
+         * `created_at`, `updated_at`, `published_at` (unpublished records
+         * first), or the key of a text, number, boolean, date or
          * enum field with one value (records without a value last, in both
          * directions; text by code point). `-` for descending.
          *
@@ -1851,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
@@ -1863,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.
          */
@@ -1914,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.
      */
@@ -1929,6 +1986,10 @@ export type RecordsCreateErrors = {
 };
 export type RecordsCreateError = RecordsCreateErrors[keyof RecordsCreateErrors];
 export type RecordsCreateResponses = {
+    /**
+     * The record.
+     */
+    200: Record;
     /**
      * The created record.
      */
@@ -2932,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?: {
@@ -3195,14 +3298,6 @@ export type DraftsListData = {
         collection_id: string;
     };
     query?: {
-        filter?: {
-            record_id?: string | {
-                /**
-                 * Up to 100 comma-separated record IDs.
-                 */
-                in: string;
-            };
-        };
         sort?: 'updated_at' | '-updated_at';
         /**
          * Page size.
@@ -4878,7 +4973,7 @@ export type MigrationsListResponses = {
     200: FieldMigrationList;
 };
 export type MigrationsListResponse = MigrationsListResponses[keyof MigrationsListResponses];
-export type FieldsMigrateData = {
+export type MigrationsCreateData = {
     body: FieldMigrationRequest;
     headers?: {
         /**
@@ -4907,14 +5002,17 @@ export type FieldsMigrateData = {
         'Nohead-Change-Note'?: string;
     };
     path: {
-        field_id: string;
+        /**
+         * Collection ID, or the collection slug when authenticating with an API key.
+         */
+        collection_id: string;
     };
     query?: {
         dry_run?: boolean;
     };
-    url: '/v1/fields/{field_id}/migrations';
+    url: '/v1/collections/{collection_id}/migrations';
 };
-export type FieldsMigrateErrors = {
+export type MigrationsCreateErrors = {
     /**
      * 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).
      */
@@ -4948,8 +5046,8 @@ export type FieldsMigrateErrors = {
      */
     429: Error;
 };
-export type FieldsMigrateError = FieldsMigrateErrors[keyof FieldsMigrateErrors];
-export type FieldsMigrateResponses = {
+export type MigrationsCreateError = MigrationsCreateErrors[keyof MigrationsCreateErrors];
+export type MigrationsCreateResponses = {
     /**
      * A preview (dry runs only).
      */
@@ -4959,7 +5057,7 @@ export type FieldsMigrateResponses = {
      */
     202: FieldMigration;
 };
-export type FieldsMigrateResponse = FieldsMigrateResponses[keyof FieldsMigrateResponses];
+export type MigrationsCreateResponse = MigrationsCreateResponses[keyof MigrationsCreateResponses];
 export type MigrationsGetData = {
     body?: never;
     path: {
@@ -5080,14 +5178,20 @@ export type AssetsListData = {
         cursor?: string;
         /**
          * `filter[deleted]=true` lists deleted assets instead.
-         * `filter[content_type]` lists only assets of those types: comma-separated
-         * MIME types or `type*` wildcards, for example the ones an asset field
-         * accepts (its `accepted_types`).
+         * `filter[content_type]` lists only assets of a type: a MIME type or a
+         * `type*` wildcard, or several with
+         * `filter[content_type][in]=image*,application/pdf`, for example the
+         * ones an asset field accepts (its `accepted_types`).
          *
          */
         filter?: {
             deleted?: 'true' | 'false';
-            content_type?: string;
+            content_type?: string | {
+                /**
+                 * Up to 50 comma-separated MIME types or `type*` wildcards.
+                 */
+                in: string;
+            };
         };
     };
     url: '/v1/projects/{project_id}/assets';
@@ -5368,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?: {
+        /**
+         * 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;
         /**
-         * `contain` fits inside width × height; `cover` fills it, cropping; `fill` stretches to it.
+         * 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).
      */
@@ -5418,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: {
@@ -6725,7 +6832,7 @@ export type AuditEventsListData = {
             actor_id?: string;
             created_at?: TimeFilter;
         };
-        sort?: 'id' | '-id';
+        sort?: 'created_at' | '-created_at';
     };
     url: '/v1/projects/{project_id}/audit-events';
 };

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;
+};