@obelism/content 0.5.0 → 0.6.0

package/README.md

@@ -155,6 +155,51 @@ export const POST = createPromptHandler({
 })
 ```
 
+## Webhooks
+
+A webhook tells your site that what the delivery API answers has changed
+(Space settings → Webhooks). Its requests are signed (Standard Webhooks);
+`createWebhookHandler` verifies them and hands you the typed event:
+
+```ts
+// app/api/revalidate/route.ts
+import { revalidatePath, revalidateTag } from 'next/cache'
+import { createWebhookHandler } from '@obelism/content/webhooks'
+
+export const POST = createWebhookHandler({
+	secret: process.env.CONTENT_WEBHOOK_SECRET!, // whsec_…, shown once
+	onEvent: (event, { id }) => {
+		if (event.type === 'entry.published' && event.data.entry.path) {
+			revalidatePath(`/${event.data.entry.path}`)
+		} else {
+			revalidateTag('content')
+		}
+	},
+})
+```
+
+It answers 401 to anything not signed with the secret or with a
+`webhook-timestamp` more than 5 minutes off (`tolerance`, in seconds), 204
+once `onEvent` is done, and 500 when it throws, so the CMS tries again. `id`
+is the delivery's `webhook-id`, the same on every retry.
+
+Elsewhere, `verifyWebhook(request, secret, { tolerance? })` returns the event
+or throws `WebhookVerificationError`. It takes a `Request`, or the raw body
+and headers (`{ body, headers }`; Node's `req.headers` work as they are), the
+body exactly as it was sent:
+
+```ts
+import { verifyWebhook } from '@obelism/content/webhooks'
+
+const event = await verifyWebhook(request, process.env.CONTENT_WEBHOOK_SECRET!)
+```
+
+`WebhookEvent` is a union on `type`: `entry.published`, `entry.unpublished`,
+`entry.deleted` and `entry.moved` (`data.entry`: `{ id, contentType, name,
+path }`, plus `previousPath` when moved), `asset.updated` (`data.asset`,
+`data.entries`), `model.changed` (`data.contentTypes`: `{ apiId, action }`),
+`locales.changed` (`data.defaultLocale`, `data.locales`) and `webhook.test`.
+
 ## Helpers
 
 - `richTextToHtml(doc, { renderEntry?, renderAsset? })`, `richTextToPlainText(doc)`
@@ -211,3 +256,40 @@ npx @obelism/content model apply   # apply it, all or nothing
 
 Options: `--file`, `--url` (or `$CONTENT_URL`), `--prune`. In GitHub Actions
 the plan is also written to the job summary.
+
+### Types
+
+Write a TypeScript type per content type to `content/content-types.ts`:
+
+```bash
+npx @obelism/content types                                    # from the environment
+npx @obelism/content types --file content/content-model.json  # from the model file, no token
+```
+
+Pages and data become `Entry<{ …fields }, 'apiId'>`, blocks
+`Block<{ …fields }, 'apiId'>`, named after the apiId (`blogPost` →
+`BlogPost`), with `ContentEntry` and `ContentBlock` as the unions of them.
+Each field is typed by what the delivery API answers with its defaults (one
+locale, rich text as a document), and `| null` when empty:
+
+| Field                    | Type                                                                 |
+| ------------------------ | -------------------------------------------------------------------- |
+| text, textarea, datetime | `string`                                                             |
+| number / boolean         | `number` / `boolean`                                                 |
+| select                   | the options' values, `'a' \| 'b'` (a list when multiple)             |
+| asset                    | `Asset` (a list when multiple)                                       |
+| reference                | the allowed entry types or their `EntryStub`s (a list when multiple) |
+| blocks                   | a list of the allowed block types and `ImproveBlock`                 |
+| richtext                 | `RichTextDocument`                                                   |
+| json                     | `unknown`                                                            |
+
+A localized field is the one locale's value. Pass the types to the client:
+
+```ts
+import type { BlogPost } from './content/content-types'
+
+const post = await client.getPage<BlogPost>('blog/hello')
+```
+
+Run it again after the model changes, e.g. after `model pull`. Options:
+`--dir` (default `content`), `--file`, `--url`.

package/dist/bin/content.js

@@ -256,9 +256,8 @@ class CliError extends Error {
         super(message), this.exitCode = exitCode;
     }
 }
-// Exit code: 0 done, 1 problems in the plan.
-const runModelCommand = async ({ command, file, url, token, prune, log = console.log, summaryFile, fetch: fetchImpl = fetch })=>{
-    const call = async (method, path, body)=>{
+// Calls the management API; anything but JSON back is a CliError.
+const managementApi = (url, token, fetchImpl = fetch)=>async (method, path, body)=>{
         const response = await fetchImpl(`${url}${config.MANAGEMENT_PATH}${path}`, {
             method,
             headers: {
@@ -284,6 +283,9 @@ const runModelCommand = async ({ command, file, url, token, prune, log = console
             throw new CliError(`${response.status} from ${url}: ${text.slice(0, 200)}`);
         }
     };
+// Exit code: 0 done, 1 problems in the plan.
+const runModelCommand = async ({ command, file, url, token, prune, log = console.log, summaryFile, fetch: fetchImpl = fetch })=>{
+    const call = managementApi(url, token, fetchImpl);
     if (command === 'pull') {
         const { ok, json } = await call('GET', '/model');
         if (!ok) throw new CliError(String(json.error ?? 'Pull failed'));
@@ -511,8 +513,173 @@ const runInitCommand = async ({ url, token, dir, install: shouldInstall, cwd = p
     return 0;
 };
 
+// What `content types` writes to content/content-types.ts: a TypeScript type
+// per content type, for what the delivery API answers with its defaults (one
+// locale, rich text as a document). Pages and data are `Entry<…>`, blocks
+// `Block<…>`, every field `| null` (delivery answers null for empty ones).
+// Pure.
+//
+//   const post = await client.getPage<BlogPost>('blog/hello')
+// The SDK's types the file imports; a content type whose name would clash
+// gets its kind as a suffix (`asset` → `AssetEntry`).
+const SDK_TYPES = [
+    'Asset',
+    'Block',
+    'Entry',
+    'EntryStub',
+    'ImproveBlock',
+    'RichTextDocument'
+];
+// The unions of every entry and block type the file ends with.
+const UNION_NAMES = [
+    'ContentEntry',
+    'ContentBlock'
+];
+const quote = (value)=>`'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+const union = (members)=>[
+        ...new Set(members)
+    ].join(' | ');
+const list = (type, multiple)=>multiple ? type.includes(' | ') ? `(${type})[]` : `${type}[]` : type;
+// `unknown` (a json field) holds null already.
+const nullable = (type)=>type === 'unknown' ? type : `${type} | null`;
+const comment = (text, indent)=>`${indent}// ${text.replace(/\s+/g, ' ').trim()}\n`;
+const generateTypes = (model)=>{
+    const types = model.contentTypes;
+    const blockTypes = types.filter(({ kind })=>kind === 'block');
+    const entryTypes = types.filter(({ kind })=>kind !== 'block');
+    const used = new Set();
+    const use = (name)=>{
+        used.add(name);
+        return name;
+    };
+    // apiIds start with a lowercase letter and are unique, so capitalizing
+    // keeps them unique.
+    const typeName = new Map(types.map(({ apiId, kind })=>{
+        const name = `${apiId[0].toUpperCase()}${apiId.slice(1)}`;
+        const reserved = SDK_TYPES.includes(name) || UNION_NAMES.includes(name);
+        return [
+            apiId,
+            reserved ? `${name}${kind === 'block' ? 'Block' : 'Entry'}` : name
+        ];
+    }));
+    const known = (allowed, candidates)=>allowed ? candidates.filter(({ apiId })=>allowed.includes(apiId)) : candidates;
+    const value = (field)=>{
+        switch(field.type){
+            case 'text':
+            case 'textarea':
+            case 'datetime':
+                return 'string';
+            case 'number':
+                return 'number';
+            case 'boolean':
+                return 'boolean';
+            case 'richtext':
+                return use('RichTextDocument');
+            case 'select':
+                return list(union(field.options.map((option)=>quote(option.value))), field.multiple);
+            case 'asset':
+                return list(use('Asset'), field.multiple);
+            case 'reference':
+                {
+                    // The entry itself, or a stub past the requested depth.
+                    const targets = known(field.contentTypes, entryTypes);
+                    const type = targets.length === 0 ? `${use('Entry')} | ${use('EntryStub')}` : union([
+                        ...targets.map(({ apiId })=>typeName.get(apiId)),
+                        `${use('EntryStub')}<${union(targets.map(({ apiId })=>quote(apiId)))}>`
+                    ]);
+                    return list(type, field.multiple);
+                }
+            case 'blocks':
+                {
+                    const allowed = known(field.allowedBlocks, blockTypes);
+                    const blocks = allowed.length === 0 ? use('Block') : union(allowed.map(({ apiId })=>typeName.get(apiId)));
+                    const improve = `${use('ImproveBlock')}${allowed.length === 0 ? '' : `<${blocks}>`}`;
+                    return list(union([
+                        blocks,
+                        improve
+                    ]), true);
+                }
+            case 'json':
+                return 'unknown';
+        }
+    };
+    const declaration = (type)=>{
+        const wrapper = type.kind === 'block' ? use('Block') : use('Entry');
+        const fields = type.fields.map((field)=>`${field.description ? comment(field.description, '\t\t') : ''}\t\t${field.apiId}: ${nullable(value(field))}\n`).join('');
+        const body = fields ? `{\n${fields}\t}` : 'Record<never, never>';
+        return [
+            comment(`${type.name} (${type.kind})${type.description ? `: ${type.description}` : ''}`, ''),
+            `export type ${typeName.get(type.apiId)} = ${wrapper}<\n\t${body},\n\t${quote(type.apiId)}\n>\n`
+        ].join('');
+    };
+    const declarations = types.map(declaration);
+    const unions = [
+        [
+            'ContentEntry',
+            entryTypes
+        ],
+        [
+            'ContentBlock',
+            blockTypes
+        ]
+    ];
+    const unionLines = unions.filter(([, members])=>members.length > 0).map(([name, members])=>`export type ${name} = ${union(members.map(({ apiId })=>typeName.get(apiId)))}\n`);
+    const imports = SDK_TYPES.filter((name)=>used.has(name));
+    return [
+        '// Generated by `npx @obelism/content types` from the content model.\n',
+        "// Don't edit: run it again after the model changes.\n",
+        ...imports.length > 0 ? [
+            `\nimport type { ${imports.join(', ')} } from '@obelism/content'\n`
+        ] : [],
+        ...declarations.map((text)=>`\n${text}`),
+        ...unionLines.length > 0 ? [
+            '\n',
+            ...unionLines
+        ] : []
+    ].join('');
+};
+
+const readModel = async (file)=>{
+    let text;
+    try {
+        text = await promises.readFile(file, 'utf8');
+    } catch  {
+        throw new CliError(`Can't read ${file}. Run \`content model pull\` first?`);
+    }
+    try {
+        return JSON.parse(text);
+    } catch (error) {
+        throw new CliError(`${file} is not valid JSON: ${error.message}`);
+    }
+};
+const runTypesCommand = async ({ dir, file, url, token, cwd = process.cwd(), log = console.log, fetch: fetchImpl = fetch })=>{
+    let model;
+    if (file) {
+        model = await readModel(node_path.resolve(cwd, file));
+    } else {
+        if (!token) {
+            throw new CliError('CONTENT_MANAGEMENT_TOKEN is not set (or pass --file to read a model file).', 2);
+        }
+        const { ok, json } = await managementApi(url, token, fetchImpl)('GET', '/model');
+        if (!ok) throw new CliError(String(json.error ?? 'Pull failed'));
+        model = json;
+    }
+    if (!Array.isArray(model.contentTypes)) {
+        throw new CliError('The model has no contentTypes');
+    }
+    const out = node_path.join(dir, 'content-types.ts');
+    await promises.mkdir(node_path.resolve(cwd, dir), {
+        recursive: true
+    });
+    await promises.writeFile(node_path.resolve(cwd, out), generateTypes(model));
+    const count = model.contentTypes.length;
+    log(`Wrote ${count} ${count === 1 ? 'type' : 'types'} to ${out}.`);
+    return 0;
+};
+
 const USAGE = `Usage: content init [--dir content] [--url origin] [--skip-install]
        content model <pull|plan|apply> [--file path] [--url origin] [--prune]
+       content types [--dir content] [--file path] [--url origin]
 
   init          start a site's repository on the token's environment: the
                 model file, an example per content type, the SDK installed
@@ -520,14 +687,19 @@ const USAGE = `Usage: content init [--dir content] [--url origin] [--skip-instal
   model pull    write the environment's model to the file
   model plan    show what applying the file would change, and what stands in the way
   model apply   apply the file in one transaction, or change nothing
+  types         write content-types.ts: a TypeScript type per content type,
+                from the environment's model (or the model file with --file)
 
-  --dir           where init writes content-model.json and examples/ (default content)
+  --dir           where init writes content-model.json and examples/, and types
+                  content-types.ts (default content)
   --skip-install  init leaves dependencies alone
-  --file          the model file (default content/content-model.json)
+  --file          the model file (default content/content-model.json); types
+                  reads it instead of pulling the model
   --url           the CMS (default $CONTENT_URL, else ${config.DEFAULT_URL})
   --prune         plan and apply also delete content types the file leaves out
 
-Needs CONTENT_MANAGEMENT_TOKEN: a management token from Space settings.`;
+Needs CONTENT_MANAGEMENT_TOKEN: a management token from Space settings
+(not for types --file).`;
 const main = async ()=>{
     let parsed;
     try {
@@ -535,8 +707,7 @@ const main = async ()=>{
             allowPositionals: true,
             options: {
                 file: {
-                    type: 'string',
-                    default: 'content/content-model.json'
+                    type: 'string'
                 },
                 url: {
                     type: 'string'
@@ -570,13 +741,23 @@ const main = async ()=>{
         return 0;
     }
     const isInit = group === 'init' && command === undefined;
+    const isTypes = group === 'types' && command === undefined;
     const modelCommand = group === 'model' && (command === 'pull' || command === 'plan' || command === 'apply') ? command : null;
-    if (!isInit && !modelCommand) throw new CliError(USAGE, 2);
+    if (!isInit && !isTypes && !modelCommand) throw new CliError(USAGE, 2);
     const token = process.env.CONTENT_MANAGEMENT_TOKEN;
+    const url = config.normalizeUrl(values.url ?? process.env.CONTENT_URL ?? config.DEFAULT_URL);
+    // With --file, types needs no token.
+    if (isTypes) {
+        return runTypesCommand({
+            dir: values.dir,
+            file: values.file,
+            url,
+            token
+        });
+    }
     if (!token) {
         throw new CliError(`CONTENT_MANAGEMENT_TOKEN is not set.\n\n${USAGE}`, 2);
     }
-    const url = config.normalizeUrl(values.url ?? process.env.CONTENT_URL ?? config.DEFAULT_URL);
     if (!modelCommand) {
         return runInitCommand({
             url,
@@ -587,7 +768,7 @@ const main = async ()=>{
     }
     return runModelCommand({
         command: modelCommand,
-        file: values.file,
+        file: values.file ?? 'content/content-model.json',
         url,
         token,
         prune: values.prune,

package/dist/prompt.js

@@ -1,5 +1,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var standardWebhooks = require('./standardWebhooks-kh5dc0ff.js');
+
 // Your own model for prompt editing in the visual editor. Set the endpoint
 // under Space settings → Prompt editing; the CMS then sends each prompt there
 // instead of to Workers AI, as a signed POST (Standard Webhooks, the same
@@ -23,48 +25,25 @@ class PromptVerificationError extends Error {
         this.name = 'PromptVerificationError';
     }
 }
-const SECRET_PREFIX = 'whsec_';
-// Seconds a request's timestamp may be off, against replays.
-const DEFAULT_TOLERANCE = 5 * 60;
-const base64ToBytes = (value)=>Uint8Array.from(atob(value), (char)=>char.charCodeAt(0));
 // Checks a request's Standard Webhooks signature and returns its body.
 // Throws PromptVerificationError when it isn't from the CMS.
-const verifyPromptRequest = async (request, secret, { tolerance = DEFAULT_TOLERANCE, now = Date.now() } = {})=>{
-    if (!secret?.startsWith(SECRET_PREFIX)) {
+const verifyPromptRequest = async (request, secret, { tolerance = standardWebhooks.DEFAULT_TOLERANCE, now = Date.now() } = {})=>{
+    if (!secret?.startsWith(standardWebhooks.SECRET_PREFIX)) {
         throw new Error('The prompt secret must be the whsec_… from Space settings');
     }
-    const id = request.headers.get('webhook-id');
-    const timestamp = request.headers.get('webhook-timestamp');
-    const signatures = request.headers.get('webhook-signature');
-    if (!id || !timestamp || !signatures) {
-        throw new PromptVerificationError('Missing signature headers');
-    }
-    const seconds = Number(timestamp);
-    if (!Number.isFinite(seconds) || Math.abs(now / 1000 - seconds) > tolerance) {
-        throw new PromptVerificationError('Timestamp outside the tolerance');
-    }
     const body = await request.text();
-    const key = await crypto.subtle.importKey('raw', base64ToBytes(secret.slice(SECRET_PREFIX.length)), {
-        name: 'HMAC',
-        hash: 'SHA-256'
-    }, false, [
-        'verify'
-    ]);
-    const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
-    let valid = false;
-    for (const signature of signatures.split(' ')){
-        const [version, value] = signature.split(',');
-        if (version !== 'v1' || !value) continue;
-        let bytes;
-        try {
-            bytes = base64ToBytes(value);
-        } catch  {
-            continue;
+    await standardWebhooks.verifySignature({
+        body,
+        id: request.headers.get('webhook-id'),
+        timestamp: request.headers.get('webhook-timestamp'),
+        signatures: request.headers.get('webhook-signature')
+    }, secret, {
+        tolerance,
+        now,
+        fail: (message)=>{
+            throw new PromptVerificationError(message);
         }
-        // crypto.subtle.verify compares in constant time.
-        if (await crypto.subtle.verify('HMAC', key, bytes, signed)) valid = true;
-    }
-    if (!valid) throw new PromptVerificationError('Invalid signature');
+    });
     let payload;
     try {
         payload = JSON.parse(body);

package/dist/prompt.mjs

@@ -1,3 +1,5 @@
+import { S as SECRET_PREFIX, v as verifySignature, D as DEFAULT_TOLERANCE } from './standardWebhooks-ew5mhpac.mjs';
+
 // Your own model for prompt editing in the visual editor. Set the endpoint
 // under Space settings → Prompt editing; the CMS then sends each prompt there
 // instead of to Workers AI, as a signed POST (Standard Webhooks, the same
@@ -21,48 +23,25 @@ class PromptVerificationError extends Error {
         this.name = 'PromptVerificationError';
     }
 }
-const SECRET_PREFIX = 'whsec_';
-// Seconds a request's timestamp may be off, against replays.
-const DEFAULT_TOLERANCE = 5 * 60;
-const base64ToBytes = (value)=>Uint8Array.from(atob(value), (char)=>char.charCodeAt(0));
 // Checks a request's Standard Webhooks signature and returns its body.
 // Throws PromptVerificationError when it isn't from the CMS.
 const verifyPromptRequest = async (request, secret, { tolerance = DEFAULT_TOLERANCE, now = Date.now() } = {})=>{
     if (!secret?.startsWith(SECRET_PREFIX)) {
         throw new Error('The prompt secret must be the whsec_… from Space settings');
     }
-    const id = request.headers.get('webhook-id');
-    const timestamp = request.headers.get('webhook-timestamp');
-    const signatures = request.headers.get('webhook-signature');
-    if (!id || !timestamp || !signatures) {
-        throw new PromptVerificationError('Missing signature headers');
-    }
-    const seconds = Number(timestamp);
-    if (!Number.isFinite(seconds) || Math.abs(now / 1000 - seconds) > tolerance) {
-        throw new PromptVerificationError('Timestamp outside the tolerance');
-    }
     const body = await request.text();
-    const key = await crypto.subtle.importKey('raw', base64ToBytes(secret.slice(SECRET_PREFIX.length)), {
-        name: 'HMAC',
-        hash: 'SHA-256'
-    }, false, [
-        'verify'
-    ]);
-    const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
-    let valid = false;
-    for (const signature of signatures.split(' ')){
-        const [version, value] = signature.split(',');
-        if (version !== 'v1' || !value) continue;
-        let bytes;
-        try {
-            bytes = base64ToBytes(value);
-        } catch  {
-            continue;
+    await verifySignature({
+        body,
+        id: request.headers.get('webhook-id'),
+        timestamp: request.headers.get('webhook-timestamp'),
+        signatures: request.headers.get('webhook-signature')
+    }, secret, {
+        tolerance,
+        now,
+        fail: (message)=>{
+            throw new PromptVerificationError(message);
         }
-        // crypto.subtle.verify compares in constant time.
-        if (await crypto.subtle.verify('HMAC', key, bytes, signed)) valid = true;
-    }
-    if (!valid) throw new PromptVerificationError('Invalid signature');
+    });
     let payload;
     try {
         payload = JSON.parse(body);

package/dist/standardWebhooks-ew5mhpac.mjs

@@ -0,0 +1,41 @@
+// Standard Webhooks (https://www.standardwebhooks.com/), the scheme the CMS
+// signs both webhooks and prompt requests with: HMAC-SHA256 over
+// `{id}.{timestamp}.{body}`, keyed with the base64 part of the `whsec_…`
+// secret, in `webhook-signature` as `v1,<base64>` (several, space-separated,
+// while a secret is rotated).
+const SECRET_PREFIX = 'whsec_';
+// Seconds a request's timestamp may be off, against replays.
+const DEFAULT_TOLERANCE = 5 * 60;
+const base64ToBytes = (value)=>Uint8Array.from(atob(value), (char)=>char.charCodeAt(0));
+// Checks a message's signature and timestamp; calls `fail` (which throws the
+// caller's own error) when it isn't from the CMS.
+const verifySignature = async ({ body, id, timestamp, signatures }, secret, { tolerance = DEFAULT_TOLERANCE, now = Date.now(), fail })=>{
+    if (!id || !timestamp || !signatures) fail('Missing signature headers');
+    const seconds = Number(timestamp);
+    if (!Number.isFinite(seconds) || Math.abs(now / 1000 - seconds) > tolerance) {
+        fail('Timestamp outside the tolerance');
+    }
+    const key = await crypto.subtle.importKey('raw', base64ToBytes(secret.slice(SECRET_PREFIX.length)), {
+        name: 'HMAC',
+        hash: 'SHA-256'
+    }, false, [
+        'verify'
+    ]);
+    const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
+    let valid = false;
+    for (const signature of signatures.split(' ')){
+        const [version, value] = signature.split(',');
+        if (version !== 'v1' || !value) continue;
+        let bytes;
+        try {
+            bytes = base64ToBytes(value);
+        } catch  {
+            continue;
+        }
+        // crypto.subtle.verify compares in constant time.
+        if (await crypto.subtle.verify('HMAC', key, bytes, signed)) valid = true;
+    }
+    if (!valid) fail('Invalid signature');
+};
+
+export { DEFAULT_TOLERANCE as D, SECRET_PREFIX as S, verifySignature as v };

package/dist/standardWebhooks-kh5dc0ff.js

@@ -0,0 +1,43 @@
+// Standard Webhooks (https://www.standardwebhooks.com/), the scheme the CMS
+// signs both webhooks and prompt requests with: HMAC-SHA256 over
+// `{id}.{timestamp}.{body}`, keyed with the base64 part of the `whsec_…`
+// secret, in `webhook-signature` as `v1,<base64>` (several, space-separated,
+// while a secret is rotated).
+const SECRET_PREFIX = 'whsec_';
+// Seconds a request's timestamp may be off, against replays.
+const DEFAULT_TOLERANCE = 5 * 60;
+const base64ToBytes = (value)=>Uint8Array.from(atob(value), (char)=>char.charCodeAt(0));
+// Checks a message's signature and timestamp; calls `fail` (which throws the
+// caller's own error) when it isn't from the CMS.
+const verifySignature = async ({ body, id, timestamp, signatures }, secret, { tolerance = DEFAULT_TOLERANCE, now = Date.now(), fail })=>{
+    if (!id || !timestamp || !signatures) fail('Missing signature headers');
+    const seconds = Number(timestamp);
+    if (!Number.isFinite(seconds) || Math.abs(now / 1000 - seconds) > tolerance) {
+        fail('Timestamp outside the tolerance');
+    }
+    const key = await crypto.subtle.importKey('raw', base64ToBytes(secret.slice(SECRET_PREFIX.length)), {
+        name: 'HMAC',
+        hash: 'SHA-256'
+    }, false, [
+        'verify'
+    ]);
+    const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
+    let valid = false;
+    for (const signature of signatures.split(' ')){
+        const [version, value] = signature.split(',');
+        if (version !== 'v1' || !value) continue;
+        let bytes;
+        try {
+            bytes = base64ToBytes(value);
+        } catch  {
+            continue;
+        }
+        // crypto.subtle.verify compares in constant time.
+        if (await crypto.subtle.verify('HMAC', key, bytes, signed)) valid = true;
+    }
+    if (!valid) fail('Invalid signature');
+};
+
+exports.DEFAULT_TOLERANCE = DEFAULT_TOLERANCE;
+exports.SECRET_PREFIX = SECRET_PREFIX;
+exports.verifySignature = verifySignature;

package/dist/webhooks.d.mts

@@ -0,0 +1,72 @@
+import { Environment } from './index.mjs';
+
+type WebhookEntry = {
+    id: string;
+    contentType: string;
+    name: string;
+    path: string | null;
+};
+type WebhookEventOf<TType extends string, TData> = {
+    type: TType;
+    timestamp: string;
+    space: string;
+    environment: Environment;
+    data: TData;
+};
+type EntryPublishedEvent = WebhookEventOf<'entry.published', {
+    entry: WebhookEntry;
+}>;
+type EntryUnpublishedEvent = WebhookEventOf<'entry.unpublished', {
+    entry: WebhookEntry;
+}>;
+type EntryDeletedEvent = WebhookEventOf<'entry.deleted', {
+    entry: WebhookEntry;
+}>;
+type EntryMovedEvent = WebhookEventOf<'entry.moved', {
+    entry: WebhookEntry;
+    previousPath: string | null;
+}>;
+type AssetUpdatedEvent = WebhookEventOf<'asset.updated', {
+    asset: {
+        id: string;
+        filename: string;
+    };
+    entries: WebhookEntry[];
+}>;
+type ModelChangedEvent = WebhookEventOf<'model.changed', {
+    contentTypes: {
+        apiId: string;
+        action: 'create' | 'update' | 'delete';
+    }[];
+}>;
+type LocalesChangedEvent = WebhookEventOf<'locales.changed', {
+    defaultLocale: string;
+    locales: string[];
+}>;
+type WebhookTestEvent = WebhookEventOf<'webhook.test', Record<string, never>>;
+type WebhookEvent = EntryPublishedEvent | EntryUnpublishedEvent | EntryDeletedEvent | EntryMovedEvent | AssetUpdatedEvent | ModelChangedEvent | LocalesChangedEvent | WebhookTestEvent;
+type WebhookEventType = WebhookEvent['type'];
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+type WebhookMessage = {
+    body: string;
+    headers: Headers | Record<string, string | string[] | undefined> | Iterable<[string, string]>;
+};
+type VerifyWebhookOptions = {
+    tolerance?: number | undefined;
+    now?: number;
+};
+declare const verifyWebhook: (request: Request | WebhookMessage, secret: string, { tolerance, now, }?: VerifyWebhookOptions) => Promise<WebhookEvent>;
+type WebhookHandlerOptions = {
+    secret: string;
+    onEvent: (event: WebhookEvent, meta: {
+        id: string;
+    }) => unknown;
+    tolerance?: number | undefined;
+};
+declare const createWebhookHandler: ({ secret, onEvent, tolerance }: WebhookHandlerOptions) => (request: Request) => Promise<Response>;
+
+export { WebhookVerificationError, createWebhookHandler, verifyWebhook };
+export type { AssetUpdatedEvent, EntryDeletedEvent, EntryMovedEvent, EntryPublishedEvent, EntryUnpublishedEvent, LocalesChangedEvent, ModelChangedEvent, VerifyWebhookOptions, WebhookEntry, WebhookEvent, WebhookEventType, WebhookHandlerOptions, WebhookMessage, WebhookTestEvent };
+//# sourceMappingURL=webhooks.d.mts.map

package/dist/webhooks.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.mts","sources":["../src/webhooks.ts"],"mappings":";;AACA,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA,KAAK,cAAc;AACnB;AACA;AACA;AACA,iBAAiB,WAAW;AAC5B;AACA;AACA,KAAK,mBAAmB,GAAG,cAAc;AACzC,WAAW,YAAY;AACvB;AACA,KAAK,qBAAqB,GAAG,cAAc;AAC3C,WAAW,YAAY;AACvB;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC,WAAW,YAAY;AACvB;AACA,KAAK,eAAe,GAAG,cAAc;AACrC,WAAW,YAAY;AACvB;AACA;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC;AACA;AACA;AACA;AACA,aAAa,YAAY;AACzB;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC;AACA;AACA;AACA;AACA;AACA,KAAK,mBAAmB,GAAG,cAAc;AACzC;AACA;AACA;AACA,KAAK,gBAAgB,GAAG,cAAc,iBAAiB,MAAM;AAC7D,KAAK,YAAY,GAAG,mBAAmB,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,eAAe,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,gBAAgB;AACtL,KAAK,gBAAgB,GAAG,YAAY;AACpC,cAAc,wBAAwB,SAAS,KAAK;AACpD;AACA;AACA,KAAK,cAAc;AACnB;AACA,aAAa,OAAO,GAAG,MAAM,0CAA0C,QAAQ;AAC/E;AACA,KAAK,oBAAoB;AACzB;AACA;AACA;AACA,cAAc,aAAa,YAAY,OAAO,GAAG,cAAc,wCAAwC,oBAAoB,KAAK,OAAO,CAAC,YAAY;AACpJ,KAAK,qBAAqB;AAC1B;AACA,qBAAqB,YAAY;AACjC;AACA;AACA;AACA;AACA,cAAc,oBAAoB,mCAAmC,qBAAqB,eAAe,OAAO,KAAK,OAAO,CAAC,QAAQ","names":[]}

package/dist/webhooks.d.ts

@@ -0,0 +1,72 @@
+import { Environment } from './index.js';
+
+type WebhookEntry = {
+    id: string;
+    contentType: string;
+    name: string;
+    path: string | null;
+};
+type WebhookEventOf<TType extends string, TData> = {
+    type: TType;
+    timestamp: string;
+    space: string;
+    environment: Environment;
+    data: TData;
+};
+type EntryPublishedEvent = WebhookEventOf<'entry.published', {
+    entry: WebhookEntry;
+}>;
+type EntryUnpublishedEvent = WebhookEventOf<'entry.unpublished', {
+    entry: WebhookEntry;
+}>;
+type EntryDeletedEvent = WebhookEventOf<'entry.deleted', {
+    entry: WebhookEntry;
+}>;
+type EntryMovedEvent = WebhookEventOf<'entry.moved', {
+    entry: WebhookEntry;
+    previousPath: string | null;
+}>;
+type AssetUpdatedEvent = WebhookEventOf<'asset.updated', {
+    asset: {
+        id: string;
+        filename: string;
+    };
+    entries: WebhookEntry[];
+}>;
+type ModelChangedEvent = WebhookEventOf<'model.changed', {
+    contentTypes: {
+        apiId: string;
+        action: 'create' | 'update' | 'delete';
+    }[];
+}>;
+type LocalesChangedEvent = WebhookEventOf<'locales.changed', {
+    defaultLocale: string;
+    locales: string[];
+}>;
+type WebhookTestEvent = WebhookEventOf<'webhook.test', Record<string, never>>;
+type WebhookEvent = EntryPublishedEvent | EntryUnpublishedEvent | EntryDeletedEvent | EntryMovedEvent | AssetUpdatedEvent | ModelChangedEvent | LocalesChangedEvent | WebhookTestEvent;
+type WebhookEventType = WebhookEvent['type'];
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+type WebhookMessage = {
+    body: string;
+    headers: Headers | Record<string, string | string[] | undefined> | Iterable<[string, string]>;
+};
+type VerifyWebhookOptions = {
+    tolerance?: number | undefined;
+    now?: number;
+};
+declare const verifyWebhook: (request: Request | WebhookMessage, secret: string, { tolerance, now, }?: VerifyWebhookOptions) => Promise<WebhookEvent>;
+type WebhookHandlerOptions = {
+    secret: string;
+    onEvent: (event: WebhookEvent, meta: {
+        id: string;
+    }) => unknown;
+    tolerance?: number | undefined;
+};
+declare const createWebhookHandler: ({ secret, onEvent, tolerance }: WebhookHandlerOptions) => (request: Request) => Promise<Response>;
+
+export { WebhookVerificationError, createWebhookHandler, verifyWebhook };
+export type { AssetUpdatedEvent, EntryDeletedEvent, EntryMovedEvent, EntryPublishedEvent, EntryUnpublishedEvent, LocalesChangedEvent, ModelChangedEvent, VerifyWebhookOptions, WebhookEntry, WebhookEvent, WebhookEventType, WebhookHandlerOptions, WebhookMessage, WebhookTestEvent };
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sources":["../src/webhooks.ts"],"mappings":";;AACA,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA,KAAK,cAAc;AACnB;AACA;AACA;AACA,iBAAiB,WAAW;AAC5B;AACA;AACA,KAAK,mBAAmB,GAAG,cAAc;AACzC,WAAW,YAAY;AACvB;AACA,KAAK,qBAAqB,GAAG,cAAc;AAC3C,WAAW,YAAY;AACvB;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC,WAAW,YAAY;AACvB;AACA,KAAK,eAAe,GAAG,cAAc;AACrC,WAAW,YAAY;AACvB;AACA;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC;AACA;AACA;AACA;AACA,aAAa,YAAY;AACzB;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC;AACA;AACA;AACA;AACA;AACA,KAAK,mBAAmB,GAAG,cAAc;AACzC;AACA;AACA;AACA,KAAK,gBAAgB,GAAG,cAAc,iBAAiB,MAAM;AAC7D,KAAK,YAAY,GAAG,mBAAmB,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,eAAe,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,gBAAgB;AACtL,KAAK,gBAAgB,GAAG,YAAY;AACpC,cAAc,wBAAwB,SAAS,KAAK;AACpD;AACA;AACA,KAAK,cAAc;AACnB;AACA,aAAa,OAAO,GAAG,MAAM,0CAA0C,QAAQ;AAC/E;AACA,KAAK,oBAAoB;AACzB;AACA;AACA;AACA,cAAc,aAAa,YAAY,OAAO,GAAG,cAAc,wCAAwC,oBAAoB,KAAK,OAAO,CAAC,YAAY;AACpJ,KAAK,qBAAqB;AAC1B;AACA,qBAAqB,YAAY;AACjC;AACA;AACA;AACA;AACA,cAAc,oBAAoB,mCAAmC,qBAAqB,eAAe,OAAO,KAAK,OAAO,CAAC,QAAQ","names":[]}

package/dist/webhooks.js

@@ -0,0 +1,110 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var standardWebhooks = require('./standardWebhooks-kh5dc0ff.js');
+
+// Webhooks from Obelism Content (the CMS's docs/guides/webhooks): one signed
+// POST per event (Standard Webhooks), telling your site what the delivery
+// API answers has changed. Verify it and revalidate:
+//
+//   // app/api/revalidate/route.ts
+//   import { revalidatePath } from 'next/cache'
+//   import { createWebhookHandler } from '@obelism/content/webhooks'
+//
+//   export const POST = createWebhookHandler({
+//     secret: process.env.CONTENT_WEBHOOK_SECRET!,
+//     onEvent: (event) => {
+//       if (event.type === 'entry.published' && event.data.entry.path) {
+//         revalidatePath(`/${event.data.entry.path}`)
+//       }
+//     },
+//   })
+class WebhookVerificationError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'WebhookVerificationError';
+    }
+}
+const headerReader = (headers)=>{
+    if (typeof headers.get === 'function') {
+        return (name)=>headers.get(name);
+    }
+    const lower = new Map();
+    const entries = Symbol.iterator in headers ? headers : Object.entries(headers);
+    for (const [name, value] of entries){
+        if (value === undefined) continue;
+        lower.set(name.toLowerCase(), Array.isArray(value) ? value.join(' ') : String(value));
+    }
+    return (name)=>lower.get(name) ?? null;
+};
+// Checks a webhook's signature and timestamp and returns its event. Throws
+// WebhookVerificationError when it isn't from the CMS, or too old.
+const verifyWebhook = async (request, secret, { tolerance = standardWebhooks.DEFAULT_TOLERANCE, now = Date.now() } = {})=>{
+    if (!secret?.startsWith(standardWebhooks.SECRET_PREFIX)) {
+        throw new Error('The webhook secret must be the whsec_… shown when the webhook was added');
+    }
+    // Not `instanceof Request`: frameworks may bring their own Request class.
+    const body = typeof request.body === 'string' ? request.body : await request.text();
+    const header = headerReader(request.headers);
+    await standardWebhooks.verifySignature({
+        body,
+        id: header('webhook-id'),
+        timestamp: header('webhook-timestamp'),
+        signatures: header('webhook-signature')
+    }, secret, {
+        tolerance,
+        now,
+        fail: (message)=>{
+            throw new WebhookVerificationError(message);
+        }
+    });
+    let event;
+    try {
+        event = JSON.parse(body);
+    } catch  {
+        throw new WebhookVerificationError('The body is not JSON');
+    }
+    if (typeof event?.type !== 'string') {
+        throw new WebhookVerificationError('The body is not a webhook event');
+    }
+    return event;
+};
+// A fetch-style handler (Request → Response) for the webhook's URL: Next.js
+// route handlers, Hono, Workers, Bun, Deno. Answers 401 to anything not
+// signed by the CMS, 204 once `onEvent` is done and 500 when it throws, so
+// the delivery is retried.
+const createWebhookHandler = ({ secret, onEvent, tolerance })=>async (request)=>{
+        let event;
+        try {
+            event = await verifyWebhook(request, secret, {
+                tolerance
+            });
+        } catch (error) {
+            if (error instanceof WebhookVerificationError) {
+                return Response.json({
+                    error: error.message
+                }, {
+                    status: 401
+                });
+            }
+            throw error;
+        }
+        try {
+            await onEvent(event, {
+                id: request.headers.get('webhook-id')
+            });
+        } catch (error) {
+            console.error('[@obelism/content webhooks]', error);
+            return Response.json({
+                error: 'Handling the event failed'
+            }, {
+                status: 500
+            });
+        }
+        return new Response(null, {
+            status: 204
+        });
+    };
+
+exports.WebhookVerificationError = WebhookVerificationError;
+exports.createWebhookHandler = createWebhookHandler;
+exports.verifyWebhook = verifyWebhook;

package/dist/webhooks.mjs

@@ -0,0 +1,106 @@
+import { S as SECRET_PREFIX, v as verifySignature, D as DEFAULT_TOLERANCE } from './standardWebhooks-ew5mhpac.mjs';
+
+// Webhooks from Obelism Content (the CMS's docs/guides/webhooks): one signed
+// POST per event (Standard Webhooks), telling your site what the delivery
+// API answers has changed. Verify it and revalidate:
+//
+//   // app/api/revalidate/route.ts
+//   import { revalidatePath } from 'next/cache'
+//   import { createWebhookHandler } from '@obelism/content/webhooks'
+//
+//   export const POST = createWebhookHandler({
+//     secret: process.env.CONTENT_WEBHOOK_SECRET!,
+//     onEvent: (event) => {
+//       if (event.type === 'entry.published' && event.data.entry.path) {
+//         revalidatePath(`/${event.data.entry.path}`)
+//       }
+//     },
+//   })
+class WebhookVerificationError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'WebhookVerificationError';
+    }
+}
+const headerReader = (headers)=>{
+    if (typeof headers.get === 'function') {
+        return (name)=>headers.get(name);
+    }
+    const lower = new Map();
+    const entries = Symbol.iterator in headers ? headers : Object.entries(headers);
+    for (const [name, value] of entries){
+        if (value === undefined) continue;
+        lower.set(name.toLowerCase(), Array.isArray(value) ? value.join(' ') : String(value));
+    }
+    return (name)=>lower.get(name) ?? null;
+};
+// Checks a webhook's signature and timestamp and returns its event. Throws
+// WebhookVerificationError when it isn't from the CMS, or too old.
+const verifyWebhook = async (request, secret, { tolerance = DEFAULT_TOLERANCE, now = Date.now() } = {})=>{
+    if (!secret?.startsWith(SECRET_PREFIX)) {
+        throw new Error('The webhook secret must be the whsec_… shown when the webhook was added');
+    }
+    // Not `instanceof Request`: frameworks may bring their own Request class.
+    const body = typeof request.body === 'string' ? request.body : await request.text();
+    const header = headerReader(request.headers);
+    await verifySignature({
+        body,
+        id: header('webhook-id'),
+        timestamp: header('webhook-timestamp'),
+        signatures: header('webhook-signature')
+    }, secret, {
+        tolerance,
+        now,
+        fail: (message)=>{
+            throw new WebhookVerificationError(message);
+        }
+    });
+    let event;
+    try {
+        event = JSON.parse(body);
+    } catch  {
+        throw new WebhookVerificationError('The body is not JSON');
+    }
+    if (typeof event?.type !== 'string') {
+        throw new WebhookVerificationError('The body is not a webhook event');
+    }
+    return event;
+};
+// A fetch-style handler (Request → Response) for the webhook's URL: Next.js
+// route handlers, Hono, Workers, Bun, Deno. Answers 401 to anything not
+// signed by the CMS, 204 once `onEvent` is done and 500 when it throws, so
+// the delivery is retried.
+const createWebhookHandler = ({ secret, onEvent, tolerance })=>async (request)=>{
+        let event;
+        try {
+            event = await verifyWebhook(request, secret, {
+                tolerance
+            });
+        } catch (error) {
+            if (error instanceof WebhookVerificationError) {
+                return Response.json({
+                    error: error.message
+                }, {
+                    status: 401
+                });
+            }
+            throw error;
+        }
+        try {
+            await onEvent(event, {
+                id: request.headers.get('webhook-id')
+            });
+        } catch (error) {
+            console.error('[@obelism/content webhooks]', error);
+            return Response.json({
+                error: 'Handling the event failed'
+            }, {
+                status: 500
+            });
+        }
+        return new Response(null, {
+            status: 204
+        });
+    };
+
+export { WebhookVerificationError, createWebhookHandler, verifyWebhook };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@obelism/content",
-	"description": "Obelism Content SDK: the delivery API client, the visual editor bridge with prompt editing, editing on your own site, and the content model CLI",
-	"version": "0.5.0",
+	"description": "Obelism Content SDK: the delivery API client, the visual editor bridge with prompt editing, editing on your own site, webhook verification, and the content model CLI",
+	"version": "0.6.0",
 	"keywords": [
 		"cms",
 		"headless-cms",
@@ -62,6 +62,16 @@
 				"types": "./dist/prompt.d.ts",
 				"default": "./dist/prompt.js"
 			}
+		},
+		"./webhooks": {
+			"import": {
+				"types": "./dist/webhooks.d.mts",
+				"default": "./dist/webhooks.mjs"
+			},
+			"require": {
+				"types": "./dist/webhooks.d.ts",
+				"default": "./dist/webhooks.js"
+			}
 		}
 	},
 	"scripts": {