@hollware/client 0.10.0 → 1.0.0-rc.0

package/dist/index.d.mts

@@ -1,5 +1,209 @@
 import { WebhookCheck, describeSite, getEntry, getTranslations, listEntries, search, signWebhook, verifyWebhook } from "@hollware/core";
 import * as z from "zod";
+//#region src/preview.d.ts
+/**
+ * What a site does with a preview link (T-103 of docs/security/threat-model.md): the token travels
+ * in a URL once, and in a cookie after that, so it does not stay in the address bar, the history,
+ * a `Referer` or a copied link. These are the pure parts, shared by `@hollware/nuxt` and
+ * `@hollware/astro`: the integrations only wire them to their framework's requests.
+ */
+/** The cookie that holds the token of a preview, on the site's own origin. */
+export declare const PREVIEW_COOKIE = "hollware_preview";
+/** How long the cookie lives, in seconds: the hour of the token. */
+export declare const PREVIEW_COOKIE_MAX_AGE = 3600;
+/** Whether a value is shaped like a preview token. A value that is not is never kept. */
+export declare function isPreviewToken(value: unknown): value is string;
+/**
+ * The preview token of a `Cookie` request header, or `undefined`: none, or one that is not shaped
+ * like a token.
+ */
+export declare function previewTokenFromCookie(header: string | null | undefined): string | undefined;
+/** What to answer a request that carries `?hollware-preview=`. */
+interface PreviewExchange {
+  /** The path and query of the same URL without the parameter, other parameters kept in order. */
+  readonly location: string;
+  /** The token, when it is shaped like one; `undefined` when it is not, and no cookie is set. */
+  readonly token: string | undefined;
+}
+/**
+ * The exchange of a URL that carries `?hollware-preview=<token>`: where to redirect (`303`) and
+ * the token to keep in a cookie, or `undefined` when the URL has no such parameter. The token is
+ * not checked here: only Hollware can, when the page reads.
+ */
+export declare function exchangePreviewLink(url: URL | string, makeNonce?: () => string): PreviewExchange | undefined;
+/**
+ * Whether the cookie is `Secure` on a request for this URL: always, but on `http://localhost` and
+ * `http://127.0.0.1`, so local development works over plain HTTP.
+ */
+export declare function isSecureRequest(url: URL | string): boolean;
+/** The `Set-Cookie` that keeps a token for its hour: no script reads it, and only this site gets it. */
+export declare function previewCookie(token: string, options: {
+  readonly secure: boolean;
+}): string;
+/** The `Set-Cookie` that removes the cookie. */
+export declare function clearedPreviewCookie(options: {
+  readonly secure: boolean;
+}): string;
+/** The headers of the redirect that exchanges a preview link: no cache, and no `Referer` to follow. */
+export declare function exchangeHeaders(exchange: PreviewExchange, url: URL | string): Array<[string, string]>;
+/**
+ * Whether an error is Hollware's refusal of a token as expired or invalid, its code
+ * `invalid_preview` (over the binding, or over HTTP as a `HollwareClientError`), looking through
+ * `cause`. A token for another entry is no refusal: Hollware answers it as no entry, and it must
+ * stay so.
+ */
+export declare function isPreviewRefusal(error: unknown): boolean;
+//#endregion
+//#region src/hollware.d.ts
+/** 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: on Workers a
+   * binding exists only while a request runs, so a module-level `createHollware` passes
+   * `() => hollwareBinding(env.HOLLWARE)`.
+   */
+  readonly reader: HollwareReader | (() => HollwareReader);
+} | {
+  /** 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>;
+};
+/** The options of `createHollware`: the key of the site, and where to read it from. */
+type HollwareOptions = ReaderOptions & {
+  /** The key of the site in the Hollware config. */
+  readonly site: string;
+};
+/** What a page shows of an entry in a listing: no verdict, no revision, no state of review. */
+interface PageSummary {
+  readonly id: string;
+  readonly collection: string;
+  readonly locale: string;
+  readonly slug: string;
+  readonly translationGroup: string | null;
+  readonly frontmatter: Record<string, unknown>;
+  readonly tags: readonly string[];
+  readonly publishedAt: string | null;
+  readonly updatedAt: string;
+}
+/** The document of an entry: what `<HollwareContent>` of `@hollware/react` and `@hollware/vue` renders. */
+interface PageDocument {
+  readonly nodes: readonly unknown[];
+  readonly frontmatter: Record<string, unknown>;
+  readonly meta: Record<string, unknown>;
+}
+/**
+ * An entry for a page. A framework that renders on the server and hydrates in the browser sends
+ * what a loader returns to the browser, so the entry holds only what a reader sees: its verdict,
+ * its revision and its last publication stay on the server.
+ */
+interface PageEntry extends PageSummary {
+  readonly document?: PageDocument;
+}
+/** What `getEntry` answers: the entry, and whether it is a preview. */
+interface EntryAnswer {
+  readonly entry: PageEntry;
+  /**
+   * `true` when the entry was read with a preview token, so it may be a draft and nothing may keep
+   * the page: answer it `Cache-Control: no-store` (`previewHeaders` does).
+   */
+  readonly preview: boolean;
+}
+/** The options of `getEntry`. */
+interface GetEntryOptions {
+  /**
+   * The incoming request: its `hollware_preview` cookie, when it has one, is the preview token
+   * (`src/preview.ts`).
+   */
+  readonly request?: Request;
+  /**
+   * The value of the `hollware_preview` cookie, when the framework gives cookies on their own
+   * (`cookies()` of Next.js): it wins over `request`, and a value that is no token is ignored.
+   */
+  readonly preview?: string;
+}
+/** What a listing narrows to. */
+interface ListEntriesOptions {
+  readonly locale?: string;
+  readonly tag?: string;
+  /** The most entries to return, 100 at the most; Hollware's default when not set. */
+  readonly limit?: number;
+  /** The `nextCursor` of the previous page. */
+  readonly cursor?: string;
+}
+/** A page of a listing: published entries, newest first. */
+interface EntryPage {
+  readonly entries: PageSummary[];
+  readonly nextCursor: string | null;
+}
+/** The same entry in another locale. */
+interface Translation {
+  readonly locale: string;
+  readonly slug: string;
+}
+/** The read side of one Hollware site, for any code that turns a `Request` into data. */
+interface Hollware {
+  /**
+   * The entry in its locale, with its Comark document, or `undefined` when it is not published
+   * (or, with a preview token, does not exist). With `request`, a preview token in its cookie
+   * reads the latest revision of the entry the token names, a draft included. A token that is
+   * expired or not valid is an error, never the published version: send it to
+   * `previewHeaders(request, error)` to clear the cookie.
+   */
+  getEntry(collection: string, locale: string, slug: string, options?: GetEntryOptions): Promise<EntryAnswer | undefined>;
+  /** The published entries of a collection, newest first. */
+  listEntries(collection: string, options?: ListEntriesOptions): Promise<EntryPage>;
+  /** The published entries of a translation group of a collection, one per locale. */
+  getTranslations(collection: string, group: string): Promise<Translation[]>;
+}
+/**
+ * The read side of a Hollware site for any app that renders on a server, whatever its framework: a React Router
+ * loader, a Next.js Server Component, a TanStack Start server function. It reads published
+ * content, through a service binding or over HTTP, and it never runs in the browser: a loader's
+ * data goes there, and `PageEntry` holds only what a reader sees.
+ *
+ * ```ts
+ * const hollware = createHollware({ site: 'my-site', reader: () => hollwareBinding(env.HOLLWARE) })
+ * const answer = await hollware.getEntry('blog', 'en', slug, { request })
+ * ```
+ */
+export declare function createHollware(options: HollwareOptions): Hollware;
+//#endregion
+//#region src/preview-request.d.ts
+/**
+ * Previews of drafts (T-103 of docs/security/threat-model.md) for any code that handles a
+ * `Request`: the link of the admin's "Preview on the site" carries `?hollware-preview=<token>`,
+ * and the site exchanges it once for an `HttpOnly` cookie, so the token does not stay in the
+ * address bar, the history or a `Referer`. The shape of the token, the cookie and the URL without
+ * the parameter are pure functions of `@hollware/client`.
+ */
+/**
+ * The answer to the link of a preview: a `303` to the same URL without the parameter, with the
+ * token in the `hollware_preview` cookie (an hour, `HttpOnly`, `SameSite=Lax`, `Secure` but on
+ * `http://localhost`), `no-store` and `Referrer-Policy: no-referrer`. `null` when the request is
+ * not a `GET` or `HEAD` with that parameter. The token is not checked: Hollware does, when the
+ * page reads. A value not shaped like a token sets no cookie.
+ */
+export declare function previewRedirect(request: Request): Response | null;
+/**
+ * The `Set-Cookie` that removes the preview cookie when `error` says Hollware refused the token
+ * as expired or not valid, and `null` for any other error. A token for another entry is no
+ * refusal: Hollware answers it as no entry, and the cookie stays.
+ */
+export declare function previewCookieClear(error: unknown, request: Request): string | null;
+/** Whether the request carries a preview token in its cookie. */
+export declare function isPreviewRequest(request: Request): boolean;
+/**
+ * The headers a page of a visitor who previews must carry: `Cache-Control: no-store` for any
+ * request that holds a token, whatever Hollware answered, and the `Set-Cookie` that clears it
+ * when `error` is a refusal. Without a token it is empty, so a published page is cached as
+ * usual. Merge it into the headers of the response (a `Headers` is what `data()`, `Response`
+ * and `NextResponse` take).
+ */
+export declare function previewHeaders(request: Request, error?: unknown): Headers;
+//#endregion
 //#region src/index.d.ts
 export declare const name = "@hollware/client";
 type Output<Spec extends {
@@ -17,6 +221,13 @@ export interface HollwareReader {
   getEntry(site: string, collection: string, slug: string, locale: string, options?: {
     readonly formats?: readonly Format[];
     readonly related?: boolean;
+    /**
+     * A preview token (`hw_prv_…`, made in the admin, or the `hollware-preview` of a page's
+     * URL): the entry it names is read in its latest revision, a draft included, and the answer
+     * must never be cached. A token that does not hold is an `invalid_input` error (a
+     * `HollwareClientError` over HTTP), never the published version in its place.
+     */
+    readonly preview?: string;
   }): Promise<Output<typeof getEntry>>;
   listEntries(site: string, collection: string, options?: {
     readonly locale?: string;
@@ -59,5 +270,11 @@ export declare class HollwareClientError extends Error {
  * of the HTTP reader only has to be that site's key.
  */
 export declare function createClient(options: ClientOptions): HollwareReader;
+/**
+ * A service binding to the `Hollware` entrypoint as a reader. `wrangler types` cannot see across
+ * Workers, so the binding comes typed as `Service`: this checks it is there, and gives the
+ * mistake a name when it is not. `@hollware/astro`, `@hollware/react` and `@hollware/vue` re-export it.
+ */
+export declare function hollwareBinding(binding: unknown, name?: string): HollwareReader;
 //#endregion
-export { type WebhookCheck, signWebhook, verifyWebhook };
+export { type EntryAnswer, type EntryPage, type GetEntryOptions, type Hollware, type HollwareOptions, type ListEntriesOptions, type PageDocument, type PageEntry, type PageSummary, type PreviewExchange, type ReaderOptions, type Translation, type WebhookCheck, signWebhook, verifyWebhook };

package/dist/index.mjs

@@ -1,4 +1,242 @@
-import { signWebhook, verifyWebhook } from "@hollware/core";
+import { PREVIEW_QUERY_PARAM, signWebhook, verifyWebhook } from "@hollware/core";
+//#region src/preview.ts
+/**
+* What a site does with a preview link (T-103 of docs/security/threat-model.md): the token travels
+* in a URL once, and in a cookie after that, so it does not stay in the address bar, the history,
+* a `Referer` or a copied link. These are the pure parts, shared by `@hollware/nuxt` and
+* `@hollware/astro`: the integrations only wire them to their framework's requests.
+*/
+/** The cookie that holds the token of a preview, on the site's own origin. */
+const PREVIEW_COOKIE = "hollware_preview";
+/** How long the cookie lives, in seconds: the hour of the token. */
+const PREVIEW_COOKIE_MAX_AGE = 3600;
+/** The shape of a token, `hw_prv_<base64url>.<base64url>`. The site cannot check more: Hollware does. */
+const TOKEN_SHAPE = /^hw_prv_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+/** Whether a value is shaped like a preview token. A value that is not is never kept. */
+function isPreviewToken(value) {
+	return typeof value === "string" && TOKEN_SHAPE.test(value);
+}
+/**
+* The preview token of a `Cookie` request header, or `undefined`: none, or one that is not shaped
+* like a token.
+*/
+function previewTokenFromCookie(header) {
+	if (header === null || header === void 0) return void 0;
+	for (const part of header.split(";")) {
+		const at = part.indexOf("=");
+		if (at === -1 || part.slice(0, at).trim() !== "hollware_preview") continue;
+		const value = part.slice(at + 1).trim();
+		return isPreviewToken(value) ? value : void 0;
+	}
+}
+/**
+* The exchange of a URL that carries `?hollware-preview=<token>`: where to redirect (`303`) and
+* the token to keep in a cookie, or `undefined` when the URL has no such parameter. The token is
+* not checked here: only Hollware can, when the page reads.
+*/
+function exchangePreviewLink(url, makeNonce = nonce) {
+	const { pathname, search } = typeof url === "string" ? new URL(url) : url;
+	const kept = [];
+	let found;
+	let seen = false;
+	for (const pair of search.slice(1).split("&")) {
+		if (pair === "") continue;
+		const at = pair.indexOf("=");
+		if (safeDecode(at === -1 ? pair : pair.slice(0, at)) !== PREVIEW_QUERY_PARAM) {
+			kept.push(pair);
+			continue;
+		}
+		if (seen) continue;
+		seen = true;
+		found = at === -1 ? "" : safeDecode(pair.slice(at + 1));
+	}
+	if (!seen) return void 0;
+	if (isPreviewToken(found)) kept.push(`${PREVIEW_VIEW_PARAM}=${makeNonce()}`);
+	return {
+		location: kept.length === 0 ? pathname : `${pathname}?${kept.join("&")}`,
+		token: isPreviewToken(found) ? found : void 0
+	};
+}
+/** The parameter that keeps a previewed page out of every cache: a random value, no secret. */
+const PREVIEW_VIEW_PARAM = "hollware-view";
+function nonce() {
+	const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(9));
+	return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_");
+}
+function safeDecode(text) {
+	try {
+		return decodeURIComponent(text.replaceAll("+", " "));
+	} catch {
+		return text;
+	}
+}
+/**
+* Whether the cookie is `Secure` on a request for this URL: always, but on `http://localhost` and
+* `http://127.0.0.1`, so local development works over plain HTTP.
+*/
+function isSecureRequest(url) {
+	const { protocol, hostname } = typeof url === "string" ? new URL(url) : url;
+	return !(protocol === "http:" && (hostname === "localhost" || hostname === "127.0.0.1"));
+}
+/** The `Set-Cookie` that keeps a token for its hour: no script reads it, and only this site gets it. */
+function previewCookie(token, options) {
+	return cookieLine(token, PREVIEW_COOKIE_MAX_AGE, options.secure);
+}
+/** The `Set-Cookie` that removes the cookie. */
+function clearedPreviewCookie(options) {
+	return cookieLine("", 0, options.secure);
+}
+function cookieLine(value, maxAge, secure) {
+	return `${PREVIEW_COOKIE}=${value}; Path=/; HttpOnly;${secure ? " Secure;" : ""} SameSite=Lax; Max-Age=${maxAge}`;
+}
+/** The headers of the redirect that exchanges a preview link: no cache, and no `Referer` to follow. */
+function exchangeHeaders(exchange, url) {
+	const headers = [
+		["location", exchange.location],
+		["cache-control", "no-store"],
+		["referrer-policy", "no-referrer"]
+	];
+	if (exchange.token !== void 0) headers.push(["set-cookie", previewCookie(exchange.token, { secure: isSecureRequest(url) })]);
+	return headers;
+}
+/**
+* Whether an error is Hollware's refusal of a token as expired or invalid, its code
+* `invalid_preview` (over the binding, or over HTTP as a `HollwareClientError`), looking through
+* `cause`. A token for another entry is no refusal: Hollware answers it as no entry, and it must
+* stay so.
+*/
+function isPreviewRefusal(error) {
+	let current = error;
+	for (let depth = 0; depth < 4 && typeof current === "object" && current !== null; depth++) {
+		if (Reflect.get(current, "code") === "invalid_preview") return true;
+		current = Reflect.get(current, "cause");
+	}
+	return false;
+}
+//#endregion
+//#region src/hollware.ts
+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
+	});
+}
+/** The fields of a summary that a page may see, picked one by one so no other one travels. */
+function summaryOf(entry) {
+	return {
+		id: entry.id,
+		collection: entry.collection,
+		locale: entry.locale,
+		slug: entry.slug,
+		translationGroup: entry.translationGroup,
+		frontmatter: entry.frontmatter,
+		tags: entry.tags,
+		publishedAt: entry.publishedAt,
+		updatedAt: entry.updatedAt
+	};
+}
+/**
+* The read side of a Hollware site for any app that renders on a server, whatever its framework: a React Router
+* loader, a Next.js Server Component, a TanStack Start server function. It reads published
+* content, through a service binding or over HTTP, and it never runs in the browser: a loader's
+* data goes there, and `PageEntry` holds only what a reader sees.
+*
+* ```ts
+* const hollware = createHollware({ site: 'my-site', reader: () => hollwareBinding(env.HOLLWARE) })
+* const answer = await hollware.getEntry('blog', 'en', slug, { request })
+* ```
+*/
+function createHollware(options) {
+	const { site } = options;
+	return {
+		async getEntry(collection, locale, slug, getOptions = {}) {
+			const preview = isPreviewToken(getOptions.preview) ? getOptions.preview : previewTokenFromCookie(getOptions.request?.headers.get("cookie"));
+			const answer = await readerOf(options).getEntry(site, collection, slug, locale, {
+				formats: ["document"],
+				...preview === void 0 ? {} : { preview }
+			});
+			if (answer.outcome === "not_found" || answer.entry === void 0) return void 0;
+			const { document } = answer.entry;
+			return {
+				entry: {
+					...summaryOf(answer.entry),
+					...document === void 0 ? {} : { document }
+				},
+				preview: preview !== void 0
+			};
+		},
+		async listEntries(collection, listOptions = {}) {
+			const page = await readerOf(options).listEntries(site, collection, listOptions);
+			return {
+				entries: page.entries.map(summaryOf),
+				nextCursor: page.nextCursor
+			};
+		},
+		async getTranslations(collection, group) {
+			return ((await readerOf(options).getTranslations(site, collection, group)).entries ?? []).map((entry) => ({
+				locale: entry.locale,
+				slug: entry.slug
+			}));
+		}
+	};
+}
+//#endregion
+//#region src/preview-request.ts
+/**
+* Previews of drafts (T-103 of docs/security/threat-model.md) for any code that handles a
+* `Request`: the link of the admin's "Preview on the site" carries `?hollware-preview=<token>`,
+* and the site exchanges it once for an `HttpOnly` cookie, so the token does not stay in the
+* address bar, the history or a `Referer`. The shape of the token, the cookie and the URL without
+* the parameter are pure functions of `@hollware/client`.
+*/
+/**
+* The answer to the link of a preview: a `303` to the same URL without the parameter, with the
+* token in the `hollware_preview` cookie (an hour, `HttpOnly`, `SameSite=Lax`, `Secure` but on
+* `http://localhost`), `no-store` and `Referrer-Policy: no-referrer`. `null` when the request is
+* not a `GET` or `HEAD` with that parameter. The token is not checked: Hollware does, when the
+* page reads. A value not shaped like a token sets no cookie.
+*/
+function previewRedirect(request) {
+	if (request.method !== "GET" && request.method !== "HEAD") return null;
+	const url = new URL(request.url);
+	const exchange = exchangePreviewLink(url);
+	if (exchange === void 0) return null;
+	return new Response(null, {
+		status: 303,
+		headers: exchangeHeaders(exchange, url)
+	});
+}
+/**
+* The `Set-Cookie` that removes the preview cookie when `error` says Hollware refused the token
+* as expired or not valid, and `null` for any other error. A token for another entry is no
+* refusal: Hollware answers it as no entry, and the cookie stays.
+*/
+function previewCookieClear(error, request) {
+	if (!isPreviewRefusal(error)) return null;
+	return clearedPreviewCookie({ secure: isSecureRequest(request.url) });
+}
+/** Whether the request carries a preview token in its cookie. */
+function isPreviewRequest(request) {
+	return previewTokenFromCookie(request.headers.get("cookie")) !== void 0;
+}
+/**
+* The headers a page of a visitor who previews must carry: `Cache-Control: no-store` for any
+* request that holds a token, whatever Hollware answered, and the `Set-Cookie` that clears it
+* when `error` is a refusal. Without a token it is empty, so a published page is cached as
+* usual. Merge it into the headers of the response (a `Headers` is what `data()`, `Response`
+* and `NextResponse` take).
+*/
+function previewHeaders(request, error) {
+	const headers = new Headers();
+	if (!isPreviewRequest(request)) return headers;
+	headers.set("cache-control", "no-store");
+	const clear = previewCookieClear(error, request);
+	if (clear !== null) headers.append("set-cookie", clear);
+	return headers;
+}
+//#endregion
 //#region src/index.ts
 const name = "@hollware/client";
 /** An answer of the HTTP read API that is no result: its code, message and fix. */
@@ -38,7 +276,8 @@ function httpReader(url, token, send) {
 	return {
 		getEntry: (_site, collection, slug, locale, options) => get(`${segment(collection)}/${segment(locale)}/${segment(slug)}`, {
 			formats: options?.formats?.join(","),
-			related: options?.related === true ? "true" : void 0
+			related: options?.related === true ? "true" : void 0,
+			preview: options?.preview
 		}),
 		listEntries: (_site, collection, options = {}) => get(segment(collection), {
 			locale: options.locale,
@@ -78,5 +317,17 @@ function createClient(options) {
 function narrow(body) {
 	return body;
 }
+function isReader(value) {
+	return typeof value === "object" && value !== null && "getEntry" in value;
+}
+/**
+* A service binding to the `Hollware` entrypoint as a reader. `wrangler types` cannot see across
+* Workers, so the binding comes typed as `Service`: this checks it is there, and gives the
+* mistake a name when it is not. `@hollware/astro`, `@hollware/react` and `@hollware/vue` re-export it.
+*/
+function hollwareBinding(binding, name = "HOLLWARE") {
+	if (isReader(binding)) return binding;
+	throw new Error(`Hollware: the Worker has no service binding ${name} to the Hollware entrypoint: add it to services in wrangler.jsonc.`);
+}
 //#endregion
-export { HollwareClientError, createClient, name, signWebhook, verifyWebhook };
+export { HollwareClientError, PREVIEW_COOKIE, PREVIEW_COOKIE_MAX_AGE, clearedPreviewCookie, createClient, createHollware, exchangeHeaders, exchangePreviewLink, hollwareBinding, isPreviewRefusal, isPreviewRequest, isPreviewToken, isSecureRequest, name, previewCookie, previewCookieClear, previewHeaders, previewRedirect, previewTokenFromCookie, signWebhook, verifyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hollware/client",
-  "version": "0.10.0",
+  "version": "1.0.0-rc.0",
   "description": "Typed Hollware client over a service binding or HTTP.",
   "homepage": "https://hollware.com",
   "bugs": {
@@ -16,6 +16,7 @@
     "dist"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -28,7 +29,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@hollware/core": "0.10.0"
+    "@hollware/core": "1.0.0-rc.0"
   },
   "devDependencies": {
     "@types/node": "24.19.2",