@hollware/astro 0.0.0 → 1.0.0-rc.0

package/README.md

@@ -1,3 +1,131 @@
 # @hollware/astro
 
-Reserved. The first release of the Astro integration of [Hollware](https://hollware.com) is published from https://github.com/hollware/hollware.
+Read [Hollware](https://hollware.com) from an Astro site: content loaders for Astro's content
+layer, over a service binding when the site is a Worker on the same Cloudflare account, or over
+HTTP with a read token anywhere else. Published content only, and the latest revision of one entry
+when a page is opened with a preview token (live collections).
+
+```sh
+npm install @hollware/astro
+```
+
+On Cloudflare, bind the Hollware Worker in the site's `wrangler.jsonc`:
+
+```jsonc
+"services": [{ "binding": "HOLLWARE", "service": "my-hollware", "entrypoint": "Hollware" }]
+```
+
+A live collection reads at request time, so a publish shows with no rebuild:
+
+```ts
+// src/live.config.ts
+import { env } from 'cloudflare:workers'
+import { defineLiveCollection } from 'astro/content/config'
+import { hollwareBinding, hollwareLiveLoader } from '@hollware/astro'
+
+const blog = defineLiveCollection({
+  loader: hollwareLiveLoader({
+    site: 'my-site',
+    collection: 'blog',
+    locale: 'en',
+    reader: () => hollwareBinding(env.HOLLWARE),
+  }),
+})
+export const collections = { blog }
+```
+
+```astro
+---
+import { getLiveEntry, render } from 'astro:content'
+const { entry } = await getLiveEntry('blog', Astro.params.slug!)
+const { Content } = await render(entry!)
+---
+<h1>{entry.data.title}</h1>
+<Content />
+```
+
+A build-time collection reads over HTTP with a read token (`hollware token create --read`):
+
+```ts
+// src/content.config.ts
+import { defineCollection } from 'astro:content'
+import { hollwareLoader } from '@hollware/astro'
+
+const blog = defineCollection({
+  loader: hollwareLoader({
+    site: 'my-site',
+    collection: 'blog',
+    locale: 'en',
+    url: 'https://cms.example.com',
+    token: process.env.HOLLWARE_TOKEN ?? '',
+  }),
+})
+export const collections = { blog }
+```
+
+| What                                   | Does                                                                   |
+| -------------------------------------- | ---------------------------------------------------------------------- |
+| `hollwareLoader(options)`              | A loader for `defineCollection`: every published entry, with its HTML  |
+| `hollwareLiveLoader(options)`          | A loader for `defineLiveCollection`: reads at request time             |
+| `hollwareBinding(env.HOLLWARE)`        | The service binding as a reader, with a clear error when it is missing |
+| `hollwareTranslations(options, group)` | The `{ locale, slug }` of each entry of a translation group            |
+
+An entry's `id` is its slug, its `data` the frontmatter (give `defineCollection` a `schema` to
+validate it) and its rendered HTML the one Hollware made, so `render(entry)` works. The
+`locale` option picks the locale; make one collection per locale. `getLiveCollection('blog',
+{ tag, limit })` lists the entries without their HTML.
+
+The token stays on the server: the loaders run in the build or in a request, and nothing here
+reaches the browser.
+
+## Previews
+
+"Preview on the site" in the admin opens the entry's page with `?hollware-preview=<token>`: a
+signed link for one entry, valid for one hour. `hollwarePreview()`, a middleware, exchanges the link
+for a cookie: a `303` to the same URL without the parameter (other parameters kept), with the token
+in `hollware_preview` (`HttpOnly`, `SameSite=Lax`, `Path=/`, an hour, and `Secure` on every request
+but `http://localhost` and `http://127.0.0.1`). The token is in a URL once, but for the first
+request's line in the logs; a value not shaped like a token sets no cookie. Every later request
+finds the token in `Astro.locals.hollwarePreview`, and its response is `no-store`:
+
+```ts
+// src/middleware.ts
+import { hollwarePreview } from '@hollware/astro'
+export const onRequest = hollwarePreview()
+```
+
+```ts
+// src/env.d.ts
+import type { HollwarePreviewLocals } from '@hollware/astro'
+
+declare global {
+  namespace App {
+    interface Locals extends HollwarePreviewLocals {}
+  }
+}
+```
+
+A live collection reads the latest revision of the entry, a draft included, when `getLiveEntry`
+gets the token in its filter:
+
+```astro
+---
+import { refusePreview } from '@hollware/astro'
+const preview = Astro.locals.hollwarePreview
+const { entry, error } = await getLiveEntry('blog', { id: Astro.params.slug!, preview })
+if (error) refusePreview(Astro.locals, error)
+---
+```
+
+A token that is expired, forged or for another entry is an `error`, never the published version.
+`refusePreview` makes the response clear the cookie when Hollware says the token expired or is not
+valid; a token for another entry is answered as no entry and keeps it.
+The build-time `hollwareLoader` has no preview: a static page is built once, for everyone, so it
+only ever holds published content.
+
+## Links
+
+- Docs: <https://hollware.com>
+- Repository: <https://github.com/hollware/hollware>
+- Issues: <https://github.com/hollware/hollware/issues>
+- License: MIT

package/dist/index.d.mts

@@ -0,0 +1,174 @@
+import { HollwareReader, HollwareReader as HollwareReader$1, hollwareBinding } from "@hollware/client";
+import { DataStore, LiveLoader, Loader, LoaderContext } from "astro/loaders";
+import { MiddlewareHandler } from "astro";
+//#region src/source.d.ts
+/** What names the collection to read: one collection of a site, in one locale. */
+interface SourceOptions {
+  /** The key of the site in the Hollware config. */
+  readonly site: string;
+  /** The collection to read, such as `blog`. */
+  readonly collection: string;
+  /** The locale to read: an entry's id is its slug in this locale. */
+  readonly locale: string;
+}
+/** Where to read from: a reader (a service binding is one), or a Hollware URL and a read token. */
+type ReaderOptions = {
+  /**
+   * A service binding to the `Hollware` entrypoint, or a function that gives it: a live
+   * collection reads at request time, when the binding exists, so it passes
+   * `() => env.HOLLWARE`.
+   */
+  readonly reader: HollwareReader$1 | (() => HollwareReader$1);
+} | {
+  /** The public URL of the Hollware. */
+  readonly url: string;
+  /** A read token (`hw_read_`, from `hollware token create --read`). */
+  readonly token: string;
+  /** `fetch`, when not the global one. */
+  readonly fetch?: (request: Request) => Promise<Response>;
+};
+/** A published entry as the content layer takes it. */
+interface SourceEntry {
+  /** The slug: Astro's id, unique within the locale. */
+  readonly id: string;
+  /** The frontmatter of the entry. */
+  readonly data: Record<string, unknown>;
+  /** The HTML Hollware renders from the Markdown: only an entry read alone has it. */
+  readonly html?: string;
+  /** When the entry last changed, as an ISO date. */
+  readonly updatedAt: string;
+}
+/** The same entry in another locale. */
+interface Translation {
+  readonly locale: string;
+  readonly slug: string;
+}
+/** What a listing narrows to. */
+interface ListOptions {
+  readonly tag?: string;
+  /** The most entries to return; all of them when not set. */
+  readonly limit?: number;
+}
+interface Source {
+  list(options?: ListOptions): Promise<SourceEntry[]>;
+  /**
+   * The entry with this slug and its HTML, or `undefined` when it is not published. With a
+   * `preview` token (made in the admin) it is the latest revision of the entry the token names,
+   * a draft included; a token that does not hold is an error, never the published version.
+   */
+  get(slug: string, options?: {
+    readonly preview?: string;
+  }): Promise<SourceEntry | undefined>;
+  translations(group: string): Promise<Translation[]>;
+}
+/**
+ * Reads one collection of a site in one locale, published content only (but for `get` with a
+ * preview token). The reader is resolved on
+ * each call, so a live loader gets its service binding from the request that makes it.
+ */
+export declare function createSource(options: SourceOptions & ReaderOptions): Source;
+//#endregion
+//#region src/preview.d.ts
+/**
+ * What `hollwarePreview()` puts on `Astro.locals`. Declare it in the site's `src/env.d.ts`:
+ *
+ * ```ts
+ * import type { HollwarePreviewLocals } from '@hollware/astro'
+ * declare global {
+ *   namespace App {
+ *     interface Locals extends HollwarePreviewLocals {}
+ *   }
+ * }
+ * ```
+ */
+interface HollwarePreviewLocals {
+  /** The preview token of the visitor's cookie: pass it to `getLiveEntry('blog', { id, preview })`. */
+  hollwarePreview: string | undefined;
+  /** Set by `refusePreview`: the response clears the cookie. */
+  hollwarePreviewRefused: boolean;
+}
+/**
+ * The middleware of previews (T-103), for `src/middleware.ts`: `export const onRequest =
+ * hollwarePreview()`, or `sequence(hollwarePreview(), ...)`.
+ *
+ * - A GET with `?hollware-preview=<token>` (the link of the admin's "Preview on the site") is
+ *   answered `303` to the same URL without the parameter, with the token in the `hollware_preview`
+ *   cookie (HttpOnly, SameSite=Lax, an hour, Secure but on http://localhost and
+ *   http://127.0.0.1), `no-store` and `Referrer-Policy: no-referrer`. The token is not checked:
+ *   Hollware does, when the page reads. A value not shaped like a token sets no cookie.
+ * - Any later request puts the cookie's token on `Astro.locals.hollwarePreview`, and its response
+ *   is `no-store`.
+ * - A page that gets a refusal from Hollware calls `refusePreview(Astro.locals, error)`: when
+ *   the token expired or is not valid, the response clears the cookie. A token for another entry
+ *   is answered as no entry and is no refusal.
+ */
+export declare function hollwarePreview(): MiddlewareHandler;
+/**
+ * Tells the middleware that Hollware refused the page's token, when `error` (the `error` of
+ * `getLiveEntry`) says it expired or is not valid, so the response clears the cookie.
+ */
+export declare function refusePreview(locals: HollwarePreviewLocals, error: unknown): void;
+//#endregion
+//#region src/index.d.ts
+export declare const name = "@hollware/astro";
+/** The options of `hollwareLoader`. */
+export type HollwareLoaderOptions = SourceOptions & ReaderOptions;
+/**
+ * A content loader for `defineCollection` in `src/content.config.ts`: it reads the published
+ * entries of one collection of a Hollware site at build time (and when the content layer is
+ * refreshed), over HTTP with a read token or through any reader. An entry's id is its slug, its
+ * data the frontmatter, and its `rendered.html` the HTML Hollware made, so Astro's `render(entry)`
+ * works. A schema in `defineCollection` validates the frontmatter.
+ */
+export declare function hollwareLoader(options: HollwareLoaderOptions): Loader;
+/** What a build-time load needs of Astro's `LoaderContext`. */
+export interface LoadContext {
+  readonly store: Pick<DataStore, 'set' | 'keys' | 'delete'>;
+  readonly parseData: LoaderContext['parseData'];
+  readonly generateDigest: LoaderContext['generateDigest'];
+  readonly logger: Pick<LoaderContext['logger'], 'info'>;
+}
+/**
+ * Stores every published entry of the source with its HTML, its data validated by the schema of
+ * the collection, and removes what is no longer published.
+ */
+export declare function loadInto(source: Source, context: LoadContext): Promise<void>;
+/** The filter of `getLiveCollection`. */
+export type HollwareCollectionFilter = ListOptions;
+/**
+ * The filter of `getLiveEntry`: the slug, and the preview token of the page's URL
+ * (`?hollware-preview=`), which reads the latest revision of its entry, a draft included.
+ */
+export interface HollwareEntryFilter {
+  readonly id: string;
+  readonly preview?: string | undefined;
+}
+/**
+ * A live loader for `defineLiveCollection` in `src/live.config.ts`: it reads at request time, so
+ * a publish shows on the next request with no rebuild. On Workers, give it the service binding
+ * through a function, because the binding exists only while a request runs:
+ *
+ * ```ts
+ * import { env } from 'cloudflare:workers'
+ * hollwareLiveLoader({
+ *   site: 'my-site',
+ *   collection: 'blog',
+ *   locale: 'en',
+ *   reader: () => hollwareBinding(env.HOLLWARE),
+ * })
+ * ```
+ *
+ * `getLiveEntry('blog', slug)` has the entry with its `rendered.html`; `getLiveEntry('blog', { id:
+ * slug, preview })`, with the `hollware-preview` of the page's URL, has its latest revision, a
+ * draft included, and the page must answer `Cache-Control: no-store` then; `getLiveCollection('blog',
+ * { tag, limit })` lists the entries without it.
+ */
+export declare function hollwareLiveLoader(options: HollwareLoaderOptions): LiveLoader<Record<string, unknown>, HollwareEntryFilter, HollwareCollectionFilter>;
+/**
+ * The entries of a translation group of a collection, one per locale: `{ locale, slug }`, to
+ * link to. The group is the value of the frontmatter field that `describe_site` names as
+ * `translationGroupField`.
+ */
+export declare function hollwareTranslations(options: HollwareLoaderOptions, group: string): Promise<Translation[]>;
+//#endregion
+export { type HollwarePreviewLocals, type HollwareReader, type ListOptions, type ReaderOptions, type Source, type SourceEntry, type SourceOptions, type Translation, hollwareBinding };

package/dist/index.mjs

@@ -0,0 +1,223 @@
+import { HollwareClientError, clearedPreviewCookie, createClient, exchangeHeaders, exchangePreviewLink, hollwareBinding, isPreviewRefusal, isSecureRequest, previewTokenFromCookie } from "@hollware/client";
+//#region src/source.ts
+/** The largest page the read API gives. */
+const PAGE = 100;
+function readerOf(options) {
+	if ("reader" in options) return typeof options.reader === "function" ? options.reader() : options.reader;
+	return createClient({
+		url: options.url,
+		token: options.token,
+		fetch: options.fetch
+	});
+}
+/**
+* Reads one collection of a site in one locale, published content only (but for `get` with a
+* preview token). The reader is resolved on
+* each call, so a live loader gets its service binding from the request that makes it.
+*/
+function createSource(options) {
+	const { site, collection, locale } = options;
+	return {
+		async list(listOptions = {}) {
+			const reader = readerOf(options);
+			const found = [];
+			let cursor;
+			do {
+				const remaining = listOptions.limit === void 0 ? PAGE : listOptions.limit - found.length;
+				if (remaining <= 0) break;
+				const page = await reader.listEntries(site, collection, {
+					locale,
+					tag: listOptions.tag,
+					limit: Math.min(PAGE, remaining),
+					cursor
+				});
+				for (const entry of page.entries) found.push({
+					id: entry.slug,
+					data: entry.frontmatter,
+					updatedAt: entry.updatedAt
+				});
+				cursor = page.nextCursor ?? void 0;
+			} while (cursor !== void 0);
+			return found;
+		},
+		async get(slug, getOptions = {}) {
+			const answer = await readerOf(options).getEntry(site, collection, slug, locale, {
+				formats: ["html"],
+				...getOptions.preview === void 0 ? {} : { preview: getOptions.preview }
+			});
+			if (answer.outcome === "not_found" || answer.entry === void 0) return void 0;
+			return {
+				id: answer.entry.slug,
+				data: answer.entry.frontmatter,
+				html: answer.entry.html ?? "",
+				updatedAt: answer.entry.updatedAt
+			};
+		},
+		async translations(group) {
+			return ((await readerOf(options).getTranslations(site, collection, group)).entries ?? []).map((entry) => ({
+				locale: entry.locale,
+				slug: entry.slug
+			}));
+		}
+	};
+}
+/** The error to hand Astro: a refusal of the read API keeps its status in the message. */
+function asError(error) {
+	if (error instanceof HollwareClientError) return new Error(`Hollware answered ${error.status} (${error.code}): ${error.message}`, { cause: error });
+	return error instanceof Error ? error : new Error(String(error));
+}
+//#endregion
+//#region src/preview.ts
+/**
+* The middleware of previews (T-103), for `src/middleware.ts`: `export const onRequest =
+* hollwarePreview()`, or `sequence(hollwarePreview(), ...)`.
+*
+* - A GET with `?hollware-preview=<token>` (the link of the admin's "Preview on the site") is
+*   answered `303` to the same URL without the parameter, with the token in the `hollware_preview`
+*   cookie (HttpOnly, SameSite=Lax, an hour, Secure but on http://localhost and
+*   http://127.0.0.1), `no-store` and `Referrer-Policy: no-referrer`. The token is not checked:
+*   Hollware does, when the page reads. A value not shaped like a token sets no cookie.
+* - Any later request puts the cookie's token on `Astro.locals.hollwarePreview`, and its response
+*   is `no-store`.
+* - A page that gets a refusal from Hollware calls `refusePreview(Astro.locals, error)`: when
+*   the token expired or is not valid, the response clears the cookie. A token for another entry
+*   is answered as no entry and is no refusal.
+*/
+function hollwarePreview() {
+	return async (context, next) => {
+		const { request, url, locals } = context;
+		if (request.method === "GET" || request.method === "HEAD") {
+			const exchange = exchangePreviewLink(url);
+			if (exchange !== void 0) return new Response(null, {
+				status: 303,
+				headers: exchangeHeaders(exchange, url)
+			});
+		}
+		const token = previewTokenFromCookie(request.headers.get("cookie"));
+		const slot = Object.assign(locals, {
+			hollwarePreview: token,
+			hollwarePreviewRefused: false
+		});
+		const response = await next();
+		if (token === void 0) return response;
+		const answer = new Response(response.body, response);
+		answer.headers.set("cache-control", "no-store");
+		if (slot.hollwarePreviewRefused) answer.headers.append("set-cookie", clearedPreviewCookie({ secure: isSecureRequest(url) }));
+		return answer;
+	};
+}
+/**
+* Tells the middleware that Hollware refused the page's token, when `error` (the `error` of
+* `getLiveEntry`) says it expired or is not valid, so the response clears the cookie.
+*/
+function refusePreview(locals, error) {
+	if (isPreviewRefusal(error)) locals.hollwarePreviewRefused = true;
+}
+//#endregion
+//#region src/index.ts
+const name = "@hollware/astro";
+/**
+* A content loader for `defineCollection` in `src/content.config.ts`: it reads the published
+* entries of one collection of a Hollware site at build time (and when the content layer is
+* refreshed), over HTTP with a read token or through any reader. An entry's id is its slug, its
+* data the frontmatter, and its `rendered.html` the HTML Hollware made, so Astro's `render(entry)`
+* works. A schema in `defineCollection` validates the frontmatter.
+*/
+function hollwareLoader(options) {
+	const source = createSource(options);
+	return {
+		name: `${name}:${options.collection}:${options.locale}`,
+		load: (context) => loadInto(source, context)
+	};
+}
+/**
+* Stores every published entry of the source with its HTML, its data validated by the schema of
+* the collection, and removes what is no longer published.
+*/
+async function loadInto(source, context) {
+	const { store, logger } = context;
+	const seen = /* @__PURE__ */ new Set();
+	for (const summary of await source.list()) {
+		const entry = await source.get(summary.id);
+		if (entry === void 0) continue;
+		const data = await context.parseData({
+			id: entry.id,
+			data: entry.data
+		});
+		const html = entry.html ?? "";
+		store.set({
+			id: entry.id,
+			data,
+			rendered: { html },
+			digest: context.generateDigest({
+				data,
+				html
+			})
+		});
+		seen.add(entry.id);
+	}
+	for (const id of store.keys()) if (!seen.has(id)) store.delete(id);
+	logger.info(`Loaded ${seen.size} published entries`);
+}
+/**
+* A live loader for `defineLiveCollection` in `src/live.config.ts`: it reads at request time, so
+* a publish shows on the next request with no rebuild. On Workers, give it the service binding
+* through a function, because the binding exists only while a request runs:
+*
+* ```ts
+* import { env } from 'cloudflare:workers'
+* hollwareLiveLoader({
+*   site: 'my-site',
+*   collection: 'blog',
+*   locale: 'en',
+*   reader: () => hollwareBinding(env.HOLLWARE),
+* })
+* ```
+*
+* `getLiveEntry('blog', slug)` has the entry with its `rendered.html`; `getLiveEntry('blog', { id:
+* slug, preview })`, with the `hollware-preview` of the page's URL, has its latest revision, a
+* draft included, and the page must answer `Cache-Control: no-store` then; `getLiveCollection('blog',
+* { tag, limit })` lists the entries without it.
+*/
+function hollwareLiveLoader(options) {
+	const source = createSource(options);
+	return {
+		name: `${name}:${options.collection}:${options.locale}`,
+		async loadEntry({ filter }) {
+			try {
+				const preview = filter.preview === "" ? void 0 : filter.preview;
+				const entry = await source.get(filter.id, preview === void 0 ? {} : { preview });
+				if (entry === void 0) return void 0;
+				return {
+					id: entry.id,
+					data: entry.data,
+					rendered: { html: entry.html ?? "" },
+					...preview === void 0 ? { cacheHint: { lastModified: new Date(entry.updatedAt) } } : {}
+				};
+			} catch (error) {
+				return { error: asError(error) };
+			}
+		},
+		async loadCollection({ filter }) {
+			try {
+				return { entries: (await source.list(filter)).map((entry) => ({
+					id: entry.id,
+					data: entry.data,
+					cacheHint: { lastModified: new Date(entry.updatedAt) }
+				})) };
+			} catch (error) {
+				return { error: asError(error) };
+			}
+		}
+	};
+}
+/**
+* The entries of a translation group of a collection, one per locale: `{ locale, slug }`, to
+* link to. The group is the value of the frontmatter field that `describe_site` names as
+* `translationGroupField`.
+*/
+function hollwareTranslations(options, group) {
+	return createSource(options).translations(group);
+}
+//#endregion
+export { createSource, hollwareBinding, hollwareLiveLoader, hollwareLoader, hollwarePreview, hollwareTranslations, loadInto, name, refusePreview };

package/package.json

@@ -1,13 +1,52 @@
 {
   "name": "@hollware/astro",
-  "version": "0.0.0",
-  "description": "Reserved for Hollware's Astro integration. The first release comes from the hollware/hollware repository.",
+  "version": "1.0.0-rc.0",
+  "description": "Read Hollware from an Astro site: a content loader, over a service binding or HTTP.",
   "homepage": "https://hollware.com",
+  "bugs": {
+    "url": "https://github.com/hollware/hollware/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hollware/hollware.git",
     "directory": "packages/astro"
   },
-  "publishConfig": { "access": "public" }
-}
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@hollware/client": "1.0.0-rc.0",
+    "@hollware/core": "1.0.0-rc.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "astro": "7.4.0",
+    "publint": "0.3.25",
+    "typescript": "7.0.2",
+    "vite-plus": "1.2.0"
+  },
+  "peerDependencies": {
+    "astro": "^7.4.0"
+  },
+  "engines": {
+    "node": ">=24.11.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "publint": "publint --strict"
+  }
+}