@viglet/shio-client 2026.2.1 → 2026.3.3

package/README.md

@@ -1,11 +1,18 @@
 # @viglet/shio-client
 
-Framework-agnostic TypeScript client for the **Shio CMS Content Delivery API (CDA)**.
+[![npm](https://img.shields.io/npm/v/@viglet/shio-client?logo=npm)](https://www.npmjs.com/package/@viglet/shio-client)
+[![License](https://img.shields.io/npm/l/@viglet/shio-client)](https://github.com/openviglet/shio/blob/HEAD/LICENSE)
+[![Website](https://img.shields.io/badge/website-0ea5e9?logo=googlechrome&logoColor=white)](https://openviglet.github.io/shio/)
+
+Framework-agnostic **TypeScript client** for the Content Delivery API (CDA) of
+**[Viglet Shio](https://openviglet.github.io/shio/)**, the open source, **agent-ready CMS
+for coding agents**.
 
 - **Zero runtime dependencies** — just `fetch`.
 - Runs in **Node, the browser, edge runtimes, Next.js server components, Astro, Vue, Svelte** and plain scripts.
 - Targets the stable, read-only CDA contract (`/api/v2/cda/**`) — no Java, no legacy console API.
-- This is the **base** SDK; `@viglet/shio-react-sdk` is one consumer of it.
+- This is the **base** SDK; [`@viglet/shio-react-sdk`](https://www.npmjs.com/package/@viglet/shio-react-sdk) is one consumer of it.
+- Pair it with [`@viglet/shio`](https://www.npmjs.com/package/@viglet/shio) — `shio types` generates a `.d.ts` from your live content model, so `post.attrs.*` autocompletes.
 
 ## Install
 
@@ -34,16 +41,41 @@ console.log(post?.attrs.title);
 |---|---|---|
 | `getSites()` | `GET /site` | `ShioSite[]` |
 | `getSite(siteId)` | `GET /site/{id}` | `ShioSite \| null` |
-| `listChildren(folderId, {page,size})` | `GET /object/{id}/list` | `ShioListing \| null` |
+| `listChildren(folderId, {page,size,locale})` | `GET /object/{id}/list` | `ShioListing \| null` |
 | `getPath(objectId)` | `GET /object/{id}/path` | `ShioPath \| null` |
 | `getPost(postId)` | `GET /post/{id}` | `ShioPost \| null` |
-| `getPostByUrl(siteId, url)` | `GET /post/by-url` | `ShioPost \| null` |
-| `query({siteId,folderId,postType,page,size})` | `GET /query` | `ShioListing` |
+| `getPostByUrl(siteId, url, locale?)` | `GET /post/by-url` | `ShioPost \| null` |
+| `query({siteId,folderId,postType,page,size,locale})` | `GET /query` | `ShioListing` |
 
 - Single-resource getters return `null` on `404`.
 - Any other non-OK status throws `ShioHttpError` (`{ status, url, body }`).
 - Every method accepts a final `{ signal }` option for cancellation.
 
+## A language switcher
+
+A site's `locales` says which languages it offers; a post's `availableLocales` says which of
+them this page exists in. Together they are a switcher, with no call beyond the two you
+already make:
+
+```ts
+const site = await shio.getSite(siteId);
+// null when the post at `url` is in another language; its availableLocales say which exist
+const post = await shio.getPostByUrl(siteId, url, locale) ?? await shio.getPostByUrl(siteId, url);
+
+const offered = site?.locales?.enabled ?? [];
+const links = offered.map((tag) => ({
+  tag,
+  // a language this page is missing in shows the site's fallback for it, else its default
+  target: post?.availableLocales.includes(tag)
+    ? tag
+    : site?.locales?.fallback[tag] ?? site?.locales?.defaultLocale,
+}));
+```
+
+`locales.declared` is `false` when nobody has chosen the site's languages yet. The list is
+then the languages its published pages are already written in, which is a description of the
+content so far rather than a promise about it.
+
 ## Next.js App Router — catch-all page
 
 The `getPostByUrl` call is built for `[...slug]` routing:
@@ -95,6 +127,20 @@ npm run typecheck  # tsc --noEmit
 npm test           # node:test, no network (injected fetch)
 ```
 
+## Related packages
+
+| Package | For |
+|---|---|
+| [`@viglet/shio`](https://www.npmjs.com/package/@viglet/shio) | The Shio CLI — content as files, type generation, and the MCP bridge for [Claude Code](https://claude.com/claude-code) |
+| [`@viglet/shio-react-sdk`](https://www.npmjs.com/package/@viglet/shio-react-sdk) | React hooks and render components built on this client |
+| [`@viglet/shio-sections`](https://www.npmjs.com/package/@viglet/shio-sections) | The page-section vocabulary |
+| [`@viglet/shio-model`](https://www.npmjs.com/package/@viglet/shio-model) | Author the content model as typed code |
+| [`@viglet/shio-editor-cors`](https://www.npmjs.com/package/@viglet/shio-editor-cors) | Inline visual editing with the Universal Editor |
+| [`@viglet/create-shio-app`](https://www.npmjs.com/package/@viglet/create-shio-app) | Next.js starter generator |
+
 ## License
 
-GPL-3.0
+Apache-2.0 — [Viglet Shio](https://openviglet.github.io/shio/) ·
+[github.com/openviglet/shio](https://github.com/openviglet/shio) ·
+[docs.viglet.org/shio](https://docs.viglet.org/shio/) ·
+part of the [Viglet](https://www.viglet.org) open source family.

package/bin/shio-types.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/*
+ * Copyright (C) 2016-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0.
+ *
+ * shio-types — generate a TypeScript `.d.ts` from a Shio instance's post-types
+ * (SH11). Fetches `/api/v2/cda/post-type` and writes typed `Post` interfaces so
+ * page code gets autocomplete on `post.attrs.*`.
+ *
+ *   npx shio-types --url http://localhost:2710 --token <CDA token> --out lib/shio-types.d.ts
+ *
+ * Env fallbacks: SHIO_URL, SHIO_CDA_TOKEN.
+ */
+import { writeFile } from "node:fs/promises";
+import { argv, env, exit, stdout } from "node:process";
+
+import { ShioClient, generateShioTypes } from "../dist/shio-client.js";
+
+const HELP = `shio-types — generate TypeScript types from Shio post-types
+
+Usage:
+  shio-types [options]
+
+Options:
+  --url <baseUrl>       Shio base URL        (env SHIO_URL, default http://localhost:2710)
+  --token <token>       CDA token            (env SHIO_CDA_TOKEN)
+  --out <file>          Output .d.ts path    (default shio-types.d.ts; "-" for stdout)
+  --import-from <mod>   Module to import ShioPost from (default @viglet/shio-client)
+  -h, --help            Show this help
+`;
+
+function parseArgs(args) {
+  const opts = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case "-h":
+      case "--help":
+        opts.help = true;
+        break;
+      case "--url":
+        opts.url = args[++i];
+        break;
+      case "--token":
+        opts.token = args[++i];
+        break;
+      case "--out":
+        opts.out = args[++i];
+        break;
+      case "--import-from":
+        opts.importFrom = args[++i];
+        break;
+      default:
+        fail(`Unknown argument: ${a}\n\n${HELP}`);
+    }
+  }
+  return opts;
+}
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  exit(1);
+}
+
+async function main() {
+  const opts = parseArgs(argv.slice(2));
+  if (opts.help) {
+    stdout.write(HELP);
+    return;
+  }
+
+  const baseUrl = opts.url ?? env.SHIO_URL ?? "http://localhost:2710";
+  const apiToken = opts.token ?? env.SHIO_CDA_TOKEN;
+  const out = opts.out ?? "shio-types.d.ts";
+
+  const client = new ShioClient({ baseUrl, apiToken });
+
+  let schemas;
+  try {
+    schemas = await client.getPostTypes();
+  } catch (err) {
+    fail(`shio-types: failed to fetch post-types from ${baseUrl}\n  ${err?.message ?? err}`);
+  }
+
+  const source = generateShioTypes(schemas, {
+    importFrom: opts.importFrom,
+  });
+
+  if (out === "-") {
+    stdout.write(source);
+    return;
+  }
+
+  await writeFile(out, source, "utf8");
+  stdout.write(`shio-types: wrote ${schemas.length} post-type(s) to ${out}\n`);
+}
+
+main().catch((err) => fail(`shio-types: ${err?.stack ?? err}`));

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { ShioClientConfig, ShioListing, ShioPageParams, ShioPath, ShioPost, ShioQueryParams, ShioRequestOptions, ShioSite } from "./types";
+import type { ShioClientConfig, ShioListing, ShioPageParams, ShioPath, ShioPost, ShioPostTypeSchema, ShioQueryParams, ShioReadOptions, ShioRedirect, ShioRequestOptions, ShioSite } from "./types";
 /**
  * Framework-agnostic client for the Shio Content Delivery API (CDA, SH1).
  *
@@ -22,17 +22,44 @@ export declare class ShioClient {
     getSites(opts?: ShioRequestOptions): Promise<ShioSite[]>;
     /** Get one site (with its root folder id), or `null` if not found. */
     getSite(siteId: string, opts?: ShioRequestOptions): Promise<ShioSite | null>;
+    /**
+     * A site's redirect table (SH1133), ordered by `from`, or `null` if the site is unknown.
+     *
+     * Small and site-scoped, so a front end can hold it and consult it before a 404 rather than
+     * asking per request. A production token sees published redirects only.
+     */
+    getRedirects(siteId: string, opts?: ShioRequestOptions): Promise<ShioRedirect[] | null>;
     /** List a folder's children (subfolders + published posts), or `null` if the folder is unknown. */
     listChildren(folderId: string, params?: ShioPageParams, opts?: ShioRequestOptions): Promise<ShioListing | null>;
     /** Get the breadcrumb path for a folder or post, or `null` if unknown. */
     getPath(objectId: string, opts?: ShioRequestOptions): Promise<ShioPath | null>;
-    /** Get a published post by id (attributes expanded), or `null` if not found / not published. */
-    getPost(postId: string, opts?: ShioRequestOptions): Promise<ShioPost | null>;
+    /**
+     * Get a published post by id (attributes expanded), or `null` if not found / not published.
+     *
+     * SH1081 — `opts.state` asks for another version: `"draft"` or `"rev:<n>"` with a preview token.
+     */
+    getPost(postId: string, opts?: ShioReadOptions): Promise<ShioPost | null>;
     /**
      * Resolve a published post by site + friendly URL — the call behind catch-all
      * routing (e.g. Next.js `[...slug]`). Returns `null` if unresolved.
+     *
+     * SH1057 — pass a `locale` as the third argument to resolve only the translation
+     * in that language: `getPostByUrl(siteId, "/about", "pt-br")` is `null` when the
+     * post at `/about` is in another language, and its `availableLocales` says which.
+     *
+     * SH1081 — `opts.state` asks for another version, as on {@link getPost}: a draft preview of
+     * one page is `getPostByUrl(siteId, "/about", { state: "draft" })` with a preview token.
+     */
+    getPostByUrl(siteId: string, url: string, opts?: ShioReadOptions): Promise<ShioPost | null>;
+    getPostByUrl(siteId: string, url: string, locale: string, opts?: ShioReadOptions): Promise<ShioPost | null>;
+    /**
+     * List every post-type's content-model schema — the input to
+     * {@link generateShioTypes}. The schema is global (not site-scoped), so a
+     * per-site token sees every post-type.
      */
-    getPostByUrl(siteId: string, url: string, opts?: ShioRequestOptions): Promise<ShioPost | null>;
+    getPostTypes(opts?: ShioRequestOptions): Promise<ShioPostTypeSchema[]>;
+    /** Get one post-type's content-model schema by its API name, or `null` if unknown. */
+    getPostType(name: string, opts?: ShioRequestOptions): Promise<ShioPostTypeSchema | null>;
     /** Query published posts by site / folder / post type (always returns a listing). */
     query(params?: ShioQueryParams, opts?: ShioRequestOptions): Promise<ShioListing>;
     private send;

package/dist/codegen.d.ts

@@ -0,0 +1,30 @@
+/**
+ * TypeScript code generation from Shio post-type schemas (SH11).
+ *
+ * Pure and dependency-free: it turns the {@link ShioPostTypeSchema}[] returned by
+ * {@link ShioClient.getPostTypes} into a `.d.ts` source string. The `shio-types`
+ * CLI ({@link file:../bin/shio-types.mjs}) wires the fetch + file write around it;
+ * keeping the transform pure makes it testable without a network or a filesystem.
+ */
+import type { ShioPostTypeSchema } from "./types";
+/** Options for {@link generateShioTypes}. */
+export interface GenerateTypesOptions {
+    /**
+     * The module the generated `Post` interfaces import `ShioPost` from. Defaults
+     * to the published package name; set to a relative path when generating into
+     * the SDK's own source tree.
+     */
+    importFrom?: string;
+    /** Override the file banner comment (e.g. to pin a version). */
+    banner?: string;
+}
+/**
+ * Generate `.d.ts` source declaring one typed `Post` interface per post-type,
+ * plus a `ShioPostTypes` name→type map. Page code then gets autocomplete on
+ * `post.attrs.*`.
+ *
+ * @example
+ * const schemas = await client.getPostTypes();
+ * await writeFile("shio-types.d.ts", generateShioTypes(schemas));
+ */
+export declare function generateShioTypes(schemas: ShioPostTypeSchema[], options?: GenerateTypesOptions): string;

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export { ShioClient, createShioClient } from "./client";
 export { ShioHttpError } from "./errors";
-export type { ShioClientConfig, ShioRequestOptions, ShioSite, ShioFolder, ShioPostSummary, ShioPost, ShioListing, ShioPath, ShioQueryParams, ShioPageParams, } from "./types";
+export { generateShioTypes } from "./codegen";
+export type { GenerateTypesOptions } from "./codegen";
+export type { ShioClientConfig, ShioRequestOptions, ShioContentState, ShioReadOptions, ShioSite, ShioSiteLocales, ShioRedirect, ShioFolder, ShioPostSummary, ShioPost, ShioListing, ShioPath, ShioQueryParams, ShioPageParams, ShioFieldSchema, ShioPostTypeSchema, ShioBlock, ShioBlockMark, } from "./types";
+export { SHIO_BLOCK_TYPES, shioBlocks } from "./types";

package/dist/shio-client.js

@@ -1,113 +1,162 @@
-class o extends Error {
-  constructor(e, t, i) {
-    super(`Shio CDA ${e} for ${t}`), this.name = "ShioHttpError", this.status = e, this.url = t, this.body = i, Object.setPrototypeOf(this, o.prototype);
-  }
+// src/errors.ts
+var e = class e extends Error {
+	constructor(t, n, r) {
+		super(`Shio CDA ${t} for ${n}`), this.name = "ShioHttpError", this.status = t, this.url = n, this.body = r, Object.setPrototypeOf(this, e.prototype);
+	}
+}, t = "/api/v2/cda", n = class {
+	constructor(e) {
+		if (!e?.baseUrl) throw Error("ShioClient: `baseUrl` is required");
+		this.baseUrl = e.baseUrl.replace(/\/+$/, ""), this.headers = {
+			Accept: "application/json",
+			...e.headers ?? {}
+		}, e.apiToken && (this.headers.Key = e.apiToken);
+		let t = e.fetch ?? globalThis.fetch;
+		if (typeof t != "function") throw Error("ShioClient: no global `fetch` available — pass `fetch` in the config");
+		this.fetchFn = t.bind(globalThis), this.credentials = e.credentials;
+	}
+	getSites(e) {
+		return this.request("/site", e);
+	}
+	getSite(e, t) {
+		return this.requestOrNull(`/site/${i(e)}`, t);
+	}
+	getRedirects(e, t) {
+		return this.requestOrNull(`/site/${i(e)}/redirects`, t);
+	}
+	listChildren(e, t, n) {
+		let r = a({
+			page: t?.page,
+			size: t?.size,
+			locale: t?.locale,
+			state: t?.state
+		});
+		return this.requestOrNull(`/object/${i(e)}/list${r}`, n);
+	}
+	getPath(e, t) {
+		return this.requestOrNull(`/object/${i(e)}/path`, t);
+	}
+	getPost(e, t) {
+		let n = a({ state: t?.state });
+		return this.requestOrNull(`/post/${i(e)}${n}`, t);
+	}
+	getPostByUrl(e, t, n, r) {
+		let i = typeof n == "string" ? n : void 0, o = typeof n == "string" ? r : n, s = a({
+			siteId: e,
+			url: t,
+			locale: i,
+			state: o?.state
+		});
+		return this.requestOrNull(`/post/by-url${s}`, o);
+	}
+	getPostTypes(e) {
+		return this.request("/post-type", e);
+	}
+	getPostType(e, t) {
+		return this.requestOrNull(`/post-type/${i(e)}`, t);
+	}
+	query(e, t) {
+		let n = a({
+			siteId: e?.siteId,
+			folderId: e?.folderId,
+			postType: e?.postType,
+			page: e?.page,
+			size: e?.size,
+			locale: e?.locale,
+			state: e?.state
+		});
+		return this.request(`/query${n}`, t);
+	}
+	async send(e, n) {
+		return this.fetchFn(`${this.baseUrl}${t}${e}`, {
+			method: "GET",
+			headers: this.headers,
+			signal: n?.signal,
+			...this.credentials ? { credentials: this.credentials } : {}
+		});
+	}
+	async request(t, n) {
+		let r = await this.send(t, n);
+		if (!r.ok) throw new e(r.status, t, await o(r));
+		return await r.json();
+	}
+	async requestOrNull(t, n) {
+		let r = await this.send(t, n);
+		if (r.status === 404) return null;
+		if (!r.ok) throw new e(r.status, t, await o(r));
+		return await r.json();
+	}
+};
+function r(e) {
+	return new n(e);
 }
-const u = "/api/v2/cda";
-class c {
-  constructor(e) {
-    if (!(e != null && e.baseUrl))
-      throw new Error("ShioClient: `baseUrl` is required");
-    this.baseUrl = e.baseUrl.replace(/\/+$/, ""), this.headers = { Accept: "application/json", ...e.headers ?? {} }, e.apiToken && (this.headers.Key = e.apiToken);
-    const t = e.fetch ?? globalThis.fetch;
-    if (typeof t != "function")
-      throw new Error(
-        "ShioClient: no global `fetch` available — pass `fetch` in the config"
-      );
-    this.fetchFn = t.bind(globalThis), this.credentials = e.credentials;
-  }
-  // --- Sites ---
-  /** List all published sites. */
-  getSites(e) {
-    return this.request("/site", e);
-  }
-  /** Get one site (with its root folder id), or `null` if not found. */
-  getSite(e, t) {
-    return this.requestOrNull(`/site/${n(e)}`, t);
-  }
-  // --- Navigation ---
-  /** List a folder's children (subfolders + published posts), or `null` if the folder is unknown. */
-  listChildren(e, t, i) {
-    const r = h({ page: t == null ? void 0 : t.page, size: t == null ? void 0 : t.size });
-    return this.requestOrNull(
-      `/object/${n(e)}/list${r}`,
-      i
-    );
-  }
-  /** Get the breadcrumb path for a folder or post, or `null` if unknown. */
-  getPath(e, t) {
-    return this.requestOrNull(`/object/${n(e)}/path`, t);
-  }
-  // --- Posts ---
-  /** Get a published post by id (attributes expanded), or `null` if not found / not published. */
-  getPost(e, t) {
-    return this.requestOrNull(`/post/${n(e)}`, t);
-  }
-  /**
-   * Resolve a published post by site + friendly URL — the call behind catch-all
-   * routing (e.g. Next.js `[...slug]`). Returns `null` if unresolved.
-   */
-  getPostByUrl(e, t, i) {
-    const r = h({ siteId: e, url: t });
-    return this.requestOrNull(`/post/by-url${r}`, i);
-  }
-  /** Query published posts by site / folder / post type (always returns a listing). */
-  query(e, t) {
-    const i = h({
-      siteId: e == null ? void 0 : e.siteId,
-      folderId: e == null ? void 0 : e.folderId,
-      postType: e == null ? void 0 : e.postType,
-      page: e == null ? void 0 : e.page,
-      size: e == null ? void 0 : e.size
-    });
-    return this.request(`/query${i}`, t);
-  }
-  // --- internals ---
-  async send(e, t) {
-    return this.fetchFn(`${this.baseUrl}${u}${e}`, {
-      method: "GET",
-      headers: this.headers,
-      signal: t == null ? void 0 : t.signal,
-      ...this.credentials ? { credentials: this.credentials } : {}
-    });
-  }
-  async request(e, t) {
-    const i = await this.send(e, t);
-    if (!i.ok)
-      throw new o(i.status, e, await l(i));
-    return await i.json();
-  }
-  async requestOrNull(e, t) {
-    const i = await this.send(e, t);
-    if (i.status === 404)
-      return null;
-    if (!i.ok)
-      throw new o(i.status, e, await l(i));
-    return await i.json();
-  }
+function i(e) {
+	return encodeURIComponent(e);
 }
-function d(s) {
-  return new c(s);
+function a(e) {
+	let t = new URLSearchParams();
+	for (let [n, r] of Object.entries(e)) r != null && r !== "" && t.append(n, String(r));
+	let n = t.toString();
+	return n ? `?${n}` : "";
 }
-function n(s) {
-  return encodeURIComponent(s);
+async function o(e) {
+	try {
+		return await e.text();
+	} catch {
+		return;
+	}
 }
-function h(s) {
-  const e = new URLSearchParams();
-  for (const [i, r] of Object.entries(s))
-    r != null && r !== "" && e.append(i, String(r));
-  const t = e.toString();
-  return t ? `?${t}` : "";
+// src/codegen.ts
+var s = "@viglet/shio-client", c = "// AUTO-GENERATED by @viglet/shio-client (shio-types). DO NOT EDIT BY HAND.\n// Re-run `shio-types` after changing a post-type.";
+function l(e, t = {}) {
+	let n = t.importFrom ?? s, r = t.banner ?? c, i = [...e].sort((e, t) => e.name.localeCompare(t.name)), a = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Set();
+	for (let e of i) {
+		let t = m(e.name) || "PostType", n = t, r = 2;
+		for (; o.has(n);) n = `${t}${r++}`;
+		o.add(n), a.set(e.name, n);
+	}
+	let l = [];
+	for (let e of i) {
+		let t = a.get(e.name), n = f(e.title ?? e.description, 0);
+		l.push(`${n}export interface ${t}Attrs {\n${u(e.fields, 1)}}\n\n/** A \`${e.name}\` post with typed attributes. */\nexport type ${t}Post = ShioPost & {\n  postType: ${JSON.stringify(e.name)};\n  attrs: ${t}Attrs;\n};`);
+	}
+	let d = `/** Maps each post-type's API name to its typed post interface. */
+export interface ShioPostTypes {\n${i.map((e) => `  ${p(e.name)}: ${a.get(e.name)}Post;`).join("\n") || ""}\n}\n\n/** Union of all known post-type API names. */
+export type ShioPostTypeName = keyof ShioPostTypes;`;
+	return `${r}\n\nimport type { ShioPost } from ${JSON.stringify(n)};\n\n` + (l.length ? `${l.join("\n\n")}\n\n` : "") + `${d}\n`;
 }
-async function l(s) {
-  try {
-    return await s.text();
-  } catch {
-    return;
-  }
+function u(e, t) {
+	let n = "  ".repeat(t);
+	return [...e].sort((e, t) => e.ordinal - t.ordinal).map((e) => {
+		let r = f(e.label ?? e.description, t), i = e.required ? "" : "?";
+		return `${r}${n}${p(e.name)}${i}: ${d(e, t)};\n`;
+	}).join("");
 }
-export {
-  c as ShioClient,
-  o as ShioHttpError,
-  d as createShioClient
-};
+function d(e, t) {
+	return e.fields && e.fields.length > 0 ? `Array<{\n${u(e.fields, t + 1)}${"  ".repeat(t)}}>` : e.multiple ? "string[]" : "string";
+}
+function f(e, t) {
+	return !e || !e.trim() ? "" : `${"  ".repeat(t)}/** ${e.trim().replace(/\*\//g, "*\\/")} */\n`;
+}
+function p(e) {
+	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(e) ? e : JSON.stringify(e);
+}
+function m(e) {
+	let t = (e ?? "").split(/[^A-Za-z0-9]+/).filter(Boolean).map((e) => e.charAt(0).toUpperCase() + e.slice(1)).join("");
+	return /^[0-9]/.test(t) && (t = `T${t}`), t;
+}
+// src/types.ts
+var h = [
+	"heading",
+	"paragraph",
+	"quote",
+	"list",
+	"code",
+	"image",
+	"embed",
+	"reference"
+];
+function g(e, t) {
+	let n = e.attrs?.[t];
+	return Array.isArray(n) ? n : null;
+}
+export { h as SHIO_BLOCK_TYPES, n as ShioClient, e as ShioHttpError, r as createShioClient, l as generateShioTypes, g as shioBlocks };

package/dist/shio-client.umd.cjs

@@ -1 +1,6 @@
-(function(s,n){typeof exports=="object"&&typeof module<"u"?n(exports):typeof define=="function"&&define.amd?define(["exports"],n):(s=typeof globalThis<"u"?globalThis:s||self,n(s.ShioClient={}))})(this,(function(s){"use strict";class n extends Error{constructor(e,t,i){super(`Shio CDA ${e} for ${t}`),this.name="ShioHttpError",this.status=e,this.url=t,this.body=i,Object.setPrototypeOf(this,n.prototype)}}const d="/api/v2/cda";class u{constructor(e){if(!(e!=null&&e.baseUrl))throw new Error("ShioClient: `baseUrl` is required");this.baseUrl=e.baseUrl.replace(/\/+$/,""),this.headers={Accept:"application/json",...e.headers??{}},e.apiToken&&(this.headers.Key=e.apiToken);const t=e.fetch??globalThis.fetch;if(typeof t!="function")throw new Error("ShioClient: no global `fetch` available — pass `fetch` in the config");this.fetchFn=t.bind(globalThis),this.credentials=e.credentials}getSites(e){return this.request("/site",e)}getSite(e,t){return this.requestOrNull(`/site/${l(e)}`,t)}listChildren(e,t,i){const o=h({page:t==null?void 0:t.page,size:t==null?void 0:t.size});return this.requestOrNull(`/object/${l(e)}/list${o}`,i)}getPath(e,t){return this.requestOrNull(`/object/${l(e)}/path`,t)}getPost(e,t){return this.requestOrNull(`/post/${l(e)}`,t)}getPostByUrl(e,t,i){const o=h({siteId:e,url:t});return this.requestOrNull(`/post/by-url${o}`,i)}query(e,t){const i=h({siteId:e==null?void 0:e.siteId,folderId:e==null?void 0:e.folderId,postType:e==null?void 0:e.postType,page:e==null?void 0:e.page,size:e==null?void 0:e.size});return this.request(`/query${i}`,t)}async send(e,t){return this.fetchFn(`${this.baseUrl}${d}${e}`,{method:"GET",headers:this.headers,signal:t==null?void 0:t.signal,...this.credentials?{credentials:this.credentials}:{}})}async request(e,t){const i=await this.send(e,t);if(!i.ok)throw new n(i.status,e,await c(i));return await i.json()}async requestOrNull(e,t){const i=await this.send(e,t);if(i.status===404)return null;if(!i.ok)throw new n(i.status,e,await c(i));return await i.json()}}function f(r){return new u(r)}function l(r){return encodeURIComponent(r)}function h(r){const e=new URLSearchParams;for(const[i,o]of Object.entries(r))o!=null&&o!==""&&e.append(i,String(o));const t=e.toString();return t?`?${t}`:""}async function c(r){try{return await r.text()}catch{return}}s.ShioClient=u,s.ShioHttpError=n,s.createShioClient=f,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"})}));
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports):typeof define==`function`&&define.amd?define([`exports`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.ShioClient={}))})(this,function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var t=class e extends Error{constructor(t,n,r){super(`Shio CDA ${t} for ${n}`),this.name=`ShioHttpError`,this.status=t,this.url=n,this.body=r,Object.setPrototypeOf(this,e.prototype)}},n=`/api/v2/cda`,r=class{constructor(e){if(!e?.baseUrl)throw Error("ShioClient: `baseUrl` is required");this.baseUrl=e.baseUrl.replace(/\/+$/,``),this.headers={Accept:`application/json`,...e.headers??{}},e.apiToken&&(this.headers.Key=e.apiToken);let t=e.fetch??globalThis.fetch;if(typeof t!=`function`)throw Error("ShioClient: no global `fetch` available — pass `fetch` in the config");this.fetchFn=t.bind(globalThis),this.credentials=e.credentials}getSites(e){return this.request(`/site`,e)}getSite(e,t){return this.requestOrNull(`/site/${a(e)}`,t)}getRedirects(e,t){return this.requestOrNull(`/site/${a(e)}/redirects`,t)}listChildren(e,t,n){let r=o({page:t?.page,size:t?.size,locale:t?.locale,state:t?.state});return this.requestOrNull(`/object/${a(e)}/list${r}`,n)}getPath(e,t){return this.requestOrNull(`/object/${a(e)}/path`,t)}getPost(e,t){let n=o({state:t?.state});return this.requestOrNull(`/post/${a(e)}${n}`,t)}getPostByUrl(e,t,n,r){let i=typeof n==`string`?n:void 0,a=typeof n==`string`?r:n,s=o({siteId:e,url:t,locale:i,state:a?.state});return this.requestOrNull(`/post/by-url${s}`,a)}getPostTypes(e){return this.request(`/post-type`,e)}getPostType(e,t){return this.requestOrNull(`/post-type/${a(e)}`,t)}query(e,t){let n=o({siteId:e?.siteId,folderId:e?.folderId,postType:e?.postType,page:e?.page,size:e?.size,locale:e?.locale,state:e?.state});return this.request(`/query${n}`,t)}async send(e,t){return this.fetchFn(`${this.baseUrl}${n}${e}`,{method:`GET`,headers:this.headers,signal:t?.signal,...this.credentials?{credentials:this.credentials}:{}})}async request(e,n){let r=await this.send(e,n);if(!r.ok)throw new t(r.status,e,await s(r));return await r.json()}async requestOrNull(e,n){let r=await this.send(e,n);if(r.status===404)return null;if(!r.ok)throw new t(r.status,e,await s(r));return await r.json()}};function i(e){return new r(e)}function a(e){return encodeURIComponent(e)}function o(e){let t=new URLSearchParams;for(let[n,r]of Object.entries(e))r!=null&&r!==``&&t.append(n,String(r));let n=t.toString();return n?`?${n}`:``}async function s(e){try{return await e.text()}catch{return}}var c=`@viglet/shio-client`,l="// AUTO-GENERATED by @viglet/shio-client (shio-types). DO NOT EDIT BY HAND.\n// Re-run `shio-types` after changing a post-type.";function u(e,t={}){let n=t.importFrom??c,r=t.banner??l,i=[...e].sort((e,t)=>e.name.localeCompare(t.name)),a=new Map,o=new Set;for(let e of i){let t=h(e.name)||`PostType`,n=t,r=2;for(;o.has(n);)n=`${t}${r++}`;o.add(n),a.set(e.name,n)}let s=[];for(let e of i){let t=a.get(e.name),n=p(e.title??e.description,0);s.push(`${n}export interface ${t}Attrs {\n${d(e.fields,1)}}\n\n/** A \`${e.name}\` post with typed attributes. */\nexport type ${t}Post = ShioPost & {\n  postType: ${JSON.stringify(e.name)};\n  attrs: ${t}Attrs;\n};`)}let u=`/** Maps each post-type's API name to its typed post interface. */
+export interface ShioPostTypes {\n${i.map(e=>`  ${m(e.name)}: ${a.get(e.name)}Post;`).join(`
+`)||``}\n}\n\n/** Union of all known post-type API names. */
+export type ShioPostTypeName = keyof ShioPostTypes;`;return`${r}\n\nimport type { ShioPost } from ${JSON.stringify(n)};\n\n`+(s.length?`${s.join(`
+
+`)}\n\n`:``)+`${u}\n`}function d(e,t){let n=`  `.repeat(t);return[...e].sort((e,t)=>e.ordinal-t.ordinal).map(e=>{let r=p(e.label??e.description,t),i=e.required?``:`?`;return`${r}${n}${m(e.name)}${i}: ${f(e,t)};\n`}).join(``)}function f(e,t){return e.fields&&e.fields.length>0?`Array<{\n${d(e.fields,t+1)}${`  `.repeat(t)}}>`:e.multiple?`string[]`:`string`}function p(e,t){return!e||!e.trim()?``:`${`  `.repeat(t)}/** ${e.trim().replace(/\*\//g,`*\\/`)} */\n`}function m(e){return/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(e)?e:JSON.stringify(e)}function h(e){let t=(e??``).split(/[^A-Za-z0-9]+/).filter(Boolean).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(``);return/^[0-9]/.test(t)&&(t=`T${t}`),t}var g=[`heading`,`paragraph`,`quote`,`list`,`code`,`image`,`embed`,`reference`];function _(e,t){let n=e.attrs?.[t];return Array.isArray(n)?n:null}e.SHIO_BLOCK_TYPES=g,e.ShioClient=r,e.ShioHttpError=t,e.createShioClient=i,e.generateShioTypes=u,e.shioBlocks=_});

package/dist/types.d.ts

@@ -3,6 +3,14 @@
  * `/api/v2/cda/**`). Field names track the backend DTO records
  * (`com.viglet.shio.api.cda.dto`) one-for-one — they are a frozen public
  * contract; do not rename.
+ *
+ * **Optional, not nullable (SH127).** A field the CMS has no value for is *absent*
+ * from the JSON rather than present as `null`, so it is declared `field?: T` here.
+ * These two halves shipped together and had to: the backend omits the null because
+ * `"url": null` costs bytes and tokens to say nothing, and this file declares it
+ * optional because a consumer written against `string | null` would otherwise start
+ * receiving `undefined` from a comparison it believed was exhaustive. Narrow with a
+ * falsy check (`if (post.title)`) rather than `=== null`.
  */
 /** Configuration for {@link ShioClient}. */
 export interface ShioClientConfig {
@@ -31,13 +39,68 @@ export interface ShioRequestOptions {
     /** Abort signal for cancellation (e.g. React effect cleanup). */
     signal?: AbortSignal;
 }
+/**
+ * The version of content a CDA read asks for (SH1081, over SH990's parameter).
+ *
+ * `"published"` is the default and any token may read it. `"draft"` and `"rev:<n>"` need a
+ * preview token, and without one the read throws {@link ShioHttpError} with status 403 and the
+ * problem slug `state-needs-preview-token`. A string rather than a union, so the server stays the
+ * one place that says which values exist.
+ */
+export type ShioContentState = string;
+/** Per-request options for a single-post read: {@link ShioRequestOptions} plus a state. */
+export interface ShioReadOptions extends ShioRequestOptions {
+    /** See {@link ShioContentState}; omitted, the published version. */
+    state?: ShioContentState;
+}
 /** A published site. */
 export interface ShioSite {
     id: string;
     name: string;
-    description: string | null;
-    url: string | null;
-    rootFolderId: string | null;
+    description?: string;
+    url?: string;
+    rootFolderId?: string;
+    /**
+     * The languages this site is in (SH1123) — what a language switcher is built from.
+     * Present on {@link ShioClient.getSite} and {@link ShioClient.getSites}; absent on the
+     * `site` a {@link ShioPath} carries.
+     */
+    locales?: ShioSiteLocales;
+}
+/**
+ * A site's locale policy (SH1123). Pair it with {@link ShioPost.availableLocales}: the
+ * site says which languages it offers, the post says which of them this page exists in.
+ */
+export interface ShioSiteLocales {
+    /** The locale the site is written in — always one of {@link enabled}. */
+    defaultLocale: string;
+    /** Every locale the site offers, in the order a switcher lists them. */
+    enabled: string[];
+    /**
+     * Locale to show instead when a page is missing in the one asked for, e.g.
+     * `{ "pt-br": "pt" }`. A locale with no entry falls back to {@link defaultLocale}.
+     */
+    fallback: Record<string, string>;
+    /**
+     * `true` when somebody chose this policy. `false` when it was read off the published
+     * content, in which case {@link enabled} lists what has been translated so far rather
+     * than what the site promises.
+     */
+    declared: boolean;
+}
+/**
+ * One row of a site's redirect table (SH1133), from {@link ShioClient.getRedirects}.
+ *
+ * A front end that serves the site's URLs itself consults this before answering 404: the
+ * instance's own renderer honours these, and a headless site never reaches it.
+ */
+export interface ShioRedirect {
+    /** The site-relative path that moved, e.g. `/pricing`. */
+    from: string;
+    /** Where it moved: a site-relative path, or an absolute URL as written. */
+    to: string;
+    /** `true` for a 301, `false` for a 302 — the default, because a wrong 301 is cached for ever. */
+    permanent: boolean;
 }
 /** A folder (listing item / breadcrumb node). */
 export interface ShioFolder {
@@ -48,32 +111,113 @@ export interface ShioFolder {
 /** A post listing item — no heavy attribute payload. */
 export interface ShioPostSummary {
     id: string;
-    title: string | null;
-    summary: string | null;
-    furl: string | null;
-    postType: string | null;
-    date: string | null;
-    modifiedDate: string | null;
+    title?: string;
+    summary?: string;
+    furl?: string;
+    postType?: string;
+    /** BCP-47 locale of this row (SH52), absent on single-language content. */
+    locale?: string;
+    date?: string;
+    modifiedDate?: string;
 }
 /** A full post with its post-type attributes expanded into {@link attrs}. */
 export interface ShioPost {
     id: string;
-    title: string | null;
-    summary: string | null;
-    furl: string | null;
-    postType: string | null;
-    siteId: string | null;
-    folderId: string | null;
+    title?: string;
+    summary?: string;
+    furl?: string;
+    postType?: string;
+    siteId?: string;
+    folderId?: string;
     published: boolean;
-    date: string | null;
-    modifiedDate: string | null;
-    publicationDate: string | null;
+    date?: string;
+    modifiedDate?: string;
+    publicationDate?: string;
+    /** BCP-47 locale of this post (SH52), absent on single-language content. */
+    locale?: string;
+    /**
+     * Every locale this post is translated into, including {@link locale} — the
+     * list a language switcher renders from (SH52). Always present; `[]` on a
+     * post with no translation group.
+     */
+    availableLocales: string[];
     /** Post-type attributes as a JSON object, keyed by attribute name. */
     attrs: Record<string, unknown>;
+    /**
+     * SH1016 — field name to rendered HTML, for this post's `Blocks` fields.
+     *
+     * Beside {@link attrs}, never instead of it: a site that maps block types to its own
+     * components reads the array out of `attrs`, and one that has been dropping a body into a
+     * div reads this. Absent for a post with no block field, which is every post written
+     * before the widget existed.
+     */
+    rendered?: Record<string, string>;
+}
+/**
+ * SH1016 — one block of a `Blocks` field, discriminated by {@link ShioBlock.type}.
+ *
+ * TypeScript narrows on `type`, so `switch (block.type)` gives each case its own fields with
+ * no cast — which is the whole reason the body is an array of these rather than a string.
+ * A `key` is the block's identity across a reorder, not its position.
+ *
+ * Marks are ranges over the block's own `text`, not nested spans: `<b><i>x</i></b>` and
+ * `<i><b>x</b></i>` are one content with two spellings, and a range has one.
+ */
+export interface ShioBlockMark {
+    from: number;
+    to: number;
+    type: "strong" | "em" | "code" | "link" | "strike";
+    /** Present on a `link` mark. */
+    href?: string;
+}
+interface ShioBlockBase {
+    key: string;
 }
+export type ShioBlock = (ShioBlockBase & {
+    type: "heading";
+    level: number;
+    text?: string;
+    marks?: ShioBlockMark[];
+}) | (ShioBlockBase & {
+    type: "paragraph";
+    text?: string;
+    marks?: ShioBlockMark[];
+}) | (ShioBlockBase & {
+    type: "quote";
+    text?: string;
+    marks?: ShioBlockMark[];
+}) | (ShioBlockBase & {
+    type: "list";
+    ordered?: boolean;
+    items?: string[];
+}) | (ShioBlockBase & {
+    type: "code";
+    language?: string;
+    text?: string;
+}) | (ShioBlockBase & {
+    type: "image";
+    src?: string;
+    alt?: string;
+}) | (ShioBlockBase & {
+    type: "embed";
+    url?: string;
+}) | (ShioBlockBase & {
+    type: "reference";
+    address?: string;
+});
+/** The registered block types, as the server refuses anything outside them. */
+export declare const SHIO_BLOCK_TYPES: readonly ["heading", "paragraph", "quote", "list", "code", "image", "embed", "reference"];
+/**
+ * Reads a post's block field as blocks, or `null` when it is not one.
+ *
+ * A helper rather than a cast, because the honest answer for a field that holds a string is
+ * "this is not a blocks field" — and a consumer that casts finds that out by rendering
+ * nothing.
+ */
+export declare function shioBlocks(post: ShioPost, field: string): ShioBlock[] | null;
 /** Folder children: subfolders plus a paged slice of published posts. */
 export interface ShioListing {
-    folderId: string | null;
+    folderId?: string;
     folders: ShioFolder[];
     posts: ShioPostSummary[];
     page: number;
@@ -82,10 +226,46 @@ export interface ShioListing {
 }
 /** Breadcrumb path for a folder or post. */
 export interface ShioPath {
-    site: ShioSite | null;
+    site?: ShioSite;
     /** Ordered root → ... → current. */
     breadcrumb: ShioFolder[];
-    currentFolder: ShioFolder | null;
+    currentFolder?: ShioFolder;
+}
+/**
+ * One field of a post-type's content model (SH11). Recursive: a Relator field
+ * carries its item sub-fields in {@link fields}. Mirrors the backend
+ * `ShCdaSchemaField` record one-for-one.
+ */
+export interface ShioFieldSchema {
+    name: string;
+    label?: string;
+    description?: string;
+    /** The Shio widget name (e.g. `"Text"`, `"Relator"`), or `null`. */
+    widget?: string;
+    required: boolean;
+    /**
+     * The delivered value is an array — a `Check Box` / `Multi Select` value, or a
+     * Relator's item list (in which case {@link fields} is non-empty).
+     */
+    multiple: boolean;
+    isTitle: boolean;
+    isSummary: boolean;
+    ordinal: number;
+    /** Sub-fields, for a Relator; empty for scalar fields. */
+    fields: ShioFieldSchema[];
+}
+/**
+ * A post-type's content model (SH11): its API {@link name} plus the ordered
+ * fields a post of this type exposes under {@link ShioPost.attrs}. Mirrors the
+ * backend `ShCdaPostTypeSchema` record. Feed an array of these to
+ * {@link generateShioTypes} to emit `.d.ts` declarations.
+ */
+export interface ShioPostTypeSchema {
+    name: string;
+    title?: string;
+    namePlural?: string;
+    description?: string;
+    fields: ShioFieldSchema[];
 }
 /** Parameters for {@link ShioClient.query}. */
 export interface ShioQueryParams {
@@ -94,9 +274,18 @@ export interface ShioQueryParams {
     postType?: string;
     page?: number;
     size?: number;
+    /** Only posts written in this locale (SH1057), e.g. `"pt-br"`; omitted, every locale. */
+    locale?: string;
+    /** SH1081 — which version of each post; see {@link ShioContentState}. */
+    state?: ShioContentState;
 }
 /** Paging parameters for listings. */
 export interface ShioPageParams {
     page?: number;
     size?: number;
+    /** Only posts written in this locale (SH1057); a folder's subfolders are listed whatever it is. */
+    locale?: string;
+    /** SH1081 — which version of each post; see {@link ShioContentState}. */
+    state?: ShioContentState;
 }
+export {};

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@viglet/shio-client",
-  "version": "2026.2.1",
-  "description": "Framework-agnostic TypeScript client for the Shio CMS Content Delivery API (CDA). Zero runtime dependencies — works in Node, the browser, edge runtimes, Next.js server components, Astro, Vue, Svelte and plain scripts.",
+  "version": "2026.3.3",
+  "description": "Framework-agnostic TypeScript client for the Viglet Shio Content Delivery API (CDA). Zero runtime dependencies — works in Node, the browser, edge runtimes, Next.js server components, Astro, Vue, Svelte and plain scripts.",
+  "homepage": "https://openviglet.github.io/shio/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openviglet/shio.git",
+    "directory": "shio-client"
+  },
+  "bugs": {
+    "url": "https://github.com/openviglet/shio/issues"
+  },
   "type": "module",
   "main": "dist/shio-client.umd.cjs",
   "module": "dist/shio-client.js",
@@ -11,31 +20,51 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/shio-client.js",
       "require": "./dist/shio-client.umd.cjs"
-    }
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "shio-types": "bin/shio-types.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "sideEffects": false,
   "devDependencies": {
     "typescript": "^5.8.3",
-    "vite": "^6.3.1"
+    "vite": "^8.3.5"
   },
   "keywords": [
     "shio",
+    "viglet",
     "cms",
-    "headless",
+    "headless-cms",
+    "content-management-system",
+    "agent",
+    "ai",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
     "cda",
     "content-delivery",
     "typescript",
-    "sdk"
+    "sdk",
+    "api-client",
+    "nextjs",
+    "astro",
+    "edge",
+    "headless"
   ],
-  "author": "Viglet Team",
-  "license": "GPL-3.0",
+  "author": {
+    "name": "Viglet Team",
+    "url": "https://www.viglet.org"
+  },
+  "license": "Apache-2.0",
   "scripts": {
     "dev": "vite build --watch",
     "build": "vite build && tsc --emitDeclarationOnly",
     "typecheck": "tsc --noEmit",
-    "test": "node --test \"test/*.test.mjs\""
+    "test": "node --import ../scripts/test-watchdog.mjs --test \"test/*.test.mjs\""
   }
 }