@headroom-cms/api 0.1.1

package/dist/codegen.d.cts

@@ -0,0 +1,49 @@
+interface FieldDef {
+    name: string;
+    type: string;
+    label: string;
+    options?: Record<string, unknown> | null;
+}
+interface CollectionSummary {
+    name: string;
+    label: string;
+    labelSingular: string;
+    slug?: string;
+    singleton: boolean;
+}
+/** Defines a belongs-to relationship on a collection. */
+interface RelationshipDef {
+    name: string;
+    label: string;
+    targetCollection: string;
+    multiple: boolean;
+}
+interface Collection extends CollectionSummary {
+    version: number;
+    fields: FieldDef[];
+    relationships?: RelationshipDef[];
+}
+interface CollectionListResult {
+    items: CollectionSummary[];
+}
+
+/** Minimal client interface for schema generation (avoids private-property TS issues). */
+interface SchemaGenClient {
+    listCollections(): Promise<CollectionListResult>;
+    getCollection(name: string): Promise<Collection>;
+}
+interface GenerateOptions {
+    /** Which collections to generate (default: all) */
+    collections?: string[];
+    /** Import source for z — "astro/zod" (default) or "zod" */
+    zodImport?: string;
+}
+/** Map a single FieldDef to a Zod expression string. */
+declare function fieldToZod(field: FieldDef): string;
+/**
+ * Generate a complete TypeScript file with Zod schemas for all (or selected)
+ * collections. Fetches collection definitions from the Headroom public API.
+ */
+declare function generateZodSchemas(client: SchemaGenClient, opts?: GenerateOptions): Promise<string>;
+
+export { type GenerateOptions, fieldToZod, generateZodSchemas };

package/dist/codegen.d.ts

@@ -0,0 +1,49 @@
+interface FieldDef {
+    name: string;
+    type: string;
+    label: string;
+    options?: Record<string, unknown> | null;
+}
+interface CollectionSummary {
+    name: string;
+    label: string;
+    labelSingular: string;
+    slug?: string;
+    singleton: boolean;
+}
+/** Defines a belongs-to relationship on a collection. */
+interface RelationshipDef {
+    name: string;
+    label: string;
+    targetCollection: string;
+    multiple: boolean;
+}
+interface Collection extends CollectionSummary {
+    version: number;
+    fields: FieldDef[];
+    relationships?: RelationshipDef[];
+}
+interface CollectionListResult {
+    items: CollectionSummary[];
+}
+
+/** Minimal client interface for schema generation (avoids private-property TS issues). */
+interface SchemaGenClient {
+    listCollections(): Promise<CollectionListResult>;
+    getCollection(name: string): Promise<Collection>;
+}
+interface GenerateOptions {
+    /** Which collections to generate (default: all) */
+    collections?: string[];
+    /** Import source for z — "astro/zod" (default) or "zod" */
+    zodImport?: string;
+}
+/** Map a single FieldDef to a Zod expression string. */
+declare function fieldToZod(field: FieldDef): string;
+/**
+ * Generate a complete TypeScript file with Zod schemas for all (or selected)
+ * collections. Fetches collection definitions from the Headroom public API.
+ */
+declare function generateZodSchemas(client: SchemaGenClient, opts?: GenerateOptions): Promise<string>;
+
+export { type GenerateOptions, fieldToZod, generateZodSchemas };

package/dist/codegen.js

@@ -0,0 +1,144 @@
+// 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";
+}
+export {
+  fieldToZod,
+  generateZodSchemas
+};

package/dist/headroom-blocks.css

@@ -0,0 +1,96 @@
+/* @headroom-cms/api — default block styles */
+
+:where(.hr-bold) { font-weight: bold; }
+:where(.hr-italic) { font-style: italic; }
+:where(.hr-underline) { text-decoration: underline; }
+:where(.hr-strikethrough) { text-decoration: line-through; }
+:where(.hr-code) {
+  font-family: ui-monospace, monospace;
+  background: var(--hr-code-bg, #f3f4f6);
+  padding: 0.125em 0.25em;
+  border-radius: 0.25em;
+  font-size: 0.875em;
+}
+:where(.hr-link) {
+  color: var(--hr-link-color, #2563eb);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+:where(.hr-image img) {
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--hr-image-radius, 0.5rem);
+}
+:where(.hr-image figcaption) {
+  margin-top: 0.5em;
+  font-size: 0.875em;
+  color: var(--hr-caption-color, #6b7280);
+  text-align: center;
+}
+:where(.hr-code-block) {
+  background: var(--hr-code-block-bg, #1e1e1e);
+  color: var(--hr-code-block-color, #d4d4d4);
+  padding: 1em;
+  border-radius: 0.5em;
+  overflow-x: auto;
+  font-size: 0.875em;
+}
+:where(.hr-check-list) {
+  list-style: none;
+  padding-left: 0;
+}
+:where(.hr-check-item) {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5em;
+}
+:where(.hr-check-item[data-checked]) {
+  text-decoration: line-through;
+  opacity: 0.7;
+}
+:where(.hr-checkbox) {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1em;
+  height: 1em;
+  margin-top: 0.25em;
+  border: 1px solid #d1d5db;
+  border-radius: 0.2em;
+  flex-shrink: 0;
+}
+:where(.hr-checkbox[aria-checked="true"]) {
+  background: var(--hr-accent, #2563eb);
+  border-color: var(--hr-accent, #2563eb);
+  color: white;
+}
+:where(.hr-checkbox svg) {
+  width: 1em;
+  height: 1em;
+}
+:where(.hr-table) {
+  width: 100%;
+  border-collapse: collapse;
+}
+:where(.hr-table th, .hr-table td) {
+  border: 1px solid #e5e7eb;
+  padding: 0.5em 0.75em;
+  text-align: left;
+}
+:where(.hr-table th) {
+  background: var(--hr-table-header-bg, #f9fafb);
+  font-weight: 600;
+}
+:where(.hr-fallback) {
+  padding: 1em;
+  border: 1px solid #e5e7eb;
+  border-radius: 0.5em;
+  background: #f9fafb;
+  margin: 0.5em 0;
+}
+:where(.hr-fallback-label) {
+  font-size: 0.75em;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: #9ca3af;
+}

package/dist/index.cjs

@@ -0,0 +1,202 @@
+"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/index.ts
+var src_exports = {};
+__export(src_exports, {
+  HeadroomClient: () => HeadroomClient,
+  HeadroomError: () => HeadroomError
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/client.ts
+var import_node_crypto = require("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 = (0, import_node_crypto.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;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HeadroomClient,
+  HeadroomError
+});