@nohead/sdk 0.4.0 → 0.6.0

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;
@@ -38,8 +38,15 @@ export declare class Assets extends Resource {
     createUpload(params: AssetUploadCreate, options?: RequestOptions): APIPromise<AssetWithUpload>;
     /** Checks an uploaded file and marks the asset `ready`. */
     complete(asset: string, options?: RequestOptions): APIPromise<Asset>;
-    list(params?: AssetListParams, options?: RequestOptions): PagePromise<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

@@ -74,12 +74,28 @@ export class Assets extends Resource {
     complete(asset, options) {
         return this.core.request("assets_complete", { path: { asset_id: asset } }, options);
     }
-    list(params = {}, options) {
-        return this.core.paginate("assets_list", { query: listQuery(params, ["deleted", "content_type"]) }, options);
+    list({ content_type, ...params } = {}, options) {
+        return this.core.paginate("assets_list", {
+            query: listQuery({
+                ...params,
+                content_type: Array.isArray(content_type)
+                    ? { in: content_type }
+                    : content_type,
+            }, ["deleted", "content_type"]),
+        }, options);
     }
     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`).
@@ -108,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/drafts.d.ts

@@ -19,11 +19,10 @@ export declare class Drafts extends Resource {
      */
     create<D = RecordData>(record: string, params?: DraftCreateParams<D>, options?: RequestOptions): APIPromise<NoheadDraft<D>>;
     /**
-     * A collection's drafts, most recently changed first. `record_id` narrows
-     * them to one record, or to several (1 to 100; an empty list is a
-     * `TypeError`, since it would match no record).
+     * A collection's drafts, most recently changed first. One record's draft
+     * is `records.drafts(record)`.
      */
-    list<D = RecordData>(collection: string, { record_id, ...params }?: DraftListParams, options?: RequestOptions): PagePromise<NoheadDraft<D>>;
+    list<D = RecordData>(collection: string, params?: DraftListParams, options?: RequestOptions): PagePromise<NoheadDraft<D>>;
     /** With `data` as the record reads after the merge, for previews. */
     get<D = RecordData>(draft: string, params?: DraftGetParams, options?: RequestOptions): APIPromise<NoheadDraft<D>>;
     /** Sets the given fields (`null` clears one), as a record update does. */

package/dist/resources/drafts.js

@@ -17,22 +17,11 @@ export class Drafts extends Resource {
         return this.core.request("drafts_create", { path: { record_id: record }, body: params }, options);
     }
     /**
-     * A collection's drafts, most recently changed first. `record_id` narrows
-     * them to one record, or to several (1 to 100; an empty list is a
-     * `TypeError`, since it would match no record).
+     * A collection's drafts, most recently changed first. One record's draft
+     * is `records.drafts(record)`.
      */
-    list(collection, { record_id, ...params } = {}, options) {
-        if (Array.isArray(record_id) && record_id.length === 0)
-            throw new TypeError("record_id needs at least one record ID");
-        const filter = record_id === undefined
-            ? undefined
-            : {
-                record_id: Array.isArray(record_id) ? { in: record_id } : record_id,
-            };
-        return this.core.paginate("drafts_list", {
-            path: { collection_id: collection },
-            query: { ...params, ...(filter && { filter }) },
-        }, options);
+    list(collection, params = {}, options) {
+        return this.core.paginate("drafts_list", { path: { collection_id: collection }, query: params }, options);
     }
     /** With `data` as the record reads after the merge, for previews. */
     get(draft, params = {}, 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/resources/schema.d.ts

@@ -1,7 +1,7 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
 import type { RequestOptions, WriteOptions } from "../core.ts";
 import type { Collection, FieldOrder, CollectionCreate, CollectionUpdate, Field, FieldCreate, FieldMigration, FieldMigrationPreview, FieldUpdate, Schema, SchemaChange, SchemaChangeDetail, SearchIndex } from "../generated/types.gen.ts";
-import type { DeletedListParams, DryRunParams, FieldMigrateParams, FieldReorderParams, ListParams, SchemaParams } from "../types.ts";
+import type { DeletedListParams, DryRunParams, FieldReorderParams, ListParams, MigrationCreateParams, SchemaParams } from "../types.ts";
 import { Resource } from "./resource.ts";
 /** Collections of the key's project. `collection` is an ID or slug. */
 export declare class Collections extends Resource {
@@ -39,7 +39,7 @@ export declare class Fields extends Resource {
     get(field: string, options?: RequestOptions): APIPromise<Field>;
     /**
      * Renames, describes or loosens a field. Changes that rewrite record
-     * values (type, `multiple`, tighter rules) are `migrate`.
+     * values (type, `multiple`, tighter rules) are `migrations.create`.
      */
     update(field: string, params: FieldUpdate, options?: WriteOptions): APIPromise<Field>;
     /**
@@ -54,17 +54,18 @@ export declare class Fields extends Resource {
     reorder(collection: string, params: FieldReorderParams, options?: WriteOptions): APIPromise<FieldOrder>;
     /** Stops accepting a renamed field's old API key before its 6 months end. */
     removeAlias(field: string, alias: string, options?: RequestOptions): APIPromise<Field>;
+}
+/** Field migrations. While one runs, its collection is read-only. */
+export declare class Migrations extends Resource {
     /**
-     * Starts a field migration (type, `multiple`, tighter configuration or a
-     * backfill) that rewrites every record. With `dry_run`, previews it.
+     * Starts a migration of one of the collection's fields (`field_id`): a
+     * type, `multiple`, tighter configuration or a backfill, which rewrites
+     * every record. With `dry_run`, previews it.
      */
-    migrate(field: string, params: FieldMigrateParams & {
+    create(collection: string, params: MigrationCreateParams & {
         dry_run: true;
     }, options?: WriteOptions): APIPromise<FieldMigrationPreview>;
-    migrate(field: string, params: FieldMigrateParams & DryRunParams, options?: WriteOptions): APIPromise<FieldMigration>;
-}
-/** Field migrations. While one runs, its collection is read-only. */
-export declare class Migrations extends Resource {
+    create(collection: string, params: MigrationCreateParams & DryRunParams, options?: WriteOptions): APIPromise<FieldMigration>;
     list(collection: string, params?: ListParams, options?: RequestOptions): PagePromise<FieldMigration>;
     get(migration: string, options?: RequestOptions): APIPromise<FieldMigration>;
     cancel(migration: string, options?: RequestOptions): APIPromise<FieldMigration>;

package/dist/resources/schema.js

@@ -66,7 +66,7 @@ export class Fields extends Resource {
     }
     /**
      * Renames, describes or loosens a field. Changes that rewrite record
-     * values (type, `multiple`, tighter rules) are `migrate`.
+     * values (type, `multiple`, tighter rules) are `migrations.create`.
      */
     update(field, params, options) {
         return this.core.request("fields_update", { path: { field_id: field }, body: params }, options);
@@ -93,12 +93,12 @@ export class Fields extends Resource {
     removeAlias(field, alias, options) {
         return this.core.request("fields_remove_alias", { path: { field_id: field, alias } }, options);
     }
-    migrate(field, { dry_run, ...body }, options) {
-        return this.core.request("fields_migrate", { path: { field_id: field }, query: { dry_run }, body }, options);
-    }
 }
 /** Field migrations. While one runs, its collection is read-only. */
 export class Migrations extends Resource {
+    create(collection, { dry_run, ...body }, options) {
+        return this.core.request("migrations_create", { path: { collection_id: collection }, query: { dry_run }, body }, options);
+    }
     list(collection, params = {}, options) {
         return this.core.paginate("migrations_list", { path: { collection_id: collection }, query: params }, 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>;
@@ -88,8 +93,6 @@ export interface DraftGetParams {
     expand?: string[];
 }
 export interface DraftListParams extends ListParams {
-    /** One record's draft, or several records' (up to 100). */
-    record_id?: string | string[];
     sort?: "updated_at" | "-updated_at";
 }
 export interface DraftScheduleParams {
@@ -155,9 +158,9 @@ export interface DeletedListParams extends ListParams {
 }
 export interface AssetListParams extends DeletedListParams {
     /**
-     * Only assets of these MIME types or `type/*` wildcards, e.g.
-     * `["image/*", "application/pdf"]`, such as an asset field's
-     * `accepted_types`.
+     * Only assets of a MIME type or `type/*` wildcard (`"image/*"`), or of any
+     * of several: `["image/*", "application/pdf"]`, such as an asset
+     * field's `accepted_types`.
      */
     content_type?: string | string[];
 }
@@ -165,12 +168,12 @@ export interface SchemaParams {
     /** A past schema version; the current one otherwise. */
     version?: number;
 }
-export type FieldMigrateParams = G.FieldMigrationRequest;
+/** `field_id`, one of the collection's fields, and the parts of its definition to change. */
+export type MigrationCreateParams = G.FieldMigrationRequest;
 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";
 }
@@ -188,7 +191,8 @@ export interface AuditEventFilter {
 }
 export interface AuditEventListParams extends ListParams {
     filter?: AuditEventFilter;
-    sort?: "id" | "-id";
+    /** Newest first by default (`-created_at`). */
+    sort?: "created_at" | "-created_at";
 }
 /** The metadata of a search page: also an estimate of the total hits. */
 export type SearchMeta = G.SearchResults["meta"];

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.4.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": [