@headroom-cms/api 0.1.1

package/blocks/InlineContent.astro

@@ -0,0 +1,47 @@
+---
+import type { InlineContent as InlineContentType, RefsMap, PublicContentRef } from "../src/types";
+
+interface Props {
+  content: InlineContentType[] | undefined | null;
+  refs?: RefsMap;
+  resolveContentLink?: (ref: PublicContentRef) => string;
+}
+
+const { content, refs, resolveContentLink } = Astro.props;
+
+function resolveHref(href: string): string {
+  if (!href.startsWith("headroom://content/")) return href;
+  const match = href.match(/^headroom:\/\/content\/([^/]+)\/([A-Z0-9]+)$/);
+  if (!match) return "#";
+  const [, , contentId] = match;
+  const ref = refs?.[contentId];
+  if (!ref) return "#";
+  if (resolveContentLink) return resolveContentLink(ref);
+  if (!ref.published) return "#";
+  return `/${ref.collection}/${ref.slug}`;
+}
+---
+
+{content?.map((item) => {
+  if (item.type === "link") {
+    const resolvedHref = resolveHref(item.href);
+    return (
+      <a href={resolvedHref} class="text-primary underline hover:text-primary/80">
+        <Astro.self content={item.content} refs={refs} resolveContentLink={resolveContentLink} />
+      </a>
+    );
+  }
+
+  const s = item.styles;
+  const classes = [
+    s?.bold && "font-bold",
+    s?.italic && "italic",
+    s?.underline && "underline",
+    s?.strikethrough && "line-through",
+    s?.code && "font-mono bg-surface-alt px-1 py-0.5 rounded text-sm",
+  ].filter(Boolean).join(" ");
+
+  return classes
+    ? <span class={classes}>{item.text}</span>
+    : <Fragment>{item.text}</Fragment>;
+})}

package/blocks/NumberedList.astro

@@ -0,0 +1,19 @@
+---
+import type { Block, RefsMap, PublicContentRef } from "../src/types";
+import InlineContent from "./InlineContent.astro";
+
+interface Props {
+  items: Block[];
+  refs?: RefsMap;
+  resolveContentLink?: (ref: PublicContentRef) => string;
+}
+
+const { items, refs, resolveContentLink } = Astro.props;
+---
+
+<ol>
+  {items.map((item) => {
+    const content = Array.isArray(item.content) ? item.content : [];
+    return <li><InlineContent content={content} refs={refs} resolveContentLink={resolveContentLink} /></li>;
+  })}
+</ol>

package/blocks/Paragraph.astro

@@ -0,0 +1,15 @@
+---
+import type { Block, RefsMap, PublicContentRef } from "../src/types";
+import InlineContent from "./InlineContent.astro";
+
+interface Props {
+  block: Block;
+  refs?: RefsMap;
+  resolveContentLink?: (ref: PublicContentRef) => string;
+}
+
+const { block, refs, resolveContentLink } = Astro.props;
+const content = Array.isArray(block.content) ? block.content : [];
+---
+
+<p><InlineContent content={content} refs={refs} resolveContentLink={resolveContentLink} /></p>

package/blocks/Table.astro

@@ -0,0 +1,29 @@
+---
+import type { Block, TableContent, InlineContent as InlineContentType, RefsMap, PublicContentRef } from "../src/types";
+import InlineContent from "./InlineContent.astro";
+
+interface Props {
+  block: Block;
+  refs?: RefsMap;
+  resolveContentLink?: (ref: PublicContentRef) => string;
+}
+
+const { block, refs, resolveContentLink } = Astro.props;
+const tableContent = block.content as TableContent | undefined;
+const rows = tableContent?.rows || [];
+---
+
+{rows.length > 0 && (
+  <table>
+    <tbody>
+      {rows.map((row, rowIndex) => (
+        <tr>
+          {row.cells.map((cell) => {
+            const Tag = rowIndex === 0 ? "th" : "td";
+            return <Tag><InlineContent content={cell as InlineContentType[]} refs={refs} resolveContentLink={resolveContentLink} /></Tag>;
+          })}
+        </tr>
+      ))}
+    </tbody>
+  </table>
+)}

package/dist/astro.d.ts

@@ -0,0 +1,49 @@
+import { Loader } from 'astro/loaders';
+import { ZodTypeAny } from 'astro/zod';
+import { AstroIntegration } from 'astro';
+
+interface HeadroomConfig {
+    /** Base URL of the Headroom API (e.g. "https://api.example.com") */
+    apiUrl: string;
+    /** Site host identifier (e.g. "mysite.com") */
+    site: string;
+    /** Public API key for X-Headroom-Key header */
+    apiKey: string;
+    /** CDN base URL for media (e.g. "https://d123.cloudfront.net"). Required for mediaUrl(). */
+    cdnUrl?: string;
+    /** HMAC secret for signing image transform URLs. Required for transformUrl(). */
+    imageSigningSecret?: string;
+}
+
+interface HeadroomLoaderOptions {
+    /** Collection name to load */
+    collection: string;
+    /**
+     * Whether to fetch full content bodies (default: false).
+     * When false, only metadata is stored (faster, less data).
+     * When true, bodies are batch-fetched and stored alongside metadata.
+     */
+    bodies?: boolean;
+    /** Client config. If omitted, reads from env vars. */
+    config?: HeadroomConfig;
+    /** Zod schema for content data. Enables type-safe access via `entry.data`. */
+    schema?: ZodTypeAny;
+}
+declare function headroomLoader(opts: HeadroomLoaderOptions): Loader;
+
+interface HeadroomRefreshOptions {
+    /** Poll interval in milliseconds (default: 5000) */
+    interval?: number;
+    /** Client config. If omitted, reads from env vars. */
+    config?: HeadroomConfig;
+}
+declare function headroomDevRefresh(opts?: HeadroomRefreshOptions): AstroIntegration;
+
+declare function getEnv(key: string): string | undefined;
+/**
+ * Build config from env vars. In Astro integration hooks, process.env may
+ * not contain .env file values, so we also read .env directly from cwd.
+ */
+declare function configFromEnv(): HeadroomConfig;
+
+export { type HeadroomLoaderOptions, type HeadroomRefreshOptions, configFromEnv, getEnv, headroomDevRefresh, headroomLoader };

package/dist/astro.js

@@ -0,0 +1,325 @@
+// src/client.ts
+import { createHmac } from "crypto";
+var HeadroomError = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message);
+    this.name = "HeadroomError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var HeadroomClient = class {
+  config;
+  constructor(config) {
+    this.config = {
+      ...config,
+      apiUrl: config.apiUrl.replace(/\/+$/, ""),
+      cdnUrl: config.cdnUrl?.replace(/\/+$/, "")
+    };
+  }
+  /** Build the full URL for a public API path */
+  url(path) {
+    return `${this.config.apiUrl}/v1/${this.config.site}${path}`;
+  }
+  /**
+   * Construct a full CDN URL from a stored media path.
+   * Media paths are stored as `/media/{site}/{mediaId}/original{ext}` in
+   * content responses (block props, coverUrl, field values).
+   *
+   *   client.mediaUrl("/media/myblog.com/01ABC/original.jpg")
+   *   → "https://d123.cloudfront.net/media/myblog.com/01ABC/original.jpg"
+   *
+   * Returns the path as-is if no cdnUrl is configured (useful for dev).
+   */
+  mediaUrl(path) {
+    if (!path) return "";
+    return this.config.cdnUrl ? `${this.config.cdnUrl}${path}` : path;
+  }
+  /**
+   * Build a signed image transform URL from a stored media path.
+   * Converts the `/media/...` path to `/img/...`, appends transform
+   * parameters, and signs with HMAC-SHA256 (matching the Go imagesign).
+   *
+   * Falls back to `mediaUrl()` when no signing secret is configured
+   * or when no transform options are provided.
+   *
+   *   client.transformUrl("/media/myblog.com/01ABC/original.jpg", { width: 800, format: "webp" })
+   *   → "https://cdn.example.com/img/myblog.com/01ABC/original.jpg?format=webp&w=800&sig=abc123..."
+   */
+  transformUrl(path, opts) {
+    if (!path) return "";
+    if (!this.config.imageSigningSecret || !opts || Object.keys(opts).length === 0) {
+      return this.mediaUrl(path);
+    }
+    const imgPath = path.replace(/^\/media\//, "/img/");
+    const params = new URLSearchParams();
+    if (opts.width) params.set("w", String(opts.width));
+    if (opts.height) params.set("h", String(opts.height));
+    if (opts.fit) params.set("fit", opts.fit);
+    if (opts.format) params.set("format", opts.format);
+    if (opts.quality) params.set("q", String(opts.quality));
+    params.sort();
+    const encoded = params.toString();
+    const canonical = encoded ? `${imgPath}?${encoded}` : imgPath;
+    const mac = createHmac("sha256", this.config.imageSigningSecret).update(canonical).digest("hex").slice(0, 32);
+    params.set("sig", mac);
+    const cdnBase = this.config.cdnUrl || "";
+    return `${cdnBase}${imgPath}?${params.toString()}`;
+  }
+  async fetch(path, params) {
+    const base = this.url(path);
+    const url = params?.toString() ? `${base}?${params}` : base;
+    const res = await fetch(url, {
+      headers: { "X-Headroom-Key": this.config.apiKey }
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const body = await res.json();
+        code = body.code || code;
+        message = body.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, message);
+    }
+    return res.json();
+  }
+  async fetchPost(path, body) {
+    const res = await fetch(this.url(path), {
+      method: "POST",
+      headers: {
+        "X-Headroom-Key": this.config.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const errBody = await res.json();
+        code = errBody.code || code;
+        message = errBody.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, message);
+    }
+    return res.json();
+  }
+  // --- Content ---
+  async listContent(collection, opts) {
+    const params = new URLSearchParams({ collection });
+    if (opts?.limit) params.set("limit", String(opts.limit));
+    if (opts?.cursor) params.set("cursor", opts.cursor);
+    if (opts?.before) params.set("before", String(opts.before));
+    if (opts?.after) params.set("after", String(opts.after));
+    if (opts?.sort) params.set("sort", opts.sort);
+    if (opts?.relatedTo) params.set("relatedTo", opts.relatedTo);
+    if (opts?.relField) params.set("relField", opts.relField);
+    return this.fetch("/content", params);
+  }
+  async getContent(contentId) {
+    return this.fetch(`/content/${contentId}`);
+  }
+  /**
+   * Fetch a single content item by slug. Uses a dedicated server-side
+   * endpoint for efficient lookup (no client-side pagination).
+   * Returns undefined if no published content matches the slug.
+   */
+  async getContentBySlug(collection, slug) {
+    try {
+      return await this.fetch(
+        `/content/by-slug/${encodeURIComponent(collection)}/${encodeURIComponent(slug)}`
+      );
+    } catch (e) {
+      if (e instanceof HeadroomError && e.status === 404) {
+        return void 0;
+      }
+      throw e;
+    }
+  }
+  async getSingleton(collection) {
+    return this.fetch(`/content/singleton/${collection}`);
+  }
+  /**
+   * Fetch multiple content items with bodies in a single request.
+   * Max 50 IDs per call. Items not found or unpublished are listed in `missing`.
+   */
+  async getBatchContent(ids) {
+    return this.fetchPost("/content/batch", { ids });
+  }
+  // --- Collections ---
+  async listCollections() {
+    return this.fetch("/collections");
+  }
+  async getCollection(name) {
+    return this.fetch(`/collections/${name}`);
+  }
+  // --- Block Types ---
+  async listBlockTypes() {
+    return this.fetch("/block-types");
+  }
+  // --- Version ---
+  async getVersion() {
+    const result = await this.fetch("/version");
+    return result.contentVersion;
+  }
+};
+
+// src/astro/env.ts
+import { readFileSync } from "fs";
+import { resolve } from "path";
+function getEnv(key) {
+  if (typeof process !== "undefined" && process.env?.[key]) {
+    return process.env[key];
+  }
+  try {
+    const env = import.meta.env;
+    if (env?.[key]) return env[key];
+  } catch {
+  }
+  return void 0;
+}
+function parseDotenv(filePath) {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const env = {};
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eqIdx = trimmed.indexOf("=");
+      if (eqIdx === -1) continue;
+      const key = trimmed.slice(0, eqIdx).trim();
+      let value = trimmed.slice(eqIdx + 1).trim();
+      if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+        value = value.slice(1, -1);
+      }
+      env[key] = value;
+    }
+    return env;
+  } catch {
+    return {};
+  }
+}
+function configFromEnv() {
+  const dotenv = parseDotenv(resolve(process.cwd(), ".env"));
+  const get = (key) => getEnv(key) || dotenv[key];
+  return {
+    apiUrl: get("HEADROOM_API_URL") || "http://localhost:3000",
+    site: get("HEADROOM_SITE") || "",
+    apiKey: get("HEADROOM_API_KEY") || "",
+    cdnUrl: get("HEADROOM_CDN_URL") || void 0,
+    imageSigningSecret: get("HEADROOM_IMAGE_SIGNING_SECRET") || void 0
+  };
+}
+
+// src/astro/loader.ts
+function headroomLoader(opts) {
+  return {
+    name: "headroom",
+    schema: opts.schema,
+    load: async ({ store, meta, generateDigest, parseData }) => {
+      const config = opts.config || configFromEnv();
+      const client = new HeadroomClient(config);
+      try {
+        const version = await client.getVersion();
+        const lastVersion = meta.get("contentVersion");
+        if (lastVersion && String(version) === lastVersion) {
+          return;
+        }
+        meta.set("contentVersion", String(version));
+      } catch {
+      }
+      const allMetadata = [];
+      let cursor;
+      do {
+        const result = await client.listContent(opts.collection, {
+          limit: 1e3,
+          cursor
+        });
+        allMetadata.push(...result.items);
+        cursor = result.hasMore ? result.cursor : void 0;
+      } while (cursor);
+      const seen = /* @__PURE__ */ new Set();
+      const storeId = (item) => item.slug || opts.collection;
+      if (opts.bodies) {
+        for (let i = 0; i < allMetadata.length; i += 50) {
+          const chunk = allMetadata.slice(i, i + 50);
+          const result = await client.getBatchContent(
+            chunk.map((m) => m.contentId)
+          );
+          for (const item of result.items) {
+            const id = storeId(item);
+            seen.add(id);
+            const raw = item;
+            const data = parseData ? await parseData({ id, data: raw }) : raw;
+            store.set({
+              id,
+              data,
+              digest: generateDigest(raw)
+            });
+          }
+        }
+      } else {
+        for (const item of allMetadata) {
+          const id = storeId(item);
+          seen.add(id);
+          const raw = item;
+          const data = parseData ? await parseData({ id, data: raw }) : raw;
+          store.set({
+            id,
+            data,
+            digest: generateDigest(raw)
+          });
+        }
+      }
+      for (const key of store.keys()) {
+        if (!seen.has(key)) {
+          store.delete(key);
+        }
+      }
+    }
+  };
+}
+
+// src/astro/refresh.ts
+function headroomDevRefresh(opts) {
+  const interval = opts?.interval || 5e3;
+  return {
+    name: "headroom-dev-refresh",
+    hooks: {
+      "astro:server:setup": ({ logger, refreshContent }) => {
+        const config = opts?.config || configFromEnv();
+        const client = new HeadroomClient(config);
+        logger.info(
+          `Polling ${config.apiUrl}/v1/${config.site}/version every ${interval / 1e3}s`
+        );
+        let lastVersion = null;
+        setInterval(async () => {
+          try {
+            const version = await client.getVersion();
+            if (lastVersion !== null && version !== lastVersion) {
+              logger.info(
+                `Content version changed (${lastVersion} \u2192 ${version}), refreshing\u2026`
+              );
+              await refreshContent({ loaders: ["headroom"] });
+            }
+            lastVersion = version;
+          } catch (e) {
+            const cause = e instanceof Error && e.cause ? ` (${e.cause})` : "";
+            logger.warn(`Version poll error: ${e}${cause}`);
+          }
+        }, interval);
+      }
+    }
+  };
+}
+export {
+  configFromEnv,
+  getEnv,
+  headroomDevRefresh,
+  headroomLoader
+};

package/dist/codegen.cjs

@@ -0,0 +1,172 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/codegen.ts
+var codegen_exports = {};
+__export(codegen_exports, {
+  fieldToZod: () => fieldToZod,
+  generateZodSchemas: () => generateZodSchemas
+});
+module.exports = __toCommonJS(codegen_exports);
+
+// src/codegen/zod.ts
+function fieldToZod(field) {
+  switch (field.type) {
+    case "text":
+    case "textarea":
+    case "rich-text":
+    case "slug":
+    case "url":
+    case "email":
+    case "select":
+      return "z.string().optional()";
+    case "number":
+      return "z.number().optional()";
+    case "boolean":
+      return "z.boolean().optional()";
+    case "date":
+    case "datetime":
+      return "z.number().optional()";
+    case "media":
+      return "z.string().optional()";
+    case "blocks":
+      return "z.array(blockSchema).optional()";
+    case "multiselect":
+      return "z.array(z.string()).optional()";
+    case "content": {
+      const multiple = field.options?.multiple === true;
+      return multiple ? "z.array(z.string()).optional()" : "z.string().optional()";
+    }
+    case "array": {
+      const itemFields = field.options?.itemFields;
+      if (itemFields && itemFields.length > 0) {
+        const props = itemFields.map((f) => `${f.name}: ${fieldToZod(f)}`).join(", ");
+        return `z.array(z.object({ ${props} })).optional()`;
+      }
+      return "z.array(z.record(z.unknown())).optional()";
+    }
+    default:
+      return "z.unknown().optional()";
+  }
+}
+var PREAMBLE = `// Auto-generated by @headroom-cms/api \u2014 do not edit
+
+`;
+var SHARED_TYPES = `
+/** Block content type (loosely typed \u2014 blocks are rendered dynamically). */
+type Block = {
+  id: string;
+  type: string;
+  props?: Record<string, unknown> | null;
+  content?: unknown;
+  children?: Block[];
+};
+
+/** Shared metadata fields present on all content items. */
+const contentMeta = {
+  contentId: z.string(),
+  collection: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  snippet: z.string(),
+  publishedAt: z.number(),
+  tags: z.array(z.string()),
+  coverUrl: z.string().optional(),
+  coverMediaId: z.string().optional(),
+  lastPublishedAt: z.number().optional(),
+};
+
+/** Block content schema (loosely typed \u2014 blocks are rendered dynamically). */
+const blockSchema: ZodType<Block> = z.object({
+  id: z.string(),
+  type: z.string(),
+  props: z.record(z.unknown()).nullable().optional(),
+  content: z.unknown().optional(),
+  children: z.lazy(() => z.array(blockSchema)).optional(),
+});
+
+/** Content reference schema. */
+const publicContentRefSchema = z.object({
+  contentId: z.string(),
+  collection: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  published: z.boolean(),
+});
+
+const refsMapSchema = z.record(publicContentRefSchema);
+`;
+function collectionToZod(col) {
+  const bodyFields = col.fields.filter((f) => f.type !== "blocks");
+  const hasBlocks = col.fields.some((f) => f.type === "blocks");
+  const hasBodyFields = bodyFields.length > 0 || hasBlocks;
+  const lines = [];
+  const exportName = camelCase(col.name) + "Schema";
+  lines.push(`/** ${col.label}${col.singleton ? " (singleton)" : ""} */`);
+  lines.push(`export const ${exportName} = z`);
+  if (!hasBodyFields) {
+    lines.push("  .object({");
+    lines.push("    ...contentMeta,");
+    lines.push("  })");
+  } else {
+    lines.push("  .object({");
+    lines.push("    ...contentMeta,");
+    lines.push("    body: z");
+    lines.push("      .object({");
+    if (hasBlocks) {
+      lines.push("        content: z.array(blockSchema).optional(),");
+    }
+    for (const field of bodyFields) {
+      lines.push(`        ${field.name}: ${fieldToZod(field)},`);
+    }
+    lines.push("      })");
+    lines.push("      .passthrough()");
+    lines.push("      .optional(),");
+    lines.push("    _refs: refsMapSchema.optional(),");
+    lines.push("  })");
+  }
+  lines.push("  .passthrough();");
+  return lines.join("\n");
+}
+function camelCase(s) {
+  return s.replace(/[-_]+(\w)/g, (_, c) => c.toUpperCase());
+}
+async function generateZodSchemas(client, opts) {
+  const zodImport = opts?.zodImport ?? "astro/zod";
+  const { items: summaries } = await client.listCollections();
+  const filtered = opts?.collections ? summaries.filter((s) => opts.collections.includes(s.name)) : summaries;
+  const collections = await Promise.all(
+    filtered.map((s) => client.getCollection(s.name))
+  );
+  const parts = [];
+  parts.push(PREAMBLE);
+  parts.push(`import { z, type ZodType } from "${zodImport}";
+`);
+  parts.push(SHARED_TYPES);
+  for (const col of collections) {
+    parts.push("");
+    parts.push(collectionToZod(col));
+  }
+  return parts.join("\n") + "\n";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fieldToZod,
+  generateZodSchemas
+});