@nohead/sdk 0.5.0 → 0.7.0

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;
@@ -13,7 +13,6 @@ export interface UploadParams {
     /** Required for a `ReadableStream`; known for everything else. */
     byte_size?: number;
 }
-/** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 export declare class Assets extends Resource {
     /**
      * Uploads a file and returns the `ready` asset: creates the upload, sends
@@ -28,6 +27,9 @@ export declare class Assets extends Resource {
      *
      *   import { openAsBlob } from "node:fs"
      *   const asset = await nohead.assets.upload(await openAsBlob("a.jpg"), { filename: "a.jpg" })
+     *
+     * Without `content_type`, the type is the Blob's, or else the filename's
+     * extension's for common files.
      */
     upload(file: Uploadable, params?: UploadParams, options?: RequestOptions): Promise<Asset>;
     /**
@@ -38,8 +40,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({ content_type, ...params }?: AssetListParams, options?: RequestOptions): PagePromise<Asset>;
+    list({ content_type, kind, ...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 +69,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

@@ -1,6 +1,31 @@
 import { AbortError, UploadError } from "../errors.js";
 import { listQuery, Resource } from "./resource.js";
 /** Files of the key's project. `asset` is an asset ID (`ast_…`). */
+/** Common files' types by extension, as the other SDKs guess them. */
+const CONTENT_TYPES = {
+    avif: "image/avif",
+    gif: "image/gif",
+    jpeg: "image/jpeg",
+    jpg: "image/jpeg",
+    png: "image/png",
+    svg: "image/svg+xml",
+    webp: "image/webp",
+    pdf: "application/pdf",
+    json: "application/json",
+    txt: "text/plain",
+    md: "text/markdown",
+    csv: "text/csv",
+    mp3: "audio/mpeg",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    zip: "application/zip",
+};
+function contentTypeOf(filename) {
+    const dot = filename.lastIndexOf(".");
+    return dot > 0
+        ? CONTENT_TYPES[filename.slice(dot + 1).toLowerCase()]
+        : undefined;
+}
 export class Assets extends Resource {
     /**
      * Uploads a file and returns the `ready` asset: creates the upload, sends
@@ -15,19 +40,28 @@ export class Assets extends Resource {
      *
      *   import { openAsBlob } from "node:fs"
      *   const asset = await nohead.assets.upload(await openAsBlob("a.jpg"), { filename: "a.jpg" })
+     *
+     * Without `content_type`, the type is the Blob's, or else the filename's
+     * extension's for common files.
      */
     async upload(file, params = {}, options) {
         const byteSize = params.byte_size ?? sizeOf(file);
         if (byteSize === undefined) {
             throw new UploadError("Uploading a stream needs `byte_size`");
         }
+        const filename = params.filename ??
+            (typeof File !== "undefined" && file instanceof File
+                ? file.name
+                : "upload");
         const { upload, ...asset } = await this.createUpload({
-            filename: params.filename ??
-                (typeof File !== "undefined" && file instanceof File
-                    ? file.name
-                    : "upload"),
+            filename,
+            // The Blob's own type, or one the filename's extension implies (a
+            // Blob from Node's openAsBlob has none), as the Python and Ruby
+            // SDKs do.
             content_type: params.content_type ??
-                ((file instanceof Blob && file.type) || "application/octet-stream"),
+                ((file instanceof Blob && file.type) ||
+                    contentTypeOf(filename) ||
+                    "application/octet-stream"),
             byte_size: byteSize,
         }, options);
         // A replayed start returns the first run's asset, which may be done.
@@ -74,19 +108,29 @@ export class Assets extends Resource {
     complete(asset, options) {
         return this.core.request("assets_complete", { path: { asset_id: asset } }, options);
     }
-    list({ content_type, ...params } = {}, options) {
+    list({ content_type, kind, ...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"]),
+                kind: Array.isArray(kind) ? { in: kind } : kind,
+            }, ["deleted", "content_type", "kind"]),
         }, 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`).
@@ -115,11 +159,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>>;
     /**
@@ -49,9 +53,9 @@ export declare class Records extends Resource {
     /** Clears both scheduled times. */
     unschedule(record: string, options?: RequestOptions): APIPromise<RecordSchedule>;
     /**
-     * A collection's pending scheduled publishes and unpublishes, soonest
-     * first: one per change, so a record due to publish and later unpublish
-     * appears twice.
+     * A collection's pending scheduled changes, soonest first: publishes,
+     * unpublishes and draft merges, one per change, so a record due to publish
+     * and later unpublish appears twice.
      */
     scheduledChanges(collection: string, params?: ScheduledChangeListParams, options?: RequestOptions): PagePromise<ScheduledChange>;
     count(collection: string, params?: RecordCountParams, options?: RequestOptions): APIPromise<RecordCount>;
@@ -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);
     }
@@ -71,9 +75,9 @@ export class Records extends Resource {
         return this.core.request("records_unschedule", { path: { record_id: record } }, options);
     }
     /**
-     * A collection's pending scheduled publishes and unpublishes, soonest
-     * first: one per change, so a record due to publish and later unpublish
-     * appears twice.
+     * A collection's pending scheduled changes, soonest first: publishes,
+     * unpublishes and draft merges, one per change, so a record due to publish
+     * and later unpublish appears twice.
      */
     scheduledChanges(collection, params = {}, options) {
         return this.core.paginate("scheduled_changes_list", { path: { collection_id: collection }, query: 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>;
@@ -152,6 +157,17 @@ export interface DeletedListParams extends ListParams {
     deleted?: boolean;
 }
 export interface AssetListParams extends DeletedListParams {
+    /**
+     * Words that must each appear in the filename or the alt text, ignoring
+     * case: `"hero jpg"` finds `Hero-banner.jpg`.
+     */
+    q?: string;
+    /**
+     * Only assets of a kind, or of any of several: `"image"`, `"video"` and
+     * `"audio"` by their types, `"document"` for PDFs, text and office files,
+     * `"other"` for every other file.
+     */
+    kind?: G.AssetKind | G.AssetKind[];
     /**
      * Only assets of a MIME type or `type/*` wildcard (`"image/*"`), or of any
      * of several: `["image/*", "application/pdf"]`, such as an asset
@@ -169,7 +185,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.7.0";

package/dist/version.js

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

package/package.json

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