@nohead/sdk 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.14.0
+
+- `noheadLoader` gives each collection its schema and TypeScript type, from
+  the collection's fields in Nohead (Astro 6 or later, through its
+  `createSchema`), so `defineCollection({ loader: noheadLoader(…) })` is
+  typed without a hand-written Zod schema. Relations are `reference()`s to
+  the collection named like their target's slug, dates are `Date`s, and
+  expanded assets and relations are `EmbeddedAsset`s and `EmbeddedRecord`s.
+  It takes the key's `schema:read` scope. A `schema` given to
+  `defineCollection` still takes its place.
+- The Astro image service takes defaults for every image from its `config`
+  in astro.config: `quality` and `format`. An image's own options win.
+
+## 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

package/README.md

@@ -31,6 +31,7 @@ The key is a project API key: create one under **API keys** in the [web app](htt
 - [Concurrency](#concurrency)
 - [Assets](#assets)
 - [Search](#search)
+- [Astro](#astro)
 - [Schema](#schema)
 - [Webhooks](#webhooks)
 - [Raw responses](#raw-responses)
@@ -57,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:
 
@@ -225,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`.
 
@@ -327,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`. Defaults for every image go in the service's `config`, and an image's own options win: `service: { entrypoint: "@nohead/sdk/astro/image-service", config: { quality: 70 } }` (`format` too). 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.
@@ -378,6 +378,89 @@ 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()`. On Astro 6 or later, the loader also gives each collection its schema and TypeScript type, from the collection's fields in Nohead (on Astro 5, give each collection a `schema`, under [Schema and types](#schema-and-types)):
+
+```ts
+// src/content.config.ts
+import { defineCollection } from "astro:content"
+import { noheadLoader } from "@nohead/sdk/astro"
+
+// Astro reads .env into import.meta.env, not process.env.
+const apiKey = import.meta.env.NOHEAD_API_KEY
+
+export const collections = {
+  people: defineCollection({
+    loader: noheadLoader({ collection: "people", apiKey }),
+  }),
+  posts: defineCollection({
+    loader: noheadLoader({
+      collection: "posts",
+      expand: ["cover"],
+      body: "body",
+      apiKey,
+    }),
+  }),
+}
+```
+
+```astro
+---
+// src/pages/posts/[slug].astro
+import { getCollection, getEntry, 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 // post.data.title: string, post.data.date: Date
+const { Content } = await render(post)
+const authors = await Promise.all(post.data.authors.map((author) => getEntry(author)))
+const { cover } = post.data // an image field's assets have their URL and size
+---
+<h1>{post.data.title}</h1>
+<p>By {authors.map((author) => author?.data.name).join(" and ")}</p>
+{cover && <Image src={cover.image_url!} width={cover.width!} height={cover.height!} alt={cover.alt ?? ""} />}
+<Content />
+```
+
+### Schema and types
+
+Before, each collection repeated its fields as a Zod schema:
+
+```ts
+posts: defineCollection({
+  loader: noheadLoader({ collection: "posts", expand: ["cover"], body: "body", apiKey }),
+  schema: z.object({
+    title: z.string(),
+    date: z.coerce.date(),
+    authors: z.array(reference("people")),
+    cover: z.object({ image_url: z.string(), width: z.number(), height: z.number() }).optional(),
+    // …and every other field
+  }),
+}),
+```
+
+Now the loader reads the collection's fields when Astro syncs (`astro dev`, `astro build`, `astro sync`) and writes both the schema and the type, so `getCollection("posts")` is typed with none of that:
+
+- Text fields are strings; integers and decimals, numbers; dates, `Date`s; enums, their options; booleans, `boolean` (`false` when unset); JSON, `unknown`. A multiple field is an array.
+- A required field is required, others optional. An expanded asset or relation is always optional, since one deleted or unpublished since is left out.
+- A relation is a `reference()` to the Astro collection named like its target's slug, so name your collections after their slugs, and define one for every target that relations point to (`categories` for a post's `category`), or `getEntry` has nothing to find. Expanded, it is an `EmbeddedRecord`, and an expanded asset an `EmbeddedAsset`. An asset that isn't expanded stays its ID.
+- The `body` field isn't in the data: `render(entry)` has it.
+- The schema takes the key's `schema:read` scope, which published-only keys can have; without it the sync fails and says so.
+- A `schema` given to `defineCollection` takes its place, as in any Astro loader. Use one to transform values, or on Astro 5, which doesn't ask loaders for a schema.
+
+- **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. Without the loader's schema, 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,29 @@
+/**
+ * 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.
+ *
+ * Defaults for every image go in the service's `config`, and an image's own
+ * `quality` or `format` wins:
+ *
+ *   service: { entrypoint: "@nohead/sdk/astro/image-service", config: { quality: 70 } }
+ */
+import type { ExternalImageService } from "astro";
+/** The service's `config` in astro.config: defaults for every image. */
+export interface ImageServiceConfig {
+    /** 1 to 100, or one of Astro's presets (`"high"` is 80). */
+    quality?: number | "low" | "mid" | "high" | "max";
+    /** `"webp"` unless set. */
+    format?: "webp" | "avif" | "jpeg" | "jpg" | "png";
+}
+declare const imageService: ExternalImageService<ImageServiceConfig>;
+export default imageService;

package/dist/astro-image-service.js

@@ -0,0 +1,32 @@
+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)) {
+            // A Picture's <source type> needs `jpeg`, not `jpg`.
+            validated.format ??=
+                formatOf(imageConfig?.service?.config?.format) ?? "webp";
+        }
+        return validated;
+    },
+    getURL(options, imageConfig) {
+        const defaults = imageConfig?.service?.config;
+        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 ?? defaults?.format ?? "webp"),
+            quality: qualityOf(options.quality ?? defaults?.quality),
+        });
+    },
+};
+export default imageService;

package/dist/astro-schema.d.ts

@@ -0,0 +1,20 @@
+import type * as Zod from "astro/zod";
+import type * as G from "./generated/types.gen.ts";
+import type { RichText } from "./types.ts";
+type Z = typeof Zod.z;
+type Schema = Zod.ZodType;
+export interface SchemaOptions {
+    /** Fields whose IDs the loader replaces with what they point at. */
+    expand: string[];
+    /** The rich text field that moves to `rendered`, out of the data. */
+    body: string | undefined;
+    richText: RichText;
+    /** Collection slugs by ID, for relations' targets. */
+    slugs: Map<string, string>;
+}
+/** The schema and the `Entry` type (a module, as Astro writes it) of the data. */
+export declare function collectionSchema(z: Z, collection: G.Collection, options: SchemaOptions): {
+    schema: Schema;
+    types: string;
+};
+export {};

package/dist/astro-schema.js

@@ -0,0 +1,125 @@
+/** The schema and the `Entry` type (a module, as Astro writes it) of the data. */
+export function collectionSchema(z, collection, options) {
+    const shape = {};
+    const lines = [];
+    for (const field of collection.fields) {
+        if (field.key === options.body)
+            continue;
+        const { schema, type, optional } = fieldSchema(z, field, options);
+        shape[field.key] = optional ? schema.optional() : schema;
+        const description = field.configuration.description;
+        const doc = `${field.name}${description ? `: ${description}` : ""}`;
+        lines.push(`  /** ${doc.replaceAll("*/", "*\\/")} */`, `  ${JSON.stringify(field.key)}${optional ? "?" : ""}: ${type}`);
+    }
+    const body = lines.join("\n");
+    const used = ["EmbeddedAsset", "EmbeddedRecord"].filter((name) => body.includes(name));
+    const types = [
+        `// The data of the ${collection.slug} collection's entries, from its fields in Nohead (@nohead/sdk/astro).`,
+        ...(used.length
+            ? [`import type { ${used.join(", ")} } from "@nohead/sdk/astro"`]
+            : []),
+        ``,
+        `export type Entry = {`,
+        ...lines,
+        `}`,
+        ``,
+    ].join("\n");
+    return { schema: z.object(shape), types };
+}
+function fieldSchema(z, field, { expand, richText, slugs }) {
+    const expanded = expand.includes(field.key);
+    let one;
+    switch (field.type) {
+        case "text":
+        case "long_text":
+            one = { schema: z.string(), type: "string" };
+            break;
+        case "rich_text":
+            one =
+                richText === "document"
+                    ? {
+                        schema: z.record(z.string(), z.unknown()),
+                        type: "Record<string, unknown>",
+                    }
+                    : { schema: z.string(), type: "string" };
+            break;
+        case "integer":
+            one = { schema: z.number().int(), type: "number" };
+            break;
+        case "decimal":
+            one = { schema: z.number(), type: "number" };
+            break;
+        case "date":
+            one = { schema: z.coerce.date(), type: "Date" };
+            break;
+        case "boolean":
+            // No value reads as false: it is never required.
+            return {
+                schema: z.boolean().default(false),
+                type: "boolean",
+                optional: false,
+            };
+        case "enum": {
+            const options = field.configuration.options;
+            one = {
+                schema: z.enum(options),
+                type: options.map((option) => JSON.stringify(option)).join(" | "),
+            };
+            break;
+        }
+        case "asset":
+            one = expanded
+                ? { schema: embeddedAsset(z), type: "EmbeddedAsset" }
+                : { schema: z.string(), type: "string" };
+            break;
+        case "relation": {
+            const target = slugs.get(field.configuration.target_collection_id);
+            one = expanded
+                ? { schema: embeddedRecord(z), type: "EmbeddedRecord" }
+                : target
+                    ? {
+                        schema: reference(z, target),
+                        type: `{ collection: ${JSON.stringify(target)}; id: string }`,
+                    }
+                    : { schema: z.string(), type: "string" };
+            break;
+        }
+        default:
+            one = { schema: z.unknown(), type: "unknown" };
+    }
+    if (field.multiple) {
+        const type = /[|{]/.test(one.type) ? `(${one.type})[]` : `${one.type}[]`;
+        return { schema: z.array(one.schema), type, optional: !field.required };
+    }
+    // An expanded asset or record deleted since (or unpublished) is left
+    // out, so it may be missing even when the field is required.
+    const optional = !field.required ||
+        (expanded && (field.type === "asset" || field.type === "relation"));
+    return { ...one, optional };
+}
+/**
+ * What Astro's `reference(collection)` makes of a record ID: a lookup for
+ * `getEntry`. Built here, since `astro:content` is Astro's virtual module.
+ */
+function reference(z, collection) {
+    return z.union([
+        z.string().transform((id) => ({ id, collection })),
+        z.object({ id: z.string(), collection: z.literal(collection) }),
+    ]);
+}
+function embeddedAsset(z) {
+    return z.object({
+        id: z.string(),
+        filename: z.string(),
+        content_type: z.string(),
+        alt: z.string().optional(),
+        width: z.number().optional(),
+        height: z.number().optional(),
+        image_url: z.string().optional(),
+        file_url: z.string().optional(),
+        media_url: z.string().optional(),
+    });
+}
+function embeddedRecord(z) {
+    return z.object({ id: z.string(), data: z.record(z.string(), z.unknown()) });
+}

package/dist/astro.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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). On Astro 6 and later, the
+ * collection's fields give the entries their schema and TypeScript type.
+ */
+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,153 @@
+import { Nohead } from "./client.js";
+import { environment } from "./core.js";
+import { collectionSchema } from "./astro-schema.js";
+import { AuthorizationError, 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"');
+    }
+    const connect = () => {
+        // 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");
+        }
+        return new Nohead({ ...client, richText });
+    };
+    return {
+        name: "nohead",
+        // Astro 6 and later: the entries' schema and type, from the collection's
+        // fields. A schema given to defineCollection takes its place.
+        async createSchema() {
+            const nohead = connect();
+            const { z } = await import("astro/zod");
+            try {
+                // Relations name their target by ID; references need its slug.
+                const slugsById = async () => {
+                    const slugs = new Map();
+                    for await (const each of nohead.collections.list()) {
+                        slugs.set(each.id, each.slug);
+                    }
+                    return slugs;
+                };
+                const [fields, slugs] = await Promise.all([
+                    nohead.collections.get(collection),
+                    slugsById(),
+                ]);
+                return collectionSchema(z, fields, {
+                    expand: expand ?? [],
+                    body,
+                    richText,
+                    slugs,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof AuthorizationError))
+                    throw error;
+                throw new NoheadError(`noheadLoader reads the ${collection} collection's fields for its schema, which takes the key's schema:read scope: add it, or pass a schema to defineCollection`, { cause: error });
+            }
+        },
+        async load(context) {
+            const { store, logger } = context;
+            const nohead = connect();
+            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/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.12.0";
+export declare const VERSION = "0.14.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.12.0";
+export const VERSION = "0.14.0";

package/package.json

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