@sandboxsonny/ace-kit 0.0.0-stage → 0.1.0

package/dist/chunk-KLRCWAE4.js

@@ -0,0 +1,147 @@
+import { addressFromPath, isHomeAddress, visitablePath } from './chunk-M5WR5TCR.js';
+import { previewTokenFrom, previewHeaders } from './chunk-YLO6IAXF.js';
+
+// src/client/errors.ts
+var AcePreviewExpiredError = class extends Error {
+  constructor() {
+    super("The preview link has expired.");
+    this.name = "AcePreviewExpiredError";
+  }
+};
+var AceUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AceUnavailableError";
+  }
+};
+
+// src/client/create-client.ts
+var requestTimeoutMilliseconds = 5e3;
+var maximumCachedAnswers = 500;
+function createAceClient({
+  apiUrl,
+  siteDomain,
+  cacheSeconds = 5,
+  fetchImplementation = (input, init) => fetch(input, init),
+  now = Date.now
+}) {
+  const cache = /* @__PURE__ */ new Map();
+  function forgetSomeAnswers() {
+    for (const [path, answer] of cache) if (answer.expiresAt <= now()) cache.delete(path);
+    for (const path of cache.keys()) {
+      if (cache.size < maximumCachedAnswers) break;
+      cache.delete(path);
+    }
+  }
+  async function get(path, options = { cached: true }) {
+    const cached = options.cached ? cache.get(path) : void 0;
+    if (cached && cached.expiresAt > now()) return cached.value;
+    let response;
+    try {
+      response = await fetchImplementation(`${apiUrl.replace(/\/+$/, "")}${path}`, {
+        headers: { Accept: "application/json", "X-Forwarded-Host": siteDomain },
+        signal: AbortSignal.timeout(requestTimeoutMilliseconds)
+      });
+    } catch {
+      throw new AceUnavailableError("Could not reach the CMS.");
+    }
+    let value = null;
+    if (response.status === 404) {
+      const reply = await response.json().catch(() => ({}));
+      if (reply.error === "no site for this domain") {
+        throw new AceUnavailableError(`The CMS has no site with the domain "${siteDomain}".`);
+      }
+    } else if (response.status === 403 && !options.cached) {
+      throw new AcePreviewExpiredError();
+    } else if (response.ok) {
+      value = await response.json().catch(() => {
+        throw new AceUnavailableError("The CMS sent a reply that could not be read.");
+      });
+    } else {
+      throw new AceUnavailableError(`The CMS answered with an error (${response.status}).`);
+    }
+    if (options.cached && cacheSeconds > 0) {
+      if (cache.size >= maximumCachedAnswers) forgetSomeAnswers();
+      cache.set(path, { expiresAt: now() + cacheSeconds * 1e3, value });
+    }
+    return value;
+  }
+  return {
+    /**
+     * One live entry of a content type, by its handle; null if the site has no such entry. With a preview token the
+     * entry the token was made for comes back with its draft applied (never cached); a token that has run out throws
+     * AcePreviewExpiredError.
+     */
+    async getEntry(contentTypeHandle, handle, options = {}) {
+      const path = `/public/entries/${encodeURIComponent(handle)}`;
+      const entry = options.previewToken ? await get(`${path}?preview=${encodeURIComponent(options.previewToken)}`, {
+        cached: false
+      }) : await get(path);
+      return entry && entry.content_type_handle === contentTypeHandle ? entry : null;
+    },
+    /** The live entries of a content type, newest first. */
+    async getEntries(contentTypeHandle, options = {}) {
+      const query = new URLSearchParams({ content_type: contentTypeHandle });
+      if (options.limit) query.set("limit", String(options.limit));
+      return await get(`/public/entries?${query}`) ?? [];
+    },
+    /** One of the site's navigation menus by its handle, with every link worked out; null if the site has none. */
+    getMenu(handle) {
+      return get(`/public/menus/${encodeURIComponent(handle)}`);
+    },
+    /** What the site's content types and fields are, which is what type generation reads. */
+    async getContentTypes() {
+      return await get("/public/content-types") ?? [];
+    }
+  };
+}
+
+// src/helpers/menus.ts
+function linksFromMenu(menu) {
+  const convert = (items) => items.map((item) => {
+    const children = convert(item.children);
+    const to = visitablePath(item.url);
+    return children.length > 0 ? { label: item.label, to, children } : { label: item.label, to };
+  });
+  return convert(menu.items);
+}
+function isCurrentPage(link, pathname) {
+  const normalised = pathname.length > 1 ? pathname.replace(/\/$/, "") : pathname;
+  return link.to === normalised;
+}
+async function loadMenuLinks(client, handle, fallback = []) {
+  try {
+    const menu = await client.getMenu(handle);
+    return menu ? linksFromMenu(menu) : fallback;
+  } catch (error) {
+    if (!(error instanceof AceUnavailableError)) throw error;
+    console.error(error.message);
+    return fallback;
+  }
+}
+
+// src/helpers/page.ts
+async function loadPage(client, { slug, url }) {
+  const address = addressFromPath(slug);
+  const previewToken = previewTokenFrom(url);
+  const headers = previewToken ? { ...previewHeaders } : {};
+  if (slug && address && isHomeAddress(address)) {
+    return { kind: "redirect", status: url.search ? 302 : 301, location: `/${url.search}`, headers };
+  }
+  if (!address) return { kind: "not-found", status: 404, headers };
+  try {
+    const entry = await client.getEntry(address.contentTypeHandle, address.entryHandle, {
+      previewToken
+    });
+    return entry ? { kind: "entry", status: 200, entry, headers } : { kind: "not-found", status: 404, headers };
+  } catch (error) {
+    if (error instanceof AcePreviewExpiredError) return { kind: "preview-expired", status: 403, headers };
+    if (error instanceof AceUnavailableError) {
+      console.error(error.message);
+      return { kind: "unavailable", status: 503, headers };
+    }
+    throw error;
+  }
+}
+
+export { AcePreviewExpiredError, AceUnavailableError, createAceClient, isCurrentPage, linksFromMenu, loadMenuLinks, loadPage };

package/dist/chunk-M5WR5TCR.js

@@ -0,0 +1,16 @@
+// src/helpers/addressing.ts
+var homeAddress = { contentTypeHandle: "pages", entryHandle: "home" };
+var pathOfAddress = (address) => `/${address.contentTypeHandle}/${address.entryHandle}`;
+var handlePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function addressFromPath(slug) {
+  const segments = (slug ?? "").split("/").filter((segment) => segment !== "");
+  if (segments.length === 0) return homeAddress;
+  if (segments.length !== 2 || !segments.every((segment) => handlePattern.test(segment))) return null;
+  return { contentTypeHandle: segments[0], entryHandle: segments[1] };
+}
+var isHomeAddress = (address) => address.contentTypeHandle === homeAddress.contentTypeHandle && address.entryHandle === homeAddress.entryHandle;
+function visitablePath(path) {
+  return path === pathOfAddress(homeAddress) ? "/" : path;
+}
+
+export { addressFromPath, homeAddress, isHomeAddress, pathOfAddress, visitablePath };

package/dist/chunk-URLKW2YS.js

@@ -0,0 +1,107 @@
+import { visitablePath } from './chunk-M5WR5TCR.js';
+
+// src/helpers/images.ts
+function dimension(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.round(value) : void 0;
+}
+function imageAttributes(image, { sizes, lazy = true }) {
+  return {
+    src: image.src,
+    srcSet: image.srcset || void 0,
+    sizes: image.srcset ? sizes : void 0,
+    width: dimension(image.width),
+    height: dimension(image.height),
+    alt: image.alt_text,
+    loading: lazy ? "lazy" : "eager",
+    decoding: "async",
+    fetchPriority: lazy ? void 0 : "high"
+  };
+}
+
+// src/helpers/links.ts
+function linkAddress(address) {
+  const allowed = /^(\/(?!\/)|https?:\/\/[^\s/]|mailto:\S|tel:\S)/.test(address) && !/\s/.test(address);
+  return allowed ? visitablePath(address) : null;
+}
+function isInternalPath(address) {
+  return address.startsWith("/") && !address.startsWith("//");
+}
+
+// src/helpers/text-area.ts
+var escapes = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+var escapeHtml = (text) => text.replace(/[&<>"']/g, (character) => escapes[character]);
+function textAreaParagraphs(text) {
+  return (text ?? "").split(/\r?\n\s*\r?\n/).map((paragraph) => paragraph.trim()).filter((paragraph) => paragraph !== "");
+}
+var textAreaLines = (paragraph) => paragraph.split(/\r?\n/).map((line) => line.trim());
+var textAreaSingleLine = (text) => (text ?? "").split(/\s*\r?\n\s*/).filter((part) => part !== "").join(" ").trim();
+function renderTextArea(text, { multiline = true } = {}) {
+  if (!multiline) return escapeHtml(textAreaSingleLine(text));
+  return textAreaParagraphs(text).map((paragraph) => `<p>${textAreaLines(paragraph).map(escapeHtml).join("<br>")}</p>`).join("");
+}
+
+// src/helpers/rich-text.ts
+var escapes2 = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+var escapeHtml2 = (text) => text.replace(/[&<>"']/g, (character) => escapes2[character]);
+var richTextImageSizes = "(min-width: 42rem) 42rem, 100vw";
+var headingLevel = (node) => node.attrs?.level === 3 || node.attrs?.level === 4 ? node.attrs.level : 2;
+var listStart = (node) => node.attrs?.start && node.attrs.start > 1 ? Math.trunc(node.attrs.start) : void 0;
+function renderImage(node) {
+  if (!node.attrs?.image) return "";
+  const attributes = imageAttributes(node.attrs.image, { sizes: richTextImageSizes });
+  const parts = [
+    `src="${escapeHtml2(attributes.src)}"`,
+    attributes.srcSet ? `srcset="${escapeHtml2(attributes.srcSet)}" sizes="${escapeHtml2(attributes.sizes ?? "")}"` : "",
+    attributes.width ? `width="${attributes.width}"` : "",
+    attributes.height ? `height="${attributes.height}"` : "",
+    `alt="${escapeHtml2(attributes.alt)}"`,
+    'loading="lazy" decoding="async"'
+  ];
+  return `<figure><img ${parts.filter(Boolean).join(" ")}></figure>`;
+}
+function renderText(node) {
+  const marks = node.marks ?? [];
+  return marks.reduce(
+    (html, mark) => {
+      if (mark.type === "bold") return `<strong>${html}</strong>`;
+      if (mark.type === "italic") return `<em>${html}</em>`;
+      const address = linkAddress(mark.attrs.href);
+      return address ? `<a href="${escapeHtml2(address)}">${html}</a>` : html;
+    },
+    escapeHtml2(node.text ?? "")
+  );
+}
+function renderNode(node) {
+  const inside = () => (node.content ?? []).map(renderNode).join("");
+  switch (node.type) {
+    case "text":
+      return renderText(node);
+    case "hardBreak":
+      return "<br>";
+    case "paragraph":
+      return `<p>${inside()}</p>`;
+    case "heading": {
+      const level = headingLevel(node);
+      return `<h${level}>${inside()}</h${level}>`;
+    }
+    case "bulletList":
+      return `<ul>${inside()}</ul>`;
+    case "orderedList": {
+      const start = listStart(node);
+      return `<ol${start ? ` start="${start}"` : ""}>${inside()}</ol>`;
+    }
+    case "listItem":
+      return `<li>${inside()}</li>`;
+    case "blockquote":
+      return `<blockquote>${inside()}</blockquote>`;
+    case "image":
+      return renderImage(node);
+    default:
+      return "";
+  }
+}
+function renderRichText(document) {
+  return (document.content ?? []).map(renderNode).join("");
+}
+
+export { headingLevel, imageAttributes, isInternalPath, linkAddress, listStart, renderRichText, renderTextArea, richTextImageSizes, textAreaLines, textAreaParagraphs, textAreaSingleLine };

package/dist/chunk-XPZY5R5A.js

@@ -0,0 +1,16 @@
+// src/helpers/notices.ts
+var pageNotices = {
+  redirect: { heading: "Redirecting", message: "This page has moved." },
+  "preview-expired": {
+    heading: "Preview expired",
+    message: "This preview link has run out. Reload the editor in the CMS to get a new one."
+  },
+  unavailable: {
+    heading: "Temporarily unavailable",
+    message: "This page can't be shown right now. Please try again shortly."
+  },
+  "not-found": { heading: "Page not found", message: "There's nothing at this address." },
+  entry: { heading: "", message: "" }
+};
+
+export { pageNotices };

package/dist/chunk-YLO6IAXF.js

@@ -0,0 +1,45 @@
+// src/helpers/preview.ts
+var previewParameter = "cms_preview";
+var refreshMessageType = "cms-ace:refresh";
+function originOf(address) {
+  try {
+    const parsed = new URL(address);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.origin : null;
+  } catch {
+    return null;
+  }
+}
+function isRefreshRequest(event, adminOrigin) {
+  const expected = originOf(adminOrigin);
+  if (expected === null || event.origin !== expected) return false;
+  return typeof event.data === "object" && event.data !== null && event.data.type === refreshMessageType;
+}
+function previewTokenFrom(address) {
+  return address.searchParams.get(previewParameter) || null;
+}
+function framingPolicy(adminOrigin) {
+  const origin = originOf(adminOrigin);
+  if (origin === null) {
+    throw new Error(
+      `The CMS admin address must be a web address like https://admin.example.com (got "${adminOrigin}"). Check ACE_PREVIEW_ADMIN_ORIGIN.`
+    );
+  }
+  return `frame-ancestors 'self' ${origin}`;
+}
+function addFramingPolicy(headers, adminOrigin) {
+  const policy = framingPolicy(adminOrigin);
+  const existing = headers.get("Content-Security-Policy");
+  if (!existing) {
+    headers.set("Content-Security-Policy", policy);
+    return;
+  }
+  const others = existing.split(";").map((directive) => directive.trim()).filter((directive) => directive !== "" && !/^frame-ancestors(\s|$)/i.test(directive));
+  headers.set("Content-Security-Policy", [...others, policy].join("; "));
+}
+var previewHeaders = { "Cache-Control": "no-store", "X-Robots-Tag": "noindex" };
+function swapPageContent(current, fresh) {
+  current.title = fresh.title;
+  current.body.replaceChildren(...Array.from(fresh.body.childNodes).map((node) => current.importNode(node, true)));
+}
+
+export { addFramingPolicy, framingPolicy, isRefreshRequest, originOf, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, swapPageContent };

package/dist/chunk-YN7LJWGI.js

@@ -0,0 +1,36 @@
+import { swapPageContent, isRefreshRequest } from './chunk-YLO6IAXF.js';
+
+// src/helpers/preview-listener.ts
+async function refreshPageContent() {
+  const response = await fetch(location.href, { cache: "no-store" });
+  if (response.ok) swapPageContent(document, new DOMParser().parseFromString(await response.text(), "text/html"));
+}
+function listenForPreviewRefresh(adminOrigin, refresh = refreshPageContent) {
+  let refreshing = false;
+  let again = false;
+  async function run() {
+    if (refreshing) {
+      again = true;
+      return;
+    }
+    refreshing = true;
+    try {
+      await refresh();
+    } catch (error) {
+      console.error("The preview could not be refreshed.", error);
+    } finally {
+      refreshing = false;
+      if (again) {
+        again = false;
+        void run();
+      }
+    }
+  }
+  const onMessage = (event) => {
+    if (isRefreshRequest(event, adminOrigin)) void run();
+  };
+  window.addEventListener("message", onMessage);
+  return () => window.removeEventListener("message", onMessage);
+}
+
+export { listenForPreviewRefresh, refreshPageContent };

package/dist/cli.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+
+// src/generate/cli.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+import { parseArgs } from "util";
+
+// src/client/errors.ts
+var AcePreviewExpiredError = class extends Error {
+  constructor() {
+    super("The preview link has expired.");
+    this.name = "AcePreviewExpiredError";
+  }
+};
+var AceUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AceUnavailableError";
+  }
+};
+
+// src/client/create-client.ts
+var requestTimeoutMilliseconds = 5e3;
+var maximumCachedAnswers = 500;
+function createAceClient({
+  apiUrl,
+  siteDomain,
+  cacheSeconds = 5,
+  fetchImplementation = (input, init) => fetch(input, init),
+  now = Date.now
+}) {
+  const cache = /* @__PURE__ */ new Map();
+  function forgetSomeAnswers() {
+    for (const [path, answer] of cache) if (answer.expiresAt <= now()) cache.delete(path);
+    for (const path of cache.keys()) {
+      if (cache.size < maximumCachedAnswers) break;
+      cache.delete(path);
+    }
+  }
+  async function get(path, options = { cached: true }) {
+    const cached = options.cached ? cache.get(path) : void 0;
+    if (cached && cached.expiresAt > now()) return cached.value;
+    let response;
+    try {
+      response = await fetchImplementation(`${apiUrl.replace(/\/+$/, "")}${path}`, {
+        headers: { Accept: "application/json", "X-Forwarded-Host": siteDomain },
+        signal: AbortSignal.timeout(requestTimeoutMilliseconds)
+      });
+    } catch {
+      throw new AceUnavailableError("Could not reach the CMS.");
+    }
+    let value = null;
+    if (response.status === 404) {
+      const reply = await response.json().catch(() => ({}));
+      if (reply.error === "no site for this domain") {
+        throw new AceUnavailableError(`The CMS has no site with the domain "${siteDomain}".`);
+      }
+    } else if (response.status === 403 && !options.cached) {
+      throw new AcePreviewExpiredError();
+    } else if (response.ok) {
+      value = await response.json().catch(() => {
+        throw new AceUnavailableError("The CMS sent a reply that could not be read.");
+      });
+    } else {
+      throw new AceUnavailableError(`The CMS answered with an error (${response.status}).`);
+    }
+    if (options.cached && cacheSeconds > 0) {
+      if (cache.size >= maximumCachedAnswers) forgetSomeAnswers();
+      cache.set(path, { expiresAt: now() + cacheSeconds * 1e3, value });
+    }
+    return value;
+  }
+  return {
+    /**
+     * One live entry of a content type, by its handle; null if the site has no such entry. With a preview token the
+     * entry the token was made for comes back with its draft applied (never cached); a token that has run out throws
+     * AcePreviewExpiredError.
+     */
+    async getEntry(contentTypeHandle, handle, options = {}) {
+      const path = `/public/entries/${encodeURIComponent(handle)}`;
+      const entry = options.previewToken ? await get(`${path}?preview=${encodeURIComponent(options.previewToken)}`, {
+        cached: false
+      }) : await get(path);
+      return entry && entry.content_type_handle === contentTypeHandle ? entry : null;
+    },
+    /** The live entries of a content type, newest first. */
+    async getEntries(contentTypeHandle, options = {}) {
+      const query = new URLSearchParams({ content_type: contentTypeHandle });
+      if (options.limit) query.set("limit", String(options.limit));
+      return await get(`/public/entries?${query}`) ?? [];
+    },
+    /** One of the site's navigation menus by its handle, with every link worked out; null if the site has none. */
+    getMenu(handle) {
+      return get(`/public/menus/${encodeURIComponent(handle)}`);
+    },
+    /** What the site's content types and fields are, which is what type generation reads. */
+    async getContentTypes() {
+      return await get("/public/content-types") ?? [];
+    }
+  };
+}
+
+// src/helpers/generate-types.ts
+var quote = (text) => JSON.stringify(text);
+function typeOfField(field) {
+  switch (field.component_key) {
+    case "text":
+    case "textarea":
+      return { type: "string" };
+    case "number":
+      return { type: "number" };
+    case "checkbox":
+      return { type: "boolean" };
+    case "select": {
+      const options = field.config?.options ?? [];
+      return { type: options.length > 0 ? options.map(quote).join(" | ") : "string" };
+    }
+    case "image":
+      return { type: "AceImageData", uses: "AceImageData" };
+    case "richtext":
+      return { type: "AceRichTextDocument", uses: "AceRichTextDocument" };
+    default:
+      return { type: "unknown" };
+  }
+}
+function generateTypes(contentTypes, packageName2, source) {
+  const used = /* @__PURE__ */ new Set();
+  const blocks = contentTypes.map((contentType) => {
+    const lines = contentType.fields.map((field) => {
+      const { type, uses } = typeOfField(field);
+      if (uses) used.add(uses);
+      const optional = field.config?.required === true ? "" : "?";
+      return `      /** ${field.label.replace(/\*\//g, "* /")} */
+      ${quote(field.handle)}${optional}: ${type};`;
+    });
+    const body = lines.length > 0 ? `{
+${lines.join("\n")}
+    }` : "Record<string, never>";
+    return `    /** ${contentType.name.replace(/\*\//g, "* /")} */
+    ${quote(contentType.handle)}: ${body};`;
+  });
+  const imports = used.size > 0 ? `import type { ${[...used].sort().join(", ")} } from ${quote(packageName2)};
+
+` : "";
+  return `// Generated by ace-kit from ${source}. Do not edit: run \`ace-kit generate\` to update it.
+${imports}declare module ${quote(packageName2)} {
+  interface AceContentTypes {
+${blocks.join("\n")}
+  }
+}
+
+export {};
+`;
+}
+
+// src/helpers/package-name.ts
+var packageName = "@sandboxsonny/ace-kit";
+
+// src/generate/cli.ts
+var usage = `ace-kit generate: write TypeScript types for your CMS Ace content types.
+
+Usage:
+  ace-kit generate [--api-url <address>] [--domain <domain>] [--out <file>]
+
+Options:
+  --api-url   Where the CMS Ace API lives (or set ACE_API_URL, in the environment or a .env file).
+  --domain    The domain your site has in the CMS (or set ACE_SITE_DOMAIN).
+  --out       Where to write the types (default: src/ace-kit.generated.d.ts).
+  --help      Show this message.
+`;
+async function main() {
+  try {
+    process.loadEnvFile(".env");
+  } catch {
+  }
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: {
+      "api-url": { type: "string" },
+      domain: { type: "string" },
+      out: { type: "string" },
+      help: { type: "boolean" }
+    }
+  });
+  if (values.help || positionals[0] !== "generate") {
+    console.log(usage);
+    return values.help ? 0 : 1;
+  }
+  const apiUrl = values["api-url"] ?? process.env.ACE_API_URL;
+  const siteDomain = values.domain ?? process.env.ACE_SITE_DOMAIN;
+  if (!apiUrl || !siteDomain) {
+    console.error(
+      "Give the API address and the site's domain: --api-url and --domain, or ACE_API_URL and ACE_SITE_DOMAIN."
+    );
+    return 1;
+  }
+  const client = createAceClient({ apiUrl, siteDomain, cacheSeconds: 0 });
+  const contentTypes = await client.getContentTypes();
+  const file = resolve(values.out ?? "src/ace-kit.generated.d.ts");
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, generateTypes(contentTypes, packageName, siteDomain));
+  console.log(`Wrote types for ${contentTypes.length} content type${contentTypes.length === 1 ? "" : "s"} to ${file}.`);
+  return 0;
+}
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+);