@obelism/content 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obelism
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# Obelism Content JS SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```bash
+npm i @obelism/content
+```
+
+## ContentClient
+
+Reads one space environment through the delivery API. The token decides the
+space, the environment and whether drafts are visible: a delivery token
+(`cms_d_…`) sees published content, a preview token (`cms_p_…`) drafts too.
+Keep preview tokens server-side.
+
+```ts
+import { ContentClient } from '@obelism/content'
+
+const content = new ContentClient({
+	token: process.env.CONTENT_DELIVERY_TOKEN,
+	// url: 'https://content.obelism.studio',
+	// locale: 'nl', depth: 1, richText: 'json', timeout: 10_000,
+	// init: { next: { revalidate: 60 } },   // passed to every fetch
+})
+
+await content.getPage('blog/hello') //       Entry | null
+await content.getEntry('entry_…') //         Entry | null
+await content.getEntries({ contentType: 'post', limit: 20, skip: 0 }) // { items, total, limit, skip }
+for await (const post of content.getAllEntries({ contentType: 'post' })) {
+}
+await content.getContentModel() //          the model file
+```
+
+Each method takes `{ locale, depth, richText, init }` to override the
+defaults. Missing pages and entries are `null`; any other failure throws a
+`ContentApiError` with `status` and the API's `message`. Type your content
+with generics: `content.getPage<Entry<{ title: string }>>('home')`.
+
+## Preview
+
+The visual editor loads your site with `?cms_preview=1&cms_entry=…&cms_environment=…`.
+
+```ts
+import { readPreviewParams } from '@obelism/content'
+
+const client = readPreviewParams(request.url) ? previewClient : deliveryClient
+```
+
+## Visual editor bridge
+
+```ts
+import { getContentBridge } from '@obelism/content/bridge'
+
+const bridge = getContentBridge()
+bridge.on('update', ({ entry }) => render(entry)) // unsaved edits, as typed
+```
+
+Mark blocks so editors can click them: `<section {...editable(block)}>`
+(adds `data-cms-uid`). Without an `update` listener the page reloads after
+each save. It replaces the `<script src=".../bridge.js">` tag; when a page has
+both, it wraps the script's bridge instead of starting a second one. React
+sites use `@obelism/content-react`.
+
+## Prompt editing
+
+Inside the visual editor, people who may edit get a prompt box at the bottom
+of the page: they type what to change and it shows on the page right away,
+unsaved, with undo. It acts on the selected block, or the whole entry. The
+bridge adds it by default; it needs nothing from your site.
+
+```ts
+getContentBridge({ prompt: false }) // leave it out
+getContentBridge({ prompt: { labels: { open: 'Bewerk met een prompt' } } })
+
+// Your own UI instead:
+const bridge = getContentBridge({ prompt: false })
+bridge.on('change', ({ features, prompting, canUndo, selectedUid }) => …)
+const { summary } = await bridge.prompt('Make the heading shorter')
+bridge.undo()
+```
+
+The CMS runs prompts on Workers AI. To use your own model, set a prompt
+endpoint under Space settings → Prompt editing and answer it with
+`createPromptHandler` (it verifies the signed request; you call the model):
+
+```ts
+// app/api/content-prompt/route.ts
+import { createPromptHandler } from '@obelism/content/prompt'
+
+export const POST = createPromptHandler({
+	secret: process.env.CONTENT_PROMPT_SECRET, // whsec_… from Space settings
+	generate: async ({ system, messages, schema }) => {
+		// call any model; return its JSON answer (object or text)
+	},
+})
+```
+
+## Helpers
+
+- `richTextToHtml(doc, { renderEntry?, renderAsset? })`, `richTextToPlainText(doc)`
+- `imageUrl(asset, { w, h, fit, format, q })`, `imageSrcSet(asset, [480, 960])`
+
+## CLI
+
+Keeps a content model file in Git in step with an environment.
+
+```bash
+export CONTENT_MANAGEMENT_TOKEN=cms_m_…
+npx @obelism/content model pull    # write content/content-model.json
+npx @obelism/content model plan    # what applying would change
+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.

package/dist/bin/content.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+var node_util = require('node:util');
+var config = require('../config-ci2hxmas.js');
+var promises = require('node:fs/promises');
+var node_path = require('node:path');
+
+// Turns a model plan from the management API into text for a terminal, or
+// Markdown for a GitHub step summary or pull request comment.
+const ACTION_SIGN = {
+    create: '+',
+    update: '~',
+    delete: '-'
+};
+const FIELD_SIGN = {
+    added: '+',
+    removed: '-',
+    changed: '~'
+};
+const plural = (count, one, many)=>`${count} ${count === 1 ? one : many}`;
+const describeChange = (change)=>{
+    const details = [];
+    for (const field of change.fields ?? []){
+        details.push(`${FIELD_SIGN[field.change] ?? '~'} field ${field.apiId}`);
+    }
+    if (change.reordered) details.push('fields reordered');
+    if (change.settingsChanged && change.action === 'update') {
+        details.push('name, kind or description');
+    }
+    if (change.affectedEntries && change.affectedEntries > 0) {
+        details.push(`removes values from ${plural(change.affectedEntries, 'entry', 'entries')}`);
+    }
+    return details;
+};
+const issueLine = ({ contentType, path, message })=>`${[
+        contentType,
+        path
+    ].filter(Boolean).join(' › ')}: ${message}`;
+// `applied` says whether the plan already happened.
+const formatPlan = (plan, { markdown = false, applied = false } = {})=>{
+    const changes = plan.changes ?? [];
+    const issues = plan.issues ?? [];
+    const lines = [];
+    if (markdown) {
+        lines.push(applied ? '### Content model applied' : '### Content model plan', '');
+    }
+    if (issues.length > 0) {
+        const count = plural(issues.length, 'problem', 'problems');
+        lines.push(markdown ? `**${count} — nothing can be applied:**` : `${count}; nothing can be applied:`);
+        for (const issue of issues){
+            lines.push(`${markdown ? '- ' : '  '}${issueLine(issue)}`);
+        }
+        lines.push('');
+    }
+    if (changes.length === 0) {
+        lines.push(issues.length > 0 ? 'No other changes.' : 'No changes: the environment matches the file.');
+    } else {
+        lines.push(`${plural(changes.length, 'content type', 'content types')} ${applied ? 'changed' : 'to change'}:`);
+        if (markdown) lines.push('', '```diff');
+        for (const change of changes){
+            lines.push(`${ACTION_SIGN[change.action] ?? '~'} ${change.apiId} (${change.name})`);
+            for (const detail of describeChange(change))lines.push(`    ${detail}`);
+        }
+        if (markdown) lines.push('```');
+    }
+    return lines.join('\n');
+};
+
+// `content model pull | plan | apply`: keeps a content model file in a
+// repository in step with an environment. The token comes from
+// $CONTENT_MANAGEMENT_TOKEN, never from an argument, so it stays out of shell
+// history and CI logs. In GitHub Actions the plan also goes to the job
+// summary.
+class CliError extends Error {
+    constructor(message, exitCode = 1){
+        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)=>{
+        const response = await fetchImpl(`${url}${config.MANAGEMENT_PATH}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                ...body !== undefined && {
+                    'Content-Type': 'application/json'
+                }
+            },
+            ...body !== undefined && {
+                body: JSON.stringify(body)
+            }
+        }).catch((error)=>{
+            throw new CliError(`Could not reach ${url}: ${error.message}`);
+        });
+        const text = await response.text();
+        try {
+            return {
+                status: response.status,
+                ok: response.ok,
+                json: JSON.parse(text)
+            };
+        } catch  {
+            throw new CliError(`${response.status} from ${url}: ${text.slice(0, 200)}`);
+        }
+    };
+    if (command === 'pull') {
+        const { ok, json } = await call('GET', '/model');
+        if (!ok) throw new CliError(String(json.error ?? 'Pull failed'));
+        await promises.mkdir(node_path.dirname(file), {
+            recursive: true
+        });
+        await promises.writeFile(file, `${JSON.stringify(json, null, '\t')}\n`);
+        const count = Array.isArray(json.contentTypes) ? json.contentTypes.length : 0;
+        log(`Wrote ${count} ${count === 1 ? 'content type' : 'content types'} to ${file}.`);
+        return 0;
+    }
+    let text;
+    try {
+        text = await promises.readFile(file, 'utf8');
+    } catch  {
+        throw new CliError(`Can't read ${file}. Run \`content model pull\` first?`);
+    }
+    let model;
+    try {
+        model = JSON.parse(text);
+    } catch (error) {
+        throw new CliError(`${file} is not valid JSON: ${error.message}`);
+    }
+    const { ok, status, json } = await call('POST', command === 'plan' ? '/model/plan' : '/model/apply', {
+        model,
+        prune
+    });
+    // A plan with issues, or an apply refused for them, still has the plan.
+    const plan = json.changes || json.issues ? json : null;
+    if (!plan) throw new CliError(String(json.error ?? `${command} failed (${status})`));
+    const applied = command === 'apply' && ok;
+    log(formatPlan(plan, {
+        applied
+    }));
+    if (summaryFile) {
+        await promises.appendFile(summaryFile, `${formatPlan(plan, {
+            markdown: true,
+            applied
+        })}\n`);
+    }
+    return !ok || (plan.issues?.length ?? 0) > 0 ? 1 : 0;
+};
+
+const USAGE = `Usage: content model <pull|plan|apply> [--file path] [--url origin] [--prune]
+
+  pull    write the environment's model to the file
+  plan    show what applying the file would change, and what stands in the way
+  apply   apply the file in one transaction, or change nothing
+
+  --file   the model file (default content/content-model.json)
+  --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.`;
+const main = async ()=>{
+    let parsed;
+    try {
+        parsed = node_util.parseArgs({
+            allowPositionals: true,
+            options: {
+                file: {
+                    type: 'string',
+                    default: 'content/content-model.json'
+                },
+                url: {
+                    type: 'string'
+                },
+                prune: {
+                    type: 'boolean',
+                    default: false
+                },
+                help: {
+                    type: 'boolean',
+                    short: 'h',
+                    default: false
+                }
+            }
+        });
+    } catch (error) {
+        throw new CliError(`${error.message}\n\n${USAGE}`, 2);
+    }
+    const { values, positionals } = parsed;
+    const [group, command] = positionals;
+    if (values.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (group !== 'model' || command !== 'pull' && command !== 'plan' && command !== 'apply') {
+        throw new CliError(USAGE, 2);
+    }
+    const token = process.env.CONTENT_MANAGEMENT_TOKEN;
+    if (!token) {
+        throw new CliError(`CONTENT_MANAGEMENT_TOKEN is not set.\n\n${USAGE}`, 2);
+    }
+    return runModelCommand({
+        command,
+        file: values.file,
+        url: config.normalizeUrl(values.url ?? process.env.CONTENT_URL ?? config.DEFAULT_URL),
+        token,
+        prune: values.prune,
+        summaryFile: process.env.GITHUB_STEP_SUMMARY || undefined
+    });
+};
+main().then((code)=>process.exit(code), (error)=>{
+    if (error instanceof CliError) {
+        console.error(error.message);
+        process.exit(error.exitCode);
+    }
+    console.error(error);
+    process.exit(1);
+});

package/dist/bridge.d.mts

@@ -0,0 +1,82 @@
+import { Entry } from './index.mjs';
+
+type BridgeEvents = {
+    update: {
+        entry: Entry;
+        selectedUid: string | null;
+    };
+    saved: Record<string, never>;
+    published: Record<string, never>;
+    change: BridgeState;
+};
+type BridgeEvent = keyof BridgeEvents;
+type BridgeListener<E extends BridgeEvent> = (payload: BridgeEvents[E]) => void;
+type BridgeState = {
+    features: readonly string[];
+    selectedUid: string | null;
+    prompting: boolean;
+    canUndo: boolean;
+    unsaved: boolean;
+    saving: boolean;
+    publishing: boolean;
+    selecting: boolean;
+};
+type PromptResult = {
+    summary: string;
+};
+type ContentBridge = {
+    readonly isEditing: boolean;
+    readonly mode: 'editor' | 'site' | null;
+    readonly entryId: string | null;
+    readonly environment: string | null;
+    on<E extends BridgeEvent>(event: E, listener: BridgeListener<E>): () => void;
+    getState(): BridgeState;
+    prompt(prompt: string, options?: {
+        uid?: string | null;
+    }): Promise<PromptResult>;
+    undo(): void;
+    save(): Promise<void>;
+    publish(): Promise<void>;
+    signOut(): void;
+    setSelecting(selecting: boolean): void;
+    select(uid: string | null): void;
+    destroy(): void;
+};
+declare const INITIAL_STATE: BridgeState;
+
+type PromptLabels = {
+    open: string;
+    placeholder: string;
+    send: string;
+    undo: string;
+    close: string;
+    scopeEntry: string;
+    scopeBlock: string;
+    clearBlock: string;
+    working: string;
+    save: string;
+    publish: string;
+    saving: string;
+    publishing: string;
+    saved: string;
+    published: string;
+    unsaved: string;
+    signOut: string;
+    viewingDrafts: string;
+    selectHint: string;
+};
+declare const DEFAULT_PROMPT_LABELS: PromptLabels;
+type PromptBoxOptions = {
+    labels?: Partial<PromptLabels> | undefined;
+};
+
+type BridgeOptions = {
+    url?: string | undefined;
+    prompt?: boolean | PromptBoxOptions | undefined;
+};
+declare const peekContentBridge: () => ContentBridge | null;
+declare const getContentBridge: ({ url, prompt, }?: BridgeOptions) => ContentBridge;
+
+export { DEFAULT_PROMPT_LABELS, INITIAL_STATE, getContentBridge, peekContentBridge };
+export type { BridgeEvent, BridgeEvents, BridgeListener, BridgeOptions, BridgeState, ContentBridge, PromptBoxOptions, PromptLabels, PromptResult };
+//# sourceMappingURL=bridge.d.mts.map

package/dist/bridge.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.mts","sources":["../src/bridge/createBridge.ts","../src/bridge/promptBox.ts","../src/bridge.ts"],"mappings":";;AAIA,KAAK,YAAY;AACjB;AACA,eAAe,KAAK;AACpB;AACA;AACA,WAAW,MAAM;AACjB,eAAe,MAAM;AACrB,YAAY,WAAW;AACvB;AACA,KAAK,WAAW,SAAS,YAAY;AACrC,KAAK,cAAc,WAAW,WAAW,cAAc,YAAY;AACnE,KAAK,WAAW;AAChB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,YAAY;AACjB;AACA;AACA,KAAK,aAAa;AAClB;AACA;AACA;AACA;AACA,iBAAiB,WAAW,sBAAsB,cAAc;AAChE,gBAAgB,WAAW;AAC3B;AACA;AACA,QAAQ,OAAO,CAAC,YAAY;AAC5B;AACA,YAAY,OAAO;AACnB,eAAe,OAAO;AACtB;AACA;AACA;AACA;AACA;AAEA,cAAc,aAAa,EAAE,WAAW;;AC9CxC,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,cAAc,qBAAqB,EAAE,YAAY;AACjD,KAAK,gBAAgB;AACrB,aAAa,OAAO,CAAC,YAAY;AACjC;;ACnBA,KAAK,aAAa;AAClB;AACA,uBAAuB,gBAAgB;AACvC;AACA,cAAc,iBAAiB,QAAQ,aAAa;AACpD,cAAc,gBAAgB,sBAAsB,aAAa,KAAK,aAAa","names":[]}

package/dist/bridge.d.ts

@@ -0,0 +1,82 @@
+import { Entry } from './index.js';
+
+type BridgeEvents = {
+    update: {
+        entry: Entry;
+        selectedUid: string | null;
+    };
+    saved: Record<string, never>;
+    published: Record<string, never>;
+    change: BridgeState;
+};
+type BridgeEvent = keyof BridgeEvents;
+type BridgeListener<E extends BridgeEvent> = (payload: BridgeEvents[E]) => void;
+type BridgeState = {
+    features: readonly string[];
+    selectedUid: string | null;
+    prompting: boolean;
+    canUndo: boolean;
+    unsaved: boolean;
+    saving: boolean;
+    publishing: boolean;
+    selecting: boolean;
+};
+type PromptResult = {
+    summary: string;
+};
+type ContentBridge = {
+    readonly isEditing: boolean;
+    readonly mode: 'editor' | 'site' | null;
+    readonly entryId: string | null;
+    readonly environment: string | null;
+    on<E extends BridgeEvent>(event: E, listener: BridgeListener<E>): () => void;
+    getState(): BridgeState;
+    prompt(prompt: string, options?: {
+        uid?: string | null;
+    }): Promise<PromptResult>;
+    undo(): void;
+    save(): Promise<void>;
+    publish(): Promise<void>;
+    signOut(): void;
+    setSelecting(selecting: boolean): void;
+    select(uid: string | null): void;
+    destroy(): void;
+};
+declare const INITIAL_STATE: BridgeState;
+
+type PromptLabels = {
+    open: string;
+    placeholder: string;
+    send: string;
+    undo: string;
+    close: string;
+    scopeEntry: string;
+    scopeBlock: string;
+    clearBlock: string;
+    working: string;
+    save: string;
+    publish: string;
+    saving: string;
+    publishing: string;
+    saved: string;
+    published: string;
+    unsaved: string;
+    signOut: string;
+    viewingDrafts: string;
+    selectHint: string;
+};
+declare const DEFAULT_PROMPT_LABELS: PromptLabels;
+type PromptBoxOptions = {
+    labels?: Partial<PromptLabels> | undefined;
+};
+
+type BridgeOptions = {
+    url?: string | undefined;
+    prompt?: boolean | PromptBoxOptions | undefined;
+};
+declare const peekContentBridge: () => ContentBridge | null;
+declare const getContentBridge: ({ url, prompt, }?: BridgeOptions) => ContentBridge;
+
+export { DEFAULT_PROMPT_LABELS, INITIAL_STATE, getContentBridge, peekContentBridge };
+export type { BridgeEvent, BridgeEvents, BridgeListener, BridgeOptions, BridgeState, ContentBridge, PromptBoxOptions, PromptLabels, PromptResult };
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sources":["../src/bridge/createBridge.ts","../src/bridge/promptBox.ts","../src/bridge.ts"],"mappings":";;AAIA,KAAK,YAAY;AACjB;AACA,eAAe,KAAK;AACpB;AACA;AACA,WAAW,MAAM;AACjB,eAAe,MAAM;AACrB,YAAY,WAAW;AACvB;AACA,KAAK,WAAW,SAAS,YAAY;AACrC,KAAK,cAAc,WAAW,WAAW,cAAc,YAAY;AACnE,KAAK,WAAW;AAChB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,YAAY;AACjB;AACA;AACA,KAAK,aAAa;AAClB;AACA;AACA;AACA;AACA,iBAAiB,WAAW,sBAAsB,cAAc;AAChE,gBAAgB,WAAW;AAC3B;AACA;AACA,QAAQ,OAAO,CAAC,YAAY;AAC5B;AACA,YAAY,OAAO;AACnB,eAAe,OAAO;AACtB;AACA;AACA;AACA;AACA;AAEA,cAAc,aAAa,EAAE,WAAW;;AC9CxC,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,cAAc,qBAAqB,EAAE,YAAY;AACjD,KAAK,gBAAgB;AACrB,aAAa,OAAO,CAAC,YAAY;AACjC;;ACnBA,KAAK,aAAa;AAClB;AACA,uBAAuB,gBAAgB;AACvC;AACA,cAAc,iBAAiB,QAAQ,aAAa;AACpD,cAAc,gBAAgB,sBAAsB,aAAa,KAAK,aAAa","names":[]}