@cancia/astro 0.5.1 → 0.7.0

package/dist/{chunk-MCHQV6Y7.js → chunk-UMCBQXB6.js}

@@ -1,4 +1,5 @@
 import {
+  isSafeHref,
   portableTextSubsetSchema
 } from "./chunk-BOIQNZAO.js";
 
@@ -56,6 +57,30 @@ var defineField = {
    *   related: f.array(f.reference({ list: "posts" }), { label: "Related" }),
    */
   reference: (o) => z.string().meta({ widget: "reference", ...o }),
+  /**
+   * A link: label + href as ONE unit.
+   *
+   * A button/CTA is two values that must stay together — saving a new label
+   * against a stale href produces a broken call-to-action, so they are stored
+   * as a single object rather than two flat keys that could drift.
+   *
+   *   cta: f.link({ label: "Primary CTA" }),
+   *
+   * `href` is NOT z.url(): a relative href ("/start", "#programmes") and a
+   * mailto:/tel: are all legitimate and z.url() rejects the relative forms.
+   * It IS constrained by `isSafeHref` — the SAME guard richtext link marks
+   * use — so a stored value can never carry a javascript:/data: XSS payload.
+   * Without this, the link widget would be a hole around a protection
+   * richtext already enforces.
+   *
+   * Whether to open in a new tab is derived from the href at render time
+   * (see `isExternalHref`) instead of being stored — one less thing that can
+   * fall out of sync with the URL it describes.
+   */
+  link: (o) => z.object({
+    label: z.string(),
+    href: z.string().refine(isSafeHref, "unsafe or unsupported URL scheme")
+  }).meta({ widget: "link", ...o }),
   /**
    * A constrained rich-text body. Stored as a Portable-Text SUBSET array (D4):
    * block styles normal/h2/h3/blockquote, bullet/number lists, strong/em marks,
@@ -145,11 +170,43 @@ function describeList(name, schema) {
     fields
   };
 }
+function parseLinkValue(raw) {
+  const safe = (href) => isSafeHref(href) ? href : "";
+  if (raw && typeof raw === "object") {
+    const o = raw;
+    return { label: String(o.label ?? ""), href: safe(String(o.href ?? "")) };
+  }
+  if (typeof raw !== "string" || raw === "") return { label: "", href: "" };
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed && typeof parsed === "object") {
+        return {
+          label: String(parsed.label ?? ""),
+          href: safe(String(parsed.href ?? ""))
+        };
+      }
+    } catch {
+    }
+  }
+  return { label: raw, href: "" };
+}
+function serializeLinkValue(value) {
+  return JSON.stringify({ label: value.label ?? "", href: value.href ?? "" });
+}
+function isExternalHref(href) {
+  if (!href) return false;
+  return /^https?:\/\//i.test(href);
+}
 
 export {
   z,
   defineList,
   defineField,
   slugify,
-  describeList
+  describeList,
+  parseLinkValue,
+  serializeLinkValue,
+  isExternalHref
 };

package/dist/{chunk-IIGDU5SV.js → chunk-VFMOVGMC.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-NG5GJME5.js";
 import {
   describeList
-} from "./chunk-MCHQV6Y7.js";
+} from "./chunk-UMCBQXB6.js";
 
 // src/routes/schemas.ts
 function json(body, status = 200) {

package/dist/content.d.ts

@@ -0,0 +1,74 @@
+/** Flat content map as returned by /api/cancia/content and kv.getAll: "key.lang" → value. */
+type ContentMap = Record<string, string>;
+/** A translator: `(key, fallback) => cms[`${key}.${lang}`] ?? fallback`. */
+type Translate = (key: string, fallback: string) => string;
+/** The value behind a `link` field: a label and where it points. */
+interface LinkValue {
+    label: string;
+    href: string;
+}
+/** Resolve a link field, falling back to the values authored in the page. */
+type TranslateLink = (key: string, fallback: LinkValue) => LinkValue;
+interface ContentReaderOptions {
+    /** Site id (the `?site=` query param and the storage `site` column). */
+    site: string;
+    /**
+     * Build-time content API base. Default: `process.env.CANCIA_CONTENT_URL`.
+     * When set (non-empty), `getCMS()` FETCHES from
+     * `${url}/api/cancia/content?site=<site>` instead of reading the DB directly.
+     * This is how a static build on a runtime-only volume gets live content.
+     */
+    url?: string;
+    /**
+     * Bearer token for the fetch. Default: `process.env.CANCIA_TOKEN`. Required by
+     * a non-public site (036 fail-closed) — without it the fetch 401s and the
+     * reader falls back to the direct DB read.
+     */
+    token?: string;
+    /**
+     * Direct-DB fallback path. Default:
+     * `process.env.CANCIA_DB_PATH ?? "<cwd>/cancia.db"`.
+     * Ignored when a `readDb` override is supplied.
+     */
+    dbPath?: string;
+    /** Default language for `makeT`/`get`. Default: `"en"`. */
+    lang?: string;
+    /** Injectable fetch (tests). Default: global `fetch`. */
+    fetch?: typeof fetch;
+    /**
+     * Optional DB-read override. Lets a non-sqlite project (e.g. json-file
+     * storage) supply its own fallback WITHOUT this reader importing every
+     * adapter. Default: read via `createSqliteAdapterV2({ dbPath })` (the
+     * recommended backend).
+     */
+    readDb?: () => Promise<ContentMap>;
+}
+interface ContentReader {
+    /**
+     * Read all content for the site as a flat `"key.lang" → value` map.
+     * Chain: fetch (when `url` set) → direct DB read → `{}`. NEVER throws.
+     */
+    getCMS(): Promise<ContentMap>;
+    /** Build a translator over a content map for the reader's `lang`. */
+    makeT(cms: ContentMap): Translate;
+    /**
+     * Build a link resolver over a content map. A link field stores
+     * `{label, href}` as JSON; this parses it and falls back to the values
+     * authored in the page. Never throws; drops an unsafe href.
+     */
+    makeTLink(cms: ContentMap): TranslateLink;
+    /** Sugar: `const { t, tLink, cms } = await reader.get()` in frontmatter. */
+    get(): Promise<{
+        t: Translate;
+        tLink: TranslateLink;
+        cms: ContentMap;
+    }>;
+}
+/**
+ * Create a content reader. Reads are transport-agnostic (network OR local file)
+ * and never throw — a static build reads content the same way whether it's a
+ * local DB, the site's own API, or a future hosted Cancia DB.
+ */
+declare function createContentReader(opts: ContentReaderOptions): ContentReader;
+
+export { type ContentMap, type ContentReader, type ContentReaderOptions, type LinkValue, type Translate, type TranslateLink, createContentReader };

package/dist/content.js

@@ -0,0 +1,84 @@
+import "./chunk-FOSOWSXV.js";
+import "./chunk-CJDIVWO3.js";
+import {
+  createSqliteAdapterV2
+} from "./chunk-GNWD7EL2.js";
+import "./chunk-U7V53JX7.js";
+import "./chunk-L2VKQJPY.js";
+import "./chunk-7IA5B5CF.js";
+
+// src/content.ts
+function isSafeHref(href) {
+  const trimmed = href.trim();
+  if (trimmed === "") return false;
+  if (/^(https?:|mailto:|tel:)/i.test(trimmed)) return true;
+  const schemeMatch = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
+  if (schemeMatch) {
+    const firstSep = trimmed.search(/[/?#]/);
+    if (firstSep === -1 || schemeMatch[1].length < firstSep) return false;
+  }
+  return true;
+}
+function parseLink(raw, fallback) {
+  if (!raw) return fallback;
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("{")) {
+    try {
+      const p = JSON.parse(trimmed);
+      if (p && typeof p === "object") {
+        const href = String(p.href ?? "");
+        return {
+          label: String(p.label ?? "") || fallback.label,
+          href: href && isSafeHref(href) ? href : fallback.href
+        };
+      }
+    } catch {
+    }
+  }
+  return { label: raw, href: fallback.href };
+}
+function createContentReader(opts) {
+  const site = opts.site;
+  const lang = opts.lang ?? "en";
+  const url = opts.url ?? process.env.CANCIA_CONTENT_URL;
+  const token = opts.token ?? process.env.CANCIA_TOKEN;
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  function readDb() {
+    if (opts.readDb) return opts.readDb();
+    const dbPath = opts.dbPath ?? process.env.CANCIA_DB_PATH ?? `${process.cwd()}/cancia.db`;
+    return createSqliteAdapterV2({ dbPath }).kv.getAll(site);
+  }
+  async function fetchFromApi(base) {
+    const endpoint = `${base.replace(/\/+$/, "")}/api/cancia/content?site=${encodeURIComponent(site)}`;
+    const res = await fetchImpl(endpoint, {
+      headers: token ? { Authorization: `Bearer ${token}` } : {}
+    });
+    if (!res.ok) throw new Error(`Content fetch failed: ${res.status}`);
+    return await res.json();
+  }
+  async function getCMS() {
+    try {
+      return url ? await fetchFromApi(url) : await readDb();
+    } catch {
+      try {
+        return await readDb();
+      } catch {
+        return {};
+      }
+    }
+  }
+  function makeT(cms) {
+    return (key, fallback) => cms[`${key}.${lang}`] ?? fallback;
+  }
+  function makeTLink(cms) {
+    return (key, fallback) => parseLink(cms[`${key}.${lang}`], fallback);
+  }
+  async function get() {
+    const cms = await getCMS();
+    return { t: makeT(cms), tLink: makeTLink(cms), cms };
+  }
+  return { getCMS, makeT, makeTLink, get };
+}
+export {
+  createContentReader
+};

package/dist/endpoints/lists.js

@@ -1,13 +1,13 @@
-import {
-  makeListsRoutes
-} from "../chunk-22DJVJBR.js";
-import "../chunk-NG5GJME5.js";
-import "../chunk-7IA5B5CF.js";
 import {
   extractRoute,
   invalidateOnSave
 } from "../chunk-VGRG5DN7.js";
+import {
+  makeListsRoutes
+} from "../chunk-22DJVJBR.js";
+import "../chunk-NG5GJME5.js";
 import "../chunk-X6ZFFGIA.js";
+import "../chunk-7IA5B5CF.js";
 
 // src/endpoints/lists.ts
 import { getCanciaRuntime } from "virtual:cancia/runtime";

package/dist/endpoints/schemas.js

@@ -1,8 +1,8 @@
 import {
   makeSchemasRoute
-} from "../chunk-IIGDU5SV.js";
+} from "../chunk-VFMOVGMC.js";
 import "../chunk-NG5GJME5.js";
-import "../chunk-MCHQV6Y7.js";
+import "../chunk-UMCBQXB6.js";
 import "../chunk-BOIQNZAO.js";
 
 // src/endpoints/schemas.ts

package/dist/index.js

@@ -6,7 +6,7 @@ import {
 } from "./chunk-22DJVJBR.js";
 import {
   makeSchemasRoute
-} from "./chunk-IIGDU5SV.js";
+} from "./chunk-VFMOVGMC.js";
 import "./chunk-NG5GJME5.js";
 import {
   makeLocalUploadHandler,
@@ -20,7 +20,7 @@ import {
   defineList,
   describeList,
   z
-} from "./chunk-MCHQV6Y7.js";
+} from "./chunk-UMCBQXB6.js";
 import {
   canciaLoader
 } from "./chunk-UR5WC3RA.js";

package/dist/schema/index.d.ts

@@ -16,7 +16,7 @@ export { P as PT_DECORATORS, a as PT_LIST_ITEMS, b as PT_STYLES, c as PortableTe
  *   z.boolean()          → "checkbox"
  *   z.enum([...])        → "select"
  */
-type FieldWidget = "text" | "textarea" | "url" | "email" | "datetime" | "number" | "checkbox" | "select" | "image" | "slug" | "array" | "object" | "reference" | "richtext";
+type FieldWidget = "text" | "textarea" | "url" | "email" | "datetime" | "number" | "checkbox" | "select" | "image" | "slug" | "array" | "object" | "reference" | "richtext" | "link";
 /**
  * Fields common to every widget's metadata. All optional.
  */
@@ -61,6 +61,8 @@ type FieldMeta = (FieldMetaBase & {
     list: string;
 }) | (FieldMetaBase & {
     widget: "richtext";
+}) | (FieldMetaBase & {
+    widget: "link";
 });
 interface ListSchemaOptions<TFields extends Record<string, z.ZodTypeAny>> {
     /** Display label for the list (e.g. "Blog Posts"). */
@@ -194,6 +196,30 @@ declare const defineField: {
     reference: (o: FieldMetaBase & {
         list: string;
     }) => z.ZodString;
+    /**
+     * A link: label + href as ONE unit.
+     *
+     * A button/CTA is two values that must stay together — saving a new label
+     * against a stale href produces a broken call-to-action, so they are stored
+     * as a single object rather than two flat keys that could drift.
+     *
+     *   cta: f.link({ label: "Primary CTA" }),
+     *
+     * `href` is NOT z.url(): a relative href ("/start", "#programmes") and a
+     * mailto:/tel: are all legitimate and z.url() rejects the relative forms.
+     * It IS constrained by `isSafeHref` — the SAME guard richtext link marks
+     * use — so a stored value can never carry a javascript:/data: XSS payload.
+     * Without this, the link widget would be a hole around a protection
+     * richtext already enforces.
+     *
+     * Whether to open in a new tab is derived from the href at render time
+     * (see `isExternalHref`) instead of being stored — one less thing that can
+     * fall out of sync with the URL it describes.
+     */
+    link: (o?: FieldMetaBase) => z.ZodObject<{
+        label: z.ZodString;
+        href: z.ZodString;
+    }, z.core.$strip>;
     /**
      * A constrained rich-text body. Stored as a Portable-Text SUBSET array (D4):
      * block styles normal/h2/h3/blockquote, bullet/number lists, strong/em marks,
@@ -257,7 +283,38 @@ interface ListDescription {
  */
 declare function slugify(input: string): string;
 declare function describeList(name: string, schema: ListSchema): ListDescription;
+/** The value behind a `link` widget: a label and where it points. */
+interface LinkValue {
+    label: string;
+    href: string;
+}
+/**
+ * Parse a stored link value. NEVER throws.
+ *
+ * The KV surface stores every value as a string, so a link round-trips as
+ * JSON. Three cases must all degrade gracefully rather than break a render:
+ *
+ *   - proper JSON object  → used as-is (missing halves coerced to "")
+ *   - a bare string       → treated as the LABEL with an empty href. This is
+ *                           the migration path for a field that used to be
+ *                           `text`, and for a fallback authored in markup.
+ *   - empty / malformed   → `{ label: "", href: "" }`
+ *
+ * A content read must never throw (same rule as createContentReader).
+ */
+declare function parseLinkValue(raw: unknown): LinkValue;
+/** Serialize a link value for storage. The inverse of `parseLinkValue`. */
+declare function serializeLinkValue(value: LinkValue): string;
+/**
+ * Should this href open in a new tab? Derived, never stored.
+ *
+ * External = has a scheme+host that isn't the current origin. Relative hrefs
+ * ("/start", "#programmes") and mailto:/tel: are NOT external — mailto/tel
+ * hand off to another app, and forcing target=_blank on them leaves a blank
+ * tab behind.
+ */
+declare function isExternalHref(href: string): boolean;
 /** Map of list name → schema. What users export from src/cms/schemas.ts. */
 type SchemasModule = Record<string, ListSchema>;
 
-export { type FieldDescription, type FieldMeta, type FieldMetaBase, type FieldWidget, type ListDescription, type ListSchema, type ListSchemaOptions, type SchemasModule, defineField, defineList, describeList, slugify };
+export { type FieldDescription, type FieldMeta, type FieldMetaBase, type FieldWidget, type LinkValue, type ListDescription, type ListSchema, type ListSchemaOptions, type SchemasModule, defineField, defineList, describeList, isExternalHref, parseLinkValue, serializeLinkValue, slugify };

package/dist/schema/index.js

@@ -2,9 +2,12 @@ import {
   defineField,
   defineList,
   describeList,
+  isExternalHref,
+  parseLinkValue,
+  serializeLinkValue,
   slugify,
   z
-} from "../chunk-MCHQV6Y7.js";
+} from "../chunk-UMCBQXB6.js";
 import {
   PT_DECORATORS,
   PT_LIST_ITEMS,
@@ -20,9 +23,12 @@ export {
   defineField,
   defineList,
   describeList,
+  isExternalHref,
   isSafeHref,
+  parseLinkValue,
   portableTextSubsetSchema,
   ptBlockSchema,
+  serializeLinkValue,
   slugify,
   z
 };

package/dist/storage/index.js

@@ -1,3 +1,4 @@
+import "../chunk-FOSOWSXV.js";
 import {
   createSQLiteAdapter
 } from "../chunk-CJDIVWO3.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cancia/astro",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Astro integration for Cancia CMS — inline editing with zero separate server",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,10 @@
       "types": "./dist/cache.d.ts",
       "import": "./dist/cache.js"
     },
+    "./content": {
+      "types": "./dist/content.d.ts",
+      "import": "./dist/content.js"
+    },
     "./richtext": {
       "types": "./dist/richtext/index.d.ts",
       "import": "./dist/richtext/index.js"