@hollware/core 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -288,6 +288,21 @@ interface SiteDefinition {
   readonly collections: Readonly<Record<string, CollectionDefinition>>;
   /** Guidance for whoever writes anywhere in the site, in Markdown. */
   readonly styleGuide?: string;
+  /** The public origin of the site, such as `https://example.com`: entries' URLs start with it. */
+  readonly url?: string;
+  /** Who hears about publications (ADR-025). */
+  readonly events?: {
+    /** Each gets every event, signed with HMAC-SHA256 by the Worker secret named in `secret`. */
+    readonly webhooks?: readonly {
+      readonly name: string;
+      readonly url: string;
+      readonly secret: string;
+    }[];
+    /** Tells IndexNow the URLs that changed; `key` names the Worker secret with the key. */
+    readonly indexNow?: {
+      readonly key: string;
+    };
+  };
 }
 /** What `hollware.config.ts` exports. */
 interface HollwareConfig {
@@ -318,6 +333,22 @@ interface ResolvedSite {
   readonly defaultLocale: string;
   readonly styleGuide: string | null;
   readonly collections: ReadonlyMap<string, ResolvedCollection>;
+  /** The public origin of the site, or `null`. */
+  readonly url: string | null;
+  readonly events: ResolvedEvents;
+}
+/** A webhook of a site; `secret` names the Worker secret that signs its deliveries. */
+interface ResolvedWebhook {
+  readonly name: string;
+  readonly url: string;
+  readonly secret: string;
+}
+/** Who hears about the publications of a site. */
+interface ResolvedEvents {
+  readonly webhooks: readonly ResolvedWebhook[];
+  readonly indexNow: {
+    readonly key: string;
+  } | null;
 }
 /** The config once resolved, at the start of the Worker. v0.1 holds exactly one site. */
 interface ResolvedConfig {
@@ -960,10 +991,13 @@ export declare class HollwareError extends Error {
  */
 /** The kinds of ids and their prefixes. A new kind adds its prefix here. */
 export declare const ID_PREFIXES: {
+  readonly delivery: 'dlv';
   readonly entry: 'ent';
+  readonly event: 'evt';
   readonly publication: 'pub';
   readonly revision: 'rev';
   readonly revisionTag: 'tag';
+  readonly schedule: 'sch';
   readonly token: 'tok';
   readonly user: 'usr';
 };
@@ -1450,6 +1484,11 @@ export declare const publish: OperationSpec<"publish", z.ZodObject<{
     contract: z.ZodString;
     path: z.ZodString;
   }, z.core.$strip>>>;
+  group: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodNumber;
+  }, z.core.$strict>>>;
+  publishAt: z.ZodOptional<z.ZodISODateTime>;
 }, z.core.$strict>, z.ZodObject<{
   outcome: z.ZodEnum<{
     blocked: "blocked";
@@ -1457,6 +1496,7 @@ export declare const publish: OperationSpec<"publish", z.ZodObject<{
     needs_acknowledgement: "needs_acknowledgement";
     not_found: "not_found";
     published: "published";
+    scheduled: "scheduled";
   }>;
   entry: z.ZodOptional<z.ZodObject<{
     id: z.ZodString;
@@ -1510,6 +1550,7 @@ export declare const publish: OperationSpec<"publish", z.ZodObject<{
     currentVersion: z.ZodNumber;
     headRevision: z.ZodString;
   }, z.core.$strip>>;
+  failedEntry: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>;
 export declare const unpublish: OperationSpec<"unpublish", z.ZodObject<{
   id: z.ZodString;
@@ -1809,6 +1850,11 @@ export declare const OPERATIONS: readonly [OperationSpec<"create_draft", z.ZodOb
     contract: z.ZodString;
     path: z.ZodString;
   }, z.core.$strip>>>;
+  group: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodNumber;
+  }, z.core.$strict>>>;
+  publishAt: z.ZodOptional<z.ZodISODateTime>;
 }, z.core.$strict>, z.ZodObject<{
   outcome: z.ZodEnum<{
     blocked: "blocked";
@@ -1816,6 +1862,7 @@ export declare const OPERATIONS: readonly [OperationSpec<"create_draft", z.ZodOb
     needs_acknowledgement: "needs_acknowledgement";
     not_found: "not_found";
     published: "published";
+    scheduled: "scheduled";
   }>;
   entry: z.ZodOptional<z.ZodObject<{
     id: z.ZodString;
@@ -1869,6 +1916,7 @@ export declare const OPERATIONS: readonly [OperationSpec<"create_draft", z.ZodOb
     currentVersion: z.ZodNumber;
     headRevision: z.ZodString;
   }, z.core.$strip>>;
+  failedEntry: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>, OperationSpec<"unpublish", z.ZodObject<{
   id: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -2026,6 +2074,33 @@ export declare function isPersonalToken(value: string): boolean;
 /** The SHA-256 of a token, in lowercase hex: what the `tokens` table stores and looks up. */
 export declare function hashPersonalToken(token: string): Promise<string>;
 //#endregion
+//#region src/webhooks.d.ts
+/**
+ * The signature of Hollware's webhooks (ADR-025), for the Worker that sends them and for whoever
+ * receives them: HMAC-SHA256 of `<timestamp>.<body>` with the webhook's secret, sent as
+ * `hollware-signature: v1=<hex>` with `hollware-timestamp` (seconds since the epoch) and
+ * `hollware-event-id`. Web Crypto only, so it runs in any runtime.
+ */
+export declare const SIGNATURE_HEADER = "hollware-signature";
+export declare const TIMESTAMP_HEADER = "hollware-timestamp";
+export declare const EVENT_ID_HEADER = "hollware-event-id";
+/** The value of `hollware-signature` for a body sent at `timestamp` (seconds). */
+export declare function signWebhook(secret: string, timestamp: number, body: string): Promise<string>;
+export interface WebhookCheck {
+  readonly secret: string;
+  /** The raw body, as received: a parsed and re-serialized body no longer matches. */
+  readonly body: string;
+  readonly headers: Headers;
+  /** Now, in seconds since the epoch; the system clock when absent. */
+  readonly now?: number;
+  readonly toleranceSeconds?: number;
+}
+/**
+ * Whether a request is a webhook of Hollware: its signature matches the body and the secret, and
+ * its timestamp is within the tolerance, so a captured request cannot be replayed later.
+ */
+export declare function verifyWebhook(check: WebhookCheck): Promise<boolean>;
+//#endregion
 //#region src/index.d.ts
 export declare const name = "@hollware/core";
 //#endregion

package/dist/index.mjs

@@ -69,7 +69,7 @@ const MAX_MARKDOWN_BYTES_CEILING = 786432;
 * letter, at most 63 characters. A component name is what Markdown writes after the colons
 * (`::callout`). A site key has its own rule (`site-key.ts`).
 */
-const NAME = /^[a-z][a-z0-9-]{0,62}$/;
+const NAME$1 = /^[a-z][a-z0-9-]{0,62}$/;
 /** A language tag: a language, then an optional script and region: `es`, `pt-BR`, `zh-Hant-TW`. */
 const LOCALE_TAG = /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$/;
 /** The id of a contract: lowercase words joined by single hyphens. */
@@ -1224,7 +1224,7 @@ function readTranslations(path, raw, schema, problems) {
 }
 const COMPONENT_FIX = "Declare it with defineComponent({ props: z.strictObject({ … }) }).";
 function readComponent(path, name, raw, problems) {
-	if (!NAME.test(name)) problems.add(path, `${quote(name)} is not a valid component name`, nameFix("callout"));
+	if (!NAME$1.test(name)) problems.add(path, `${quote(name)} is not a valid component name`, nameFix("callout"));
 	if (!isRecord$1(raw)) {
 		problems.add(path, wrongType(raw, "a component"), COMPONENT_FIX);
 		return null;
@@ -1347,7 +1347,7 @@ function readMaxMarkdownBytes(path, raw, problems) {
 * problem already: `resolveConfig` throws when there is any, so nothing else keeps track of them.
 */
 function readCollection(path, name, raw, site, problems) {
-	if (!NAME.test(name)) problems.add(path, `${quote(name)} is not a valid collection name`, nameFix("blog"));
+	if (!NAME$1.test(name)) problems.add(path, `${quote(name)} is not a valid collection name`, nameFix("blog"));
 	if (!isRecord$1(raw)) {
 		problems.add(path, wrongType(raw, "a collection"), "Declare it with defineCollection({ schema, routes, … }).");
 		return null;
@@ -1376,6 +1376,90 @@ function readCollection(path, name, raw, site, problems) {
 	};
 }
 //#endregion
+//#region src/config/events.ts
+/** The name of a Worker secret or variable: what `wrangler secret put` takes. */
+const BINDING_NAME = /^[A-Z][A-Z0-9_]*$/;
+/** A subscriber's name: lowercase words joined by hyphens. */
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** The public URL of a site: an absolute http or https URL with no path, query or fragment. */
+function readSiteUrl(path, raw, problems) {
+	if (raw === void 0) return null;
+	const fix = "Write the public origin of the site, such as \"https://example.com\".";
+	if (typeof raw !== "string" || !URL.canParse(raw)) {
+		problems.add(path, wrongType(raw, "an absolute URL"), fix);
+		return null;
+	}
+	const url = new URL(raw);
+	if (url.protocol !== "https:" && url.protocol !== "http:" || url.pathname !== "/" || url.search !== "" || url.hash !== "") {
+		problems.add(path, `${quote(raw)} is not an origin`, fix);
+		return null;
+	}
+	return url.origin;
+}
+function readBindingName(path, raw, problems) {
+	if (typeof raw === "string" && BINDING_NAME.test(raw)) return raw;
+	problems.add(path, wrongType(raw, "the name of a Worker secret"), "Name the secret that holds the value, such as \"WEBHOOK_SECRET\", and set it with wrangler secret put.");
+	return null;
+}
+function readWebhook(path, raw, problems) {
+	if (!isRecord$1(raw)) {
+		problems.add(path, wrongType(raw, "a webhook"), "Declare it as { name: \"newsletter\", url: \"https://…\", secret: \"WEBHOOK_SECRET\" }.");
+		return null;
+	}
+	const name = raw["name"];
+	if (typeof name !== "string" || !NAME.test(name)) problems.add(keyPath(path, "name"), wrongType(name, "a name"), "Name it with lowercase words joined by hyphens, such as \"newsletter\".");
+	const url = raw["url"];
+	const urlOk = typeof url === "string" && URL.canParse(url) && new URL(url).protocol === "https:";
+	if (!urlOk) problems.add(keyPath(path, "url"), wrongType(url, "an https URL"), "Give the https URL that receives the events.");
+	const secret = readBindingName(keyPath(path, "secret"), raw["secret"], problems);
+	if (typeof name !== "string" || !NAME.test(name) || !urlOk || secret === null) return null;
+	return {
+		name,
+		url: String(url),
+		secret
+	};
+}
+/** Who hears about publications (ADR-025): webhooks, and IndexNow when the site has a URL. */
+function readEvents(path, raw, siteUrl, problems) {
+	const events = {
+		webhooks: [],
+		indexNow: null
+	};
+	if (raw === void 0) return events;
+	if (!isRecord$1(raw)) {
+		problems.add(path, wrongType(raw, "an object"), "Declare { webhooks: [ … ], indexNow: { … } }.");
+		return events;
+	}
+	const webhooks = raw["webhooks"];
+	if (webhooks !== void 0) {
+		if (!Array.isArray(webhooks)) problems.add(keyPath(path, "webhooks"), wrongType(webhooks, "a list"), "List the webhooks.");
+		else {
+			const seen = /* @__PURE__ */ new Set();
+			webhooks.forEach((item, index) => {
+				const webhook = readWebhook(itemPath(keyPath(path, "webhooks"), index), item, problems);
+				if (webhook === null) return;
+				if (seen.has(webhook.name)) {
+					problems.add(itemPath(keyPath(path, "webhooks"), index), `repeats the name ${quote(webhook.name)}`, "Give each webhook a name of its own.");
+					return;
+				}
+				seen.add(webhook.name);
+				events.webhooks.push(webhook);
+			});
+		}
+	}
+	const indexNow = raw["indexNow"];
+	if (indexNow !== void 0) {
+		const indexPath = keyPath(path, "indexNow");
+		if (!isRecord$1(indexNow)) problems.add(indexPath, wrongType(indexNow, "an object"), "Declare { key: \"INDEXNOW_KEY\" }.");
+		else {
+			const key = readBindingName(keyPath(indexPath, "key"), indexNow["key"], problems);
+			if (siteUrl === null) problems.add(indexPath, "needs the URL of the site", "Set url on the site: IndexNow is told the public URLs of the entries.");
+			else if (key !== null) events.indexNow = { key };
+		}
+	}
+	return events;
+}
+//#endregion
 //#region src/config/site-key.ts
 /**
 * The key of a site, which is the id of its row in the database: lowercase letters and digits
@@ -1480,12 +1564,16 @@ function readSite(key, raw, problems) {
 		localesOk: ok,
 		routes: /* @__PURE__ */ new Map()
 	}, problems);
+	const styleGuide = readOptionalString(keyPath(path, "styleGuide"), raw["styleGuide"], "Write the guidance as a Markdown string, or remove it.", problems);
+	const url = readSiteUrl(keyPath(path, "url"), raw["url"], problems);
 	return {
 		key,
 		locales,
 		defaultLocale,
-		styleGuide: readOptionalString(keyPath(path, "styleGuide"), raw["styleGuide"], "Write the guidance as a Markdown string, or remove it.", problems),
-		collections
+		styleGuide,
+		collections,
+		url,
+		events: readEvents(keyPath(path, "events"), raw["events"], url, problems)
 	};
 }
 function readSites(raw, problems) {
@@ -1577,10 +1665,13 @@ var HollwareError = class extends Error {
 const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 /** The kinds of ids and their prefixes. A new kind adds its prefix here. */
 const ID_PREFIXES = {
+	delivery: "dlv",
 	entry: "ent",
+	event: "evt",
 	publication: "pub",
 	revision: "rev",
 	revisionTag: "tag",
+	schedule: "sch",
 	token: "tok",
 	user: "usr"
 };
@@ -3196,15 +3287,21 @@ const validate = defineOperation({
 const publish = defineOperation({
 	name: "publish",
 	title: "Publish an entry",
-	description: "Publishes the latest revision of an entry, if the entry is still at the version you read. It is blocked while the contracts report errors. Warnings have to be acknowledged: an answer of needs_acknowledgement lists them, and publish again with them in acknowledgeWarnings.",
+	description: "Publishes the latest revision of an entry, if the entry is still at the version you read, and with group, other entries in the same step. It is blocked while the contracts report errors. Warnings have to be acknowledged: an answer of needs_acknowledgement lists them, and publish again with them in acknowledgeWarnings. Publish entries that link to each other as one group.",
 	input: z.strictObject({
 		id: entryId,
 		version,
-		acknowledgeWarnings: z.array(acknowledgedWarning).default([]).describe("The warnings you accept, as needs_acknowledgement listed them.")
+		acknowledgeWarnings: z.array(acknowledgedWarning).default([]).describe("The warnings you accept, as needs_acknowledgement listed them."),
+		group: z.array(z.strictObject({
+			id: entryId,
+			version
+		})).max(99).default([]).describe("Other entries to publish in the same step, each with the version you read: all of them are published, or none. A link between two of them counts as published, and an acknowledged warning holds for every entry that reports it."),
+		publishAt: z.iso.datetime({ offset: true }).optional().describe("Publish at this time instead of now, as an ISO 8601 date and time: the entry is checked now and waits as scheduled, and it is published within a minute of the time, if nobody changes it before. One entry at a time, never with group.")
 	}),
 	output: z.object({
 		outcome: z.enum([
 			"published",
+			"scheduled",
 			"blocked",
 			"needs_acknowledgement",
 			"conflict",
@@ -3212,12 +3309,14 @@ const publish = defineOperation({
 		]),
 		entry: entrySummary.optional(),
 		verdict: verdict.optional(),
-		conflict: conflict.optional()
+		conflict: conflict.optional(),
+		failedEntry: entryId.optional().describe("In a group, the entry that kept the group from being published.")
 	}),
 	scopes: ["content:publish"],
 	effect: "write",
 	outcomes: {
 		published: { isError: false },
+		scheduled: { isError: false },
 		blocked: { isError: true },
 		needs_acknowledgement: { isError: false },
 		conflict: { isError: true },
@@ -3303,7 +3402,51 @@ async function hashPersonalToken(token) {
 	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 //#endregion
+//#region src/webhooks.ts
+/**
+* The signature of Hollware's webhooks (ADR-025), for the Worker that sends them and for whoever
+* receives them: HMAC-SHA256 of `<timestamp>.<body>` with the webhook's secret, sent as
+* `hollware-signature: v1=<hex>` with `hollware-timestamp` (seconds since the epoch) and
+* `hollware-event-id`. Web Crypto only, so it runs in any runtime.
+*/
+const SIGNATURE_HEADER = "hollware-signature";
+const TIMESTAMP_HEADER = "hollware-timestamp";
+const EVENT_ID_HEADER = "hollware-event-id";
+/** How far a timestamp may be from the receiver's clock, by default: five minutes. */
+const TOLERANCE_SECONDS = 300;
+const encoder = new TextEncoder();
+async function hmac(secret, text) {
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return [...new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(text)))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** The value of `hollware-signature` for a body sent at `timestamp` (seconds). */
+async function signWebhook(secret, timestamp, body) {
+	return `v1=${await hmac(secret, `${timestamp}.${body}`)}`;
+}
+/** Compares two strings in time that does not depend on where they differ. */
+function sameText(a, b) {
+	if (a.length !== b.length) return false;
+	let difference = 0;
+	for (let index = 0; index < a.length; index++) difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+	return difference === 0;
+}
+/**
+* Whether a request is a webhook of Hollware: its signature matches the body and the secret, and
+* its timestamp is within the tolerance, so a captured request cannot be replayed later.
+*/
+async function verifyWebhook(check) {
+	const signature = check.headers.get(SIGNATURE_HEADER);
+	const timestamp = Number(check.headers.get(TIMESTAMP_HEADER));
+	if (signature === null || !Number.isInteger(timestamp)) return false;
+	const now = check.now ?? Math.floor(Date.now() / 1e3);
+	if (Math.abs(now - timestamp) > (check.toleranceSeconds ?? TOLERANCE_SECONDS)) return false;
+	return sameText(signature, await signWebhook(check.secret, timestamp, check.body));
+}
+//#endregion
 //#region src/index.ts
 const name = "@hollware/core";
 //#endregion
-export { BUILT_IN_CONTRACT_IDS, COMARK_VERSION, ConfigError, DEFAULT_MAX_MARKDOWN_BYTES, ERROR_CODES, HollwareError, ID_PREFIXES, MAX_MARKDOWN_BYTES_CEILING, OPERATIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, REFUSAL_CONTRACT_IDS, SCOPES, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, contracts, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, describeBuiltInContracts, describeContract, describeResolvedSite, describeSite, generatePersonalToken, getEntry, getTranslations, hashPersonalToken, isBuiltInContract, isId, isPersonalToken, isScope, isSiteKey, listEntries, name, newId, processMarkdown, publish, renderHtml, resolveConfig, runContracts, schemas_exports as schemas, sizeLimitViolation, ulid, uniqueSlugViolation, uniqueTranslationViolation, unpublish, updateDraft, validate };
+export { BUILT_IN_CONTRACT_IDS, COMARK_VERSION, ConfigError, DEFAULT_MAX_MARKDOWN_BYTES, ERROR_CODES, EVENT_ID_HEADER, HollwareError, ID_PREFIXES, MAX_MARKDOWN_BYTES_CEILING, OPERATIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, REFUSAL_CONTRACT_IDS, SCOPES, SIGNATURE_HEADER, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, TIMESTAMP_HEADER, contracts, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, describeBuiltInContracts, describeContract, describeResolvedSite, describeSite, generatePersonalToken, getEntry, getTranslations, hashPersonalToken, isBuiltInContract, isId, isPersonalToken, isScope, isSiteKey, listEntries, name, newId, processMarkdown, publish, renderHtml, resolveConfig, runContracts, schemas_exports as schemas, signWebhook, sizeLimitViolation, ulid, uniqueSlugViolation, uniqueTranslationViolation, unpublish, updateDraft, validate, verifyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hollware/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Contracts, operation specs, schemas and the Markdown pipeline of Hollware. No Cloudflare dependencies.",
   "homepage": "https://hollware.com",
   "bugs": {
@@ -33,7 +33,7 @@
     "comark": "0.7.0"
   },
   "devDependencies": {
-    "@cloudflare/vitest-plugin": "1.4.0",
+    "@cloudflare/vitest-plugin": "1.4.1",
     "@types/node": "24.19.2",
     "publint": "0.3.25",
     "typescript": "7.0.2",