@nohead/sdk 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.13.0
+
+- `@nohead/sdk/astro`: `noheadLoader`, a loader for Astro's content
+  collections (Astro 5.9 or later). It loads a collection's published records
+  as entries, by record ID, with rich text as HTML, expanded assets in place
+  of their IDs and relations kept as IDs for `reference()`; `body` renders a
+  rich text field for `render(entry)`.
+- **Breaking:** Astro's image service has its own entry point, which
+  astro.config names directly:
+  `image: { service: { entrypoint: "@nohead/sdk/astro/image-service" } }`.
+  `astroImageService` is gone from `@nohead/sdk/images`. The service now
+  builds on Astro's base service, so `<Image>` and `<Picture>` render `alt`,
+  `width`, `height`, `loading` and the `srcset` for `widths` and `densities`
+  (before, a bare `<img src>`). It serves WebP unless a `format` says
+  otherwise, and takes Astro's quality presets (`"high"`).
+- Nuxt Image's `format: "jpg"` gives a JPEG, as `"jpeg"` does, instead of
+  the image's own format.
+- `nextImageLoader` serves WebP, as Next.js's own optimizer would, where it
+  served each image in its own format (a JPEG at twice the size). A format
+  the URL names stays: `@svg` keeps an SVG a vector.
+- **Breaking:** Nuxt Image (and the Astro image service) crop to a box of
+  both sizes when no `fit` is given, as their own services do. They used to
+  fit the image inside it, so an image of another shape came back smaller
+  and the browser stretched it to the `<img>`'s width and height.
+
+## 0.12.0
+
+- `webhooks.create` and `webhooks.update` take `published_only`, and every
+  webhook has it: a published-only webhook sends only the events that change
+  what a published-only API key reads (a record published, unpublished or
+  edited while live, schema changes, changes to assets that published records
+  use), and skips drafts, schedules and edits to unpublished records.
+- Audit events have `note`: the change note (`Nohead-Change-Note`) a record
+  or schema change was made with, or `null`.
+
 ## 0.11.0
 
 - `records.diff` takes `richText`, and the client's `richText` now applies to

package/README.md

@@ -14,6 +14,8 @@ for await (const post of nohead.records.list("posts", {
 }
 ```
 
+The key is a project API key: create one under **API keys** in the [web app](https://app.nohead.io), with the **Read records** scope for this example, and set it as `NOHEAD_API_KEY` in your app's environment (or pass it as `apiKey`, under [Configuration](#configuration)). The SDK doesn't read the key that `nohead login` saves for the CLI: give your app a key of its own.
+
 > **Status:** 0.x until the Nohead API launches.
 
 ## Contents
@@ -29,6 +31,7 @@ for await (const post of nohead.records.list("posts", {
 - [Concurrency](#concurrency)
 - [Assets](#assets)
 - [Search](#search)
+- [Astro](#astro)
 - [Schema](#schema)
 - [Webhooks](#webhooks)
 - [Raw responses](#raw-responses)
@@ -55,20 +58,19 @@ const nohead = new Nohead({
 })
 ```
 
-| Option       | Default                 |                                                                                           |
-| ------------ | ----------------------- | ----------------------------------------------------------------------------------------- |
-| `apiKey`     | `NOHEAD_API_KEY`        | A project API key (`nohead_sk_…`, or `nohead_pk_…` when published-only). Required.        |
-| `baseUrl`    | `https://api.nohead.io` | For a proxy, or a mock server in tests.                                                   |
-| `projectId`  | the key's project       | Looked up once with `GET /v1/me` when omitted.                                            |
-| `maxRetries` | `2`                     | See [retries](#retries-and-idempotency).                                                  |
-| `timeout`    | `60000`                 | Milliseconds an attempt may go without progress. See [retries](#retries-and-idempotency). |
-| `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).                        |
-| `richText`   | `"document"`            | How rich text reads: `"html"` or `"markdown"`. See [rich text](#rich-text).               |
-
-An empty option counts as unset, as an empty environment variable does: `apiKey: ""` falls back to `NOHEAD_API_KEY`, and `baseUrl: ""` to `https://api.nohead.io`. The base URL comes only from `baseUrl`, never from the environment. A `baseUrl` that isn't an `http` or `https` URL throws.
+| Option       | Default            |                                                                                           |
+| ------------ | ------------------ | ----------------------------------------------------------------------------------------- |
+| `apiKey`     | `NOHEAD_API_KEY`   | A project API key (`nohead_sk_…`, or `nohead_pk_…` when published-only). Required.        |
+| `projectId`  | the key's project  | Looked up once with `GET /v1/me` when omitted.                                            |
+| `maxRetries` | `2`                | See [retries](#retries-and-idempotency).                                                  |
+| `timeout`    | `60000`            | Milliseconds an attempt may go without progress. See [retries](#retries-and-idempotency). |
+| `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).                        |
+| `richText`   | `"document"`       | How rich text reads: `"html"` or `"markdown"`. See [rich text](#rich-text).               |
+
+An empty option counts as unset, as an empty environment variable does: `apiKey: ""` falls back to `NOHEAD_API_KEY`.
 
 `withOptions` copies a client with another `timeout`, `maxRetries`, `onRetry` or `richText`, or more `headers` (added to the client's). The copy shares the key's project, so it doesn't look it up again:
 
@@ -223,7 +225,7 @@ Every error is a `NoheadError`. API errors are `APIError`s with `status`, `type`
 
 An API error's `message` names the status, the type and the request ID along with the API's message, so logging it is enough to look the request up: `422 validation_error: Title is required (request req_…)`. The API's own text is `apiMessage`, to show a person.
 
-The client follows no redirects: a `3xx` is an `APIError` (`type` `redirect`) that names where it pointed, which usually means the base URL is wrong.
+The client follows no redirects: a `3xx` is an `APIError` (`type` `redirect`) that names where it pointed.
 
 Other errors: `ConnectionError`, `TimeoutError` (a `ConnectionError`), `AbortError` (your `signal` fired), `UploadError` and `WebhookVerificationError`.
 
@@ -325,8 +327,8 @@ 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"`.
+- **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} … />`. It serves WebP, as Next.js's own optimizer does by default, unless the URL names a format (`@avif` for AVIF, which `images.formats` can't ask a loader for): ``src={`${asset.image_url}@svg`}`` keeps an SVG a vector.
+- **Astro:** `image: { service: { entrypoint: "@nohead/sdk/astro/image-service" } }` in astro.config, then `<Image src={asset.image_url} width={…} height={…} alt={…} />`. It serves WebP unless a `format` says otherwise: give an SVG `format="svg"` to keep it a vector (an asset's `content_type` tells). Pass `width` and `height`, which expanded assets carry; `inferSize` would need the image host in Astro's `image.domains`. Needs Astro 5.9 or later.
 - **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.
@@ -376,6 +378,75 @@ results.meta.total_estimate
 
 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.
 
+## Astro
+
+`@nohead/sdk/astro` loads collections into Astro's content collections (Astro 5.9 or later), so pages read them with `getCollection`, `getEntry`, `reference()` and `render()`:
+
+```ts
+// src/content.config.ts
+import { defineCollection, reference } from "astro:content"
+import { z } from "astro/zod"
+import { noheadLoader } from "@nohead/sdk/astro"
+
+// Astro reads .env into import.meta.env, not process.env.
+const apiKey = import.meta.env.NOHEAD_API_KEY
+const image = z.object({
+  image_url: z.string(),
+  width: z.number(),
+  height: z.number(),
+  alt: z.string().optional(),
+})
+
+export const collections = {
+  people: defineCollection({
+    loader: noheadLoader({ collection: "people", apiKey }),
+    schema: z.object({ name: z.string(), slug: z.string() }),
+  }),
+  posts: defineCollection({
+    loader: noheadLoader({
+      collection: "posts",
+      expand: ["cover"],
+      body: "body",
+      apiKey,
+    }),
+    schema: z.object({
+      title: z.string(),
+      slug: z.string(),
+      date: z.coerce.date(),
+      authors: z.array(reference("people")),
+      cover: image.optional(),
+    }),
+  }),
+}
+```
+
+```astro
+---
+// src/pages/posts/[slug].astro
+import { getCollection, render } from "astro:content"
+import { Image } from "astro:assets"
+
+export async function getStaticPaths() {
+  const posts = await getCollection("posts")
+  return posts.map((post) => ({ params: { slug: post.data.slug }, props: { post } }))
+}
+const { post } = Astro.props
+const { Content } = await render(post)
+const { cover } = post.data
+---
+{cover && <Image src={cover.image_url} width={cover.width} height={cover.height} alt={cover.alt ?? ""} />}
+<Content />
+```
+
+- **Entries.** Each record becomes an entry whose `id` is the record ID and whose `data` is its fields, checked by the collection's `schema`. Collections load when the site builds and when `astro dev` starts. Each load lists the whole collection, removes the entries of records that are gone, and skips records that haven't changed.
+- **Published only.** Only published records load, whatever the key may read, so a published-only key (`nohead_pk_…`) is enough. `filter` adds conditions (`{ featured: true }`); `filter: { published_at: undefined }` loads every record.
+- **Rich text** reads as HTML (or Markdown with `richText: "markdown"`). `body` names the field that `render(entry)` renders: it moves out of `data` into the entry's rendered content. As Markdown, it goes through Astro's own Markdown pipeline (your plugins, syntax highlighting, `headings`). A record can have several rich text fields and an entry renders one; the others stay in `data` as HTML, for `<Fragment set:html={post.data.summary} />`.
+- **Order.** Astro doesn't keep an order for a collection (from Astro 6, `getCollection` returns entries by ID), so sort what it returns: `posts.sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf())`.
+- **Relations** stay record IDs, for `reference("people")` and `getEntry`.
+- **Assets** named in `expand` replace their ID with the asset: `id`, `filename`, `content_type`, and when they have them `alt`, `width`, `height`, `image_url`, `file_url` and `media_url` (`EmbeddedAsset`). With the image service, `@nohead/sdk/astro/image-service` (under [Assets](#assets)), `<Image>` writes sizes and formats into the image's URL. An expanded relation becomes `{ id, data }`. An asset or record deleted since is left out, and so is an unpublished record, unless `filter` loads unpublished entries too.
+- **Empty fields** are left out of `data` rather than `null`, so `.optional()` fits them. Dates and times are strings: `z.coerce.date()` makes them `Date`s.
+- **The key** is `apiKey`, or `NOHEAD_API_KEY` from the environment; the other client options (`timeout`, `maxRetries`, `headers`) apply too. Astro keeps `.env` in `import.meta.env`, so pass the key from there as above.
+
 ## Schema
 
 ```ts

package/dist/astro-image-service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Astro's image service for Nohead images
+ * (`@nohead/sdk/astro/image-service`). In astro.config:
+ *
+ *   image: { service: { entrypoint: "@nohead/sdk/astro/image-service" } }
+ *
+ * then `<Image src={asset.image_url} width={…} height={…} alt={…} />`.
+ * `<Image>` and `<Picture>` write each size and format into the image's
+ * URL, and Nohead makes it on request, so the build never downloads or
+ * resizes an image. Astro's base service supplies the rest (the `<img>`
+ * attributes, `srcset` for `widths` and `densities`). WebP unless a
+ * `format` says otherwise. Other images (the site's own, imported or
+ * remote) are served as they are.
+ */
+import type { ExternalImageService } from "astro";
+declare const imageService: ExternalImageService;
+export default imageService;

package/dist/astro-image-service.js

@@ -0,0 +1,28 @@
+import { baseService } from "astro/assets";
+import { fitOf, formatOf, qualityOf } from "./frameworks.js";
+import { imageUrl, isImageUrl } from "./images.js";
+const imageService = {
+    getHTMLAttributes: baseService.getHTMLAttributes,
+    getSrcSet: baseService.getSrcSet,
+    async validateOptions(options, imageConfig, logger) {
+        const validated = await baseService.validateOptions(options, imageConfig, logger);
+        // So the srcset's <source type> says what the URLs serve.
+        if (isImageUrl(validated.src))
+            validated.format ??= "webp";
+        return validated;
+    },
+    getURL(options) {
+        const { src } = options;
+        // An imported image's metadata, or another URL.
+        if (!isImageUrl(src))
+            return typeof src === "string" ? src : src.src;
+        return imageUrl(src, {
+            width: options.width,
+            height: options.height,
+            fit: fitOf(options.fit, options.width, options.height),
+            format: formatOf(options.format ?? "webp"),
+            quality: qualityOf(options.quality),
+        });
+    },
+};
+export default imageService;

package/dist/astro.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Astro's content collections from Nohead (`@nohead/sdk/astro`). In
+ * src/content.config.ts:
+ *
+ *   import { defineCollection } from "astro:content"
+ *   import { noheadLoader } from "@nohead/sdk/astro"
+ *
+ *   export const collections = {
+ *     posts: defineCollection({
+ *       loader: noheadLoader({ collection: "posts", expand: ["cover"] }),
+ *     }),
+ *   }
+ *
+ * Every published record becomes an entry, by its record ID, when the site
+ * builds (and when `astro dev` starts or syncs).
+ */
+import type { Loader } from "astro/loaders";
+import { type ClientOptions } from "./core.ts";
+import type * as G from "./generated/types.gen.ts";
+import type { RecordFilter } from "./types.ts";
+export interface NoheadLoaderOptions extends ClientOptions {
+    /** The collection's slug or ID. */
+    collection: string;
+    /**
+     * Filters, added to the default `{ published_at: { exists: true } }`, so
+     * only published records load whatever the key may read. Set
+     * `published_at` to change that: `undefined` loads every record.
+     */
+    filter?: RecordFilter;
+    /**
+     * Asset (or relation) fields whose IDs to replace with what they point
+     * at: an asset as an `EmbeddedAsset`, a published record as an
+     * `EmbeddedRecord`. At most 5. Relations otherwise stay record IDs, for
+     * `reference()`.
+     */
+    expand?: string[];
+    /**
+     * A rich text field to render: it moves from `data` into the entry's
+     * `rendered`, so `render(entry)` returns its `<Content />`. As HTML (the
+     * default), or with `richText: "markdown"`, through Astro's Markdown
+     * pipeline (your remark and rehype plugins, syntax highlighting,
+     * headings).
+     */
+    body?: string;
+    /**
+     * How rich text fields read: `"html"` by default, strings ready for
+     * `set:html`, or `"markdown"`. The `"document"` form is the API's.
+     */
+    richText?: G.RichText;
+}
+/** An expanded asset field's value: what a page needs to show the file. */
+export interface EmbeddedAsset {
+    id: string;
+    filename: string;
+    content_type: string;
+    /** The asset's alt text, when it has some. */
+    alt?: string;
+    /** For images: their size, and their URL (see `@nohead/sdk/images`). */
+    width?: number;
+    height?: number;
+    image_url?: string;
+    /** The file as uploaded, for any ready asset. */
+    file_url?: string;
+    /** For video and audio: the URL that plays inline. */
+    media_url?: string;
+}
+/** An expanded relation field's value: the related record's ID and fields. */
+export interface EmbeddedRecord {
+    id: string;
+    data: Record<string, unknown>;
+}
+/**
+ * An Astro content loader for a Nohead collection. It reads the key from
+ * `apiKey` or `NOHEAD_API_KEY`, and takes the other client options too
+ * (`timeout`, `maxRetries`, `headers`…). Empty fields are left out of an
+ * entry's data, so a schema's `.optional()` fits them.
+ */
+export declare function noheadLoader(options: NoheadLoaderOptions): Loader;

package/dist/astro.js

@@ -0,0 +1,118 @@
+import { Nohead } from "./client.js";
+import { environment } from "./core.js";
+import { NoheadError } from "./errors.js";
+/**
+ * An Astro content loader for a Nohead collection. It reads the key from
+ * `apiKey` or `NOHEAD_API_KEY`, and takes the other client options too
+ * (`timeout`, `maxRetries`, `headers`…). Empty fields are left out of an
+ * entry's data, so a schema's `.optional()` fits them.
+ */
+export function noheadLoader(options) {
+    const { collection, filter, expand, body, richText = "html", ...client } = options;
+    if (!collection)
+        throw new TypeError("noheadLoader needs a collection");
+    if (body && richText === "document") {
+        throw new TypeError('noheadLoader renders its body from HTML or Markdown: set richText to "html" or "markdown"');
+    }
+    return {
+        name: "nohead",
+        async load(context) {
+            const { store, logger } = context;
+            // Astro reads .env into import.meta.env, not process.env.
+            if (!client.apiKey && !environment().NOHEAD_API_KEY) {
+                throw new NoheadError("Missing API key: pass `apiKey: import.meta.env.NOHEAD_API_KEY` to noheadLoader, or set NOHEAD_API_KEY in the environment");
+            }
+            const nohead = new Nohead({ ...client, richText });
+            const records = [];
+            for await (const record of nohead.records.list(collection, {
+                limit: 100,
+                filter: { published_at: { exists: true }, ...filter },
+                expand,
+            })) {
+                records.push(record);
+            }
+            // Embedded records are published too, unless entries may not be.
+            const publishedAt = filter && "published_at" in filter
+                ? filter.published_at
+                : { exists: true };
+            const publishedOnly = !(publishedAt === undefined || publishedAt.exists === false);
+            // Every entry is made before the store changes, so a failure leaves
+            // the entries as they were.
+            const entries = await Promise.all(records.map(async (record) => {
+                const data = entryData(record, publishedOnly);
+                const digest = context.generateDigest(data);
+                if (store.get(record.id)?.digest === digest)
+                    return undefined;
+                let rendered;
+                if (body !== undefined) {
+                    const value = data[body];
+                    delete data[body];
+                    if (typeof value === "string") {
+                        rendered =
+                            richText === "markdown"
+                                ? await context.renderMarkdown(value)
+                                : { html: value };
+                    }
+                }
+                const parsed = await context.parseData({ id: record.id, data });
+                return { id: record.id, data: parsed, digest, rendered };
+            }));
+            const ids = new Set(records.map((record) => record.id));
+            for (const id of store.keys())
+                if (!ids.has(id))
+                    store.delete(id);
+            for (const entry of entries)
+                if (entry)
+                    store.set(entry);
+            logger.info(`Loaded ${records.length} records from ${collection}`);
+        },
+    };
+}
+/**
+ * A record's fields as an entry's data: without empty values, and with each
+ * expanded asset or relation in place of its ID.
+ */
+function entryData(record, publishedOnly) {
+    const data = present(record.data);
+    // Gone since, or (as entries are) unpublished: left out.
+    const shown = (embedded) => embedded !== null &&
+        !(publishedOnly && embedded.object === "record" && !embedded.published_at);
+    for (const [key, embedded] of Object.entries(record.expanded ?? {})) {
+        const value = record.data[key];
+        // A rich text field's expansion (the assets its images show) is a list
+        // beside a single value: the field keeps its text.
+        if (Array.isArray(value) && Array.isArray(embedded)) {
+            data[key] = embedded.filter(shown).map(entryValue);
+        }
+        else if (typeof value === "string" && !Array.isArray(embedded)) {
+            if (shown(embedded))
+                data[key] = entryValue(embedded);
+            else
+                delete data[key];
+        }
+    }
+    return data;
+}
+function entryValue(embedded) {
+    if (embedded.object === "record") {
+        return { id: embedded.id, data: present(embedded.data) };
+    }
+    const { id, filename, content_type } = embedded;
+    return {
+        id,
+        filename,
+        content_type,
+        ...present({
+            alt: embedded.alt,
+            width: embedded.width,
+            height: embedded.height,
+            image_url: embedded.image_url,
+            file_url: embedded.file_url,
+            media_url: embedded.media_url,
+        }),
+    };
+}
+/** The values that are set: Zod's `.optional()` takes undefined, not null. */
+function present(values) {
+    return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== null && value !== undefined));
+}

package/dist/core.d.ts

@@ -149,4 +149,5 @@ export declare class Core {
  * ISO 8601.
  */
 export declare function appendQuery(params: URLSearchParams, value: unknown, key?: string): void;
+export declare function environment(): Record<string, string | undefined>;
 export {};

package/dist/core.js

@@ -436,7 +436,7 @@ function finiteNumbers(key, value) {
     }
     return value;
 }
-function environment() {
+export function environment() {
     const process = globalThis.process;
     return process?.env ?? {};
 }

package/dist/frameworks.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The fit asked for (an unknown one as `contain`, as Astro reads it), else
+ * `cover` for a box of both sizes, as Astro's and Nuxt Image's own services
+ * crop to it: an image fitted inside would be stretched to the <img>'s width
+ * and height.
+ */
+export declare const fitOf: (fit: unknown, width?: number, height?: number) => "fill" | "contain" | "cover" | undefined;
+/** Any other format (an SVG's `svg`) leaves the image in its own. */
+export declare const formatOf: (format: unknown) => "webp" | "avif" | "jpeg" | "png" | undefined;
+export declare const numberOf: (value: unknown) => number | undefined;
+export declare const qualityOf: (quality: unknown) => number | undefined;

package/dist/frameworks.js

@@ -0,0 +1,48 @@
+const FORMATS = {
+    webp: "webp",
+    avif: "avif",
+    jpeg: "jpeg",
+    jpg: "jpeg",
+    png: "png",
+};
+// Astro's and Nuxt Image's fits, as imgproxy has them.
+const FITS = {
+    cover: "cover",
+    contain: "contain",
+    fill: "fill",
+    inside: "contain",
+    outside: "cover",
+    "scale-down": "contain",
+};
+// Astro's quality presets, as its own services read them.
+const QUALITIES = {
+    low: 25,
+    mid: 50,
+    high: 80,
+    max: 100,
+};
+/**
+ * The fit asked for (an unknown one as `contain`, as Astro reads it), else
+ * `cover` for a box of both sizes, as Astro's and Nuxt Image's own services
+ * crop to it: an image fitted inside would be stretched to the <img>'s width
+ * and height.
+ */
+export const fitOf = (fit, width, height) => typeof fit === "string" && fit
+    ? Object.hasOwn(FITS, fit)
+        ? FITS[fit]
+        : "contain"
+    : width && height
+        ? "cover"
+        : undefined;
+/** Any other format (an SVG's `svg`) leaves the image in its own. */
+export const formatOf = (format) => typeof format === "string" && Object.hasOwn(FORMATS, format)
+    ? FORMATS[format]
+    : undefined;
+export const numberOf = (value) => typeof value === "number"
+    ? value
+    : typeof value === "string" && value
+        ? Number(value)
+        : undefined;
+export const qualityOf = (quality) => typeof quality === "string" && Object.hasOwn(QUALITIES, quality)
+    ? QUALITIES[quality]
+    : numberOf(quality);

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

@@ -1231,6 +1231,10 @@ export type WebhookProperties = {
      * The subscribed event types and wildcards (`record.*`, or `*` for all).
      */
     event_types: Array<WebhookSubscription>;
+    /**
+     * Send only events that change what a published-only API key can read: a record's change while it is published (or that publishes, unpublishes, deletes or restores it), schema changes, and changes to assets that published records use. Drafts, schedules, history redactions, uploads and purges are never sent. `webhook.test` always is.
+     */
+    published_only: boolean;
     enabled: boolean;
     /**
      * When the webhook was deleted; null unless it is.
@@ -1336,10 +1340,19 @@ export type AuditEvent = {
      * The client the change came through, when known.
      */
     via: null | Via;
+    /**
+     * The change note (`Nohead-Change-Note`) the change was made with,
+     * read from the revision or schema change the event references, so
+     * record and schema events have one when their change did; null
+     * otherwise, and once a revision's history is pruned.
+     *
+     */
+    note: string | null;
     /**
      * Small, action-specific references, e.g. `revision_id` and
      * `collection_id` for record events, `schema_change_id` for schema
-     * events, `changed` attribute names for updates. Never content.
+     * events, `changed` attribute names for updates (field keys for a
+     * draft's). Never content.
      *
      */
     metadata: {
@@ -1363,12 +1376,20 @@ export type WebhookCreate = {
     url: string;
     description?: string | null;
     event_types: Array<WebhookSubscription>;
+    /**
+     * Send only events that change what a published-only API key can read (`false` by default). It can't be combined with event types it never sends, such as `draft.*`.
+     */
+    published_only?: boolean;
     enabled?: boolean;
 };
 export type WebhookUpdate = {
     url?: string;
     description?: string | null;
     event_types?: Array<WebhookSubscription>;
+    /**
+     * Send only events that change what a published-only API key can read (`false` by default). It can't be combined with event types it never sends, such as `draft.*`.
+     */
+    published_only?: boolean;
     enabled?: boolean;
 };
 export type WebhookDeliveryProperties = {

package/dist/images.d.ts

@@ -1,12 +1,3 @@
-/**
- * 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;
@@ -34,6 +25,8 @@ 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} />`.
+ * As WebP, which Next.js's own optimizer would pick, unless the URL names a
+ * format: `${asset.image_url}@png`, or `@svg` to keep an SVG a vector.
  * Other images (the site's own) are left as they are.
  */
 export declare function nextImageLoader({ src, width, quality, }: {
@@ -41,22 +34,6 @@ export declare function nextImageLoader({ src, width, quality, }: {
     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,

package/dist/images.js

@@ -3,11 +3,15 @@
  * 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.
+ * browser bundles and frameworks' image components (Astro's image service is
+ * `@nohead/sdk/astro/image-service`).
  *
  *   imageUrl(asset, { width: 800, height: 600, fit: "cover", format: "webp" })
  */
+import { fitOf, formatOf, numberOf } from "./frameworks.js";
 const FITS = { contain: "fit", cover: "fill", fill: "force" };
+// The format an image URL names, after its source: `…@webp`.
+const FORMAT = /@[a-z]+$/;
 /** 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;
@@ -38,7 +42,7 @@ export function imageUrl(image, 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}`;
+        source = `${source.replace(FORMAT, "")}@${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. */
@@ -49,46 +53,17 @@ export function isImageUrl(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} />`.
+ * As WebP, which Next.js's own optimizer would pick, unless the URL names a
+ * format: `${asset.image_url}@png`, or `@svg` to keep an SVG a vector.
  * 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;
+    if (!isImageUrl(src))
+        return src;
+    // A loader is given no format: one the URL names stays.
+    const format = FORMAT.test(src) ? undefined : "webp";
+    return imageUrl(src, { width, quality, format });
 }
-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,
@@ -97,20 +72,17 @@ export const astroImageService = {
  * 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 };
+    const width = numberOf(modifiers.width);
+    const height = numberOf(modifiers.height);
     return {
         url: imageUrl(src, {
-            width: number(modifiers.width),
-            height: number(modifiers.height),
-            fit: fitOf(modifiers.fit),
+            width,
+            height,
+            fit: fitOf(modifiers.fit, width, height),
             format: formatOf(modifiers.format),
-            quality: number(modifiers.quality),
+            quality: numberOf(modifiers.quality),
         }),
     };
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.11.0";
+export declare const VERSION = "0.13.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.11.0";
+export const VERSION = "0.13.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",
@@ -31,6 +31,14 @@
       "types": "./dist/images.d.ts",
       "default": "./dist/images.js"
     },
+    "./astro": {
+      "types": "./dist/astro.d.ts",
+      "default": "./dist/astro.js"
+    },
+    "./astro/image-service": {
+      "types": "./dist/astro-image-service.d.ts",
+      "default": "./dist/astro-image-service.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -53,11 +61,20 @@
     "samples": "node scripts/samples.ts",
     "typecheck:smoke": "tsc -p smoke"
   },
+  "peerDependencies": {
+    "astro": ">=5.9.0"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@hey-api/openapi-ts": "0.99.0",
     "@types/node": "^26.6.4",
     "ajv": "^8.20.0",
+    "astro": "^7.4.7",
     "eslint": "^10.12.0",
     "globals": "^17.13.0",
     "prettier": "^3.9.9",