@hollware/client 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -1,3 +1,53 @@
+import { WebhookCheck, describeSite, getEntry, getTranslations, listEntries, signWebhook, verifyWebhook } from "@hollware/core";
+import * as z from "zod";
 //#region src/index.d.ts
 export declare const name = "@hollware/client";
-//#endregion
+type Output<Spec extends {
+  output: z.ZodType;
+}> = z.output<Spec['output']>;
+export type Format = 'markdown' | 'document' | 'html';
+/**
+ * What a site reads from Hollware: the published content, through the four read methods. A
+ * service binding to a Hollware Worker already has this shape; `createClient` gives the same over
+ * HTTP, so a site can move from one transport to the other without changing a call.
+ */
+export interface HollwareReader {
+  getEntry(site: string, collection: string, slug: string, locale: string, options?: {
+    readonly formats?: readonly Format[];
+  }): Promise<Output<typeof getEntry>>;
+  listEntries(site: string, collection: string, options?: {
+    readonly locale?: string;
+    readonly tag?: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+  }): Promise<Output<typeof listEntries>>;
+  getTranslations(site: string, collection: string, translationGroup: string): Promise<Output<typeof getTranslations>>;
+  describeSite(site: string): Promise<Output<typeof describeSite>>;
+}
+export type ClientOptions =
+/** A service binding to the `Hollware` entrypoint of a Hollware Worker. */
+{
+  readonly binding: HollwareReader;
+} |
+/** The public URL of a Hollware, and a personal token with `content:read`. */
+{
+  readonly url: string;
+  readonly token: string;
+  /** `fetch`, when not the global one. */
+  readonly fetch?: (request: Request) => Promise<Response>;
+};
+/** An answer of the HTTP read API that is no result: its code, message and fix. */
+export declare class HollwareClientError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly fix: string | null;
+  constructor(status: number, code: string, message: string, fix: string | null);
+}
+/**
+ * A reader of a Hollware: over a service binding, which needs no network and no token, or over
+ * HTTP, through the read API at `<url>/v1`. A deployment serves one site, so the `site` argument
+ * of the HTTP reader only has to be that site's key.
+ */
+export declare function createClient(options: ClientOptions): HollwareReader;
+//#endregion
+export { type WebhookCheck, signWebhook, verifyWebhook };

package/dist/index.mjs

@@ -1,4 +1,71 @@
+import { signWebhook, verifyWebhook } from "@hollware/core";
 //#region src/index.ts
 const name = "@hollware/client";
+/** An answer of the HTTP read API that is no result: its code, message and fix. */
+var HollwareClientError = class extends Error {
+	status;
+	code;
+	fix;
+	constructor(status, code, message, fix) {
+		super(message);
+		this.name = "HollwareClientError";
+		this.status = status;
+		this.code = code;
+		this.fix = fix;
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function httpReader(url, token, send) {
+	const base = url.replace(/\/+$/, "");
+	async function get(path, query = {}) {
+		const params = new URLSearchParams();
+		for (const [key, value] of Object.entries(query)) if (value !== void 0) params.set(key, value);
+		const search = params.toString();
+		const response = await send(new Request(`${base}/v1/${path}${search === "" ? "" : `?${search}`}`, { headers: {
+			authorization: `Bearer ${token}`,
+			accept: "application/json"
+		} }));
+		const body = await response.json().catch(() => null);
+		if (response.status === 200 || response.status === 404) {
+			if (isRecord(body) && typeof body["outcome"] === "string") return body;
+		}
+		const field = (key) => isRecord(body) && typeof body[key] === "string" ? body[key] : null;
+		throw new HollwareClientError(response.status, field("code") ?? "http_error", field("message") ?? `Hollware answered ${response.status}`, field("fix"));
+	}
+	const segment = encodeURIComponent;
+	return {
+		getEntry: (_site, collection, slug, locale, options) => get(`${segment(collection)}/${segment(locale)}/${segment(slug)}`, { formats: options?.formats?.join(",") }),
+		listEntries: (_site, collection, options = {}) => get(segment(collection), {
+			locale: options.locale,
+			tag: options.tag,
+			limit: options.limit === void 0 ? void 0 : String(options.limit),
+			cursor: options.cursor
+		}),
+		getTranslations: (_site, collection, group) => get(`${segment(collection)}/translations/${segment(group)}`),
+		describeSite: (_site) => get("site")
+	};
+}
+/**
+* A reader of a Hollware: over a service binding, which needs no network and no token, or over
+* HTTP, through the read API at `<url>/v1`. A deployment serves one site, so the `site` argument
+* of the HTTP reader only has to be that site's key.
+*/
+function createClient(options) {
+	if ("binding" in options) return options.binding;
+	const send = options.fetch ?? ((request) => fetch(request));
+	const reader = httpReader(options.url, options.token, send);
+	return {
+		getEntry: async (...args) => narrow(await reader.getEntry(...args)),
+		listEntries: async (...args) => narrow(await reader.listEntries(...args)),
+		getTranslations: async (...args) => narrow(await reader.getTranslations(...args)),
+		describeSite: async (...args) => narrow(await reader.describeSite(...args))
+	};
+}
+/** The body of an answer, which the read API builds from the output schema of its operation. */
+function narrow(body) {
+	return body;
+}
 //#endregion
-export { name };
+export { HollwareClientError, createClient, name, signWebhook, verifyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hollware/client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Typed Hollware client over a service binding or HTTP.",
   "homepage": "https://hollware.com",
   "bugs": {
@@ -27,11 +27,18 @@
     "access": "public",
     "provenance": true
   },
+  "dependencies": {
+    "@hollware/core": "0.2.0"
+  },
   "devDependencies": {
     "@types/node": "24.19.2",
     "publint": "0.3.25",
     "typescript": "7.0.2",
-    "vite-plus": "1.1.0"
+    "vite-plus": "1.1.0",
+    "zod": "4.6.5"
+  },
+  "peerDependencies": {
+    "zod": "^4.2.0"
   },
   "engines": {
     "node": ">=24.11.0"