@headroom-cms/api 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,227 @@
+interface TextStyles {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    code?: boolean;
+}
+interface TextContent {
+    type: "text";
+    text: string;
+    styles?: TextStyles;
+}
+interface LinkContent {
+    type: "link";
+    href: string;
+    content: TextContent[];
+}
+type InlineContent = TextContent | LinkContent;
+interface TableRow {
+    cells: InlineContent[][];
+}
+interface TableContent {
+    type: "tableContent";
+    rows: TableRow[];
+}
+interface Block {
+    id: string;
+    type: string;
+    props?: Record<string, unknown> | null;
+    content?: InlineContent[] | TableContent;
+    children?: Block[];
+}
+/** A reference to another content item (used in relationships and _refs). */
+interface ContentRef {
+    contentId: string;
+    collection: string;
+    slug: string;
+    title: string;
+}
+/**
+ * Resolved content reference in the public API `_refs` map.
+ * Includes `published` status so frontends can handle broken links.
+ */
+interface PublicContentRef extends ContentRef {
+    published: boolean;
+}
+/**
+ * Map of contentId → resolved reference metadata.
+ * Returned in `_refs` on single-content API responses.
+ * Used by block renderers to resolve `headroom://content/...` links.
+ */
+type RefsMap = Record<string, PublicContentRef>;
+interface ContentMetadata {
+    contentId: string;
+    collection: string;
+    slug: string;
+    title: string;
+    snippet: string;
+    publishedAt: number;
+    tags: string[];
+    coverUrl?: string;
+    coverMediaId?: string;
+    lastPublishedAt?: number;
+}
+interface ContentItem extends ContentMetadata {
+    body?: {
+        content?: Block[];
+        [key: string]: unknown;
+    };
+    /**
+     * Resolved content link references. Map of contentId → metadata.
+     * Populated on single-content responses (GET by ID, GET singleton).
+     * Used by block renderers to resolve `headroom://content/{collection}/{contentId}` links.
+     */
+    _refs?: RefsMap;
+    /**
+     * Content relationships. Map of relationship name → array of referenced content.
+     * Populated on single-content responses (GET by ID, GET singleton).
+     */
+    relationships?: Record<string, ContentRef[]>;
+}
+interface ContentListResult {
+    items: ContentMetadata[];
+    cursor?: string;
+    hasMore: boolean;
+}
+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[];
+}
+interface BlockTypeDef {
+    name: string;
+    label: string;
+    icon?: string;
+    fields?: FieldDef[];
+    previewTemplate?: string;
+    previewData?: Record<string, unknown>;
+}
+interface BlockTypeListResult {
+    items: BlockTypeDef[];
+    builtIn: BlockTypeDef[];
+}
+interface BatchContentResult {
+    items: ContentItem[];
+    missing: string[];
+}
+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;
+}
+/** Options for image transforms via the Sharp Lambda pipeline. */
+interface TransformOptions {
+    /** Target width in pixels */
+    width?: number;
+    /** Target height in pixels */
+    height?: number;
+    /** Resize fit mode */
+    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+    /** Output format */
+    format?: "webp" | "avif" | "jpeg" | "png";
+    /** Quality (1-100) */
+    quality?: number;
+}
+interface HeadroomErrorBody {
+    error: string;
+    code?: string;
+}
+
+declare class HeadroomError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare class HeadroomClient {
+    private config;
+    constructor(config: HeadroomConfig);
+    /** Build the full URL for a public API path */
+    private url;
+    /**
+     * 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: string | undefined): string;
+    /**
+     * 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: string | undefined, opts?: TransformOptions): string;
+    private fetch;
+    private fetchPost;
+    listContent(collection: string, opts?: {
+        limit?: number;
+        cursor?: string;
+        before?: number;
+        after?: number;
+        /** Sort order: "published_desc" (default), "published_asc", "title_asc", "title_desc" */
+        sort?: "published_desc" | "published_asc" | "title_asc" | "title_desc";
+        /** Find content that has a relationship pointing to this content ID (reverse query) */
+        relatedTo?: string;
+        /** Filter reverse query to a specific relationship field name */
+        relField?: string;
+    }): Promise<ContentListResult>;
+    getContent(contentId: string): Promise<ContentItem>;
+    /**
+     * 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.
+     */
+    getContentBySlug(collection: string, slug: string): Promise<ContentItem | undefined>;
+    getSingleton(collection: string): Promise<ContentItem>;
+    /**
+     * Fetch multiple content items with bodies in a single request.
+     * Max 50 IDs per call. Items not found or unpublished are listed in `missing`.
+     */
+    getBatchContent(ids: string[]): Promise<BatchContentResult>;
+    listCollections(): Promise<CollectionListResult>;
+    getCollection(name: string): Promise<Collection>;
+    listBlockTypes(): Promise<BlockTypeListResult>;
+    getVersion(): Promise<number>;
+}
+
+export { type BatchContentResult, type Block, type BlockTypeDef, type BlockTypeListResult, type Collection, type CollectionListResult, type CollectionSummary, type ContentItem, type ContentListResult, type ContentMetadata, type ContentRef, type FieldDef, HeadroomClient, type HeadroomConfig, HeadroomError, type HeadroomErrorBody, type InlineContent, type LinkContent, type PublicContentRef, type RefsMap, type RelationshipDef, type TableContent, type TableRow, type TextContent, type TextStyles, type TransformOptions };

package/dist/index.d.ts

@@ -0,0 +1,227 @@
+interface TextStyles {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    code?: boolean;
+}
+interface TextContent {
+    type: "text";
+    text: string;
+    styles?: TextStyles;
+}
+interface LinkContent {
+    type: "link";
+    href: string;
+    content: TextContent[];
+}
+type InlineContent = TextContent | LinkContent;
+interface TableRow {
+    cells: InlineContent[][];
+}
+interface TableContent {
+    type: "tableContent";
+    rows: TableRow[];
+}
+interface Block {
+    id: string;
+    type: string;
+    props?: Record<string, unknown> | null;
+    content?: InlineContent[] | TableContent;
+    children?: Block[];
+}
+/** A reference to another content item (used in relationships and _refs). */
+interface ContentRef {
+    contentId: string;
+    collection: string;
+    slug: string;
+    title: string;
+}
+/**
+ * Resolved content reference in the public API `_refs` map.
+ * Includes `published` status so frontends can handle broken links.
+ */
+interface PublicContentRef extends ContentRef {
+    published: boolean;
+}
+/**
+ * Map of contentId → resolved reference metadata.
+ * Returned in `_refs` on single-content API responses.
+ * Used by block renderers to resolve `headroom://content/...` links.
+ */
+type RefsMap = Record<string, PublicContentRef>;
+interface ContentMetadata {
+    contentId: string;
+    collection: string;
+    slug: string;
+    title: string;
+    snippet: string;
+    publishedAt: number;
+    tags: string[];
+    coverUrl?: string;
+    coverMediaId?: string;
+    lastPublishedAt?: number;
+}
+interface ContentItem extends ContentMetadata {
+    body?: {
+        content?: Block[];
+        [key: string]: unknown;
+    };
+    /**
+     * Resolved content link references. Map of contentId → metadata.
+     * Populated on single-content responses (GET by ID, GET singleton).
+     * Used by block renderers to resolve `headroom://content/{collection}/{contentId}` links.
+     */
+    _refs?: RefsMap;
+    /**
+     * Content relationships. Map of relationship name → array of referenced content.
+     * Populated on single-content responses (GET by ID, GET singleton).
+     */
+    relationships?: Record<string, ContentRef[]>;
+}
+interface ContentListResult {
+    items: ContentMetadata[];
+    cursor?: string;
+    hasMore: boolean;
+}
+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[];
+}
+interface BlockTypeDef {
+    name: string;
+    label: string;
+    icon?: string;
+    fields?: FieldDef[];
+    previewTemplate?: string;
+    previewData?: Record<string, unknown>;
+}
+interface BlockTypeListResult {
+    items: BlockTypeDef[];
+    builtIn: BlockTypeDef[];
+}
+interface BatchContentResult {
+    items: ContentItem[];
+    missing: string[];
+}
+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;
+}
+/** Options for image transforms via the Sharp Lambda pipeline. */
+interface TransformOptions {
+    /** Target width in pixels */
+    width?: number;
+    /** Target height in pixels */
+    height?: number;
+    /** Resize fit mode */
+    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+    /** Output format */
+    format?: "webp" | "avif" | "jpeg" | "png";
+    /** Quality (1-100) */
+    quality?: number;
+}
+interface HeadroomErrorBody {
+    error: string;
+    code?: string;
+}
+
+declare class HeadroomError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare class HeadroomClient {
+    private config;
+    constructor(config: HeadroomConfig);
+    /** Build the full URL for a public API path */
+    private url;
+    /**
+     * 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: string | undefined): string;
+    /**
+     * 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: string | undefined, opts?: TransformOptions): string;
+    private fetch;
+    private fetchPost;
+    listContent(collection: string, opts?: {
+        limit?: number;
+        cursor?: string;
+        before?: number;
+        after?: number;
+        /** Sort order: "published_desc" (default), "published_asc", "title_asc", "title_desc" */
+        sort?: "published_desc" | "published_asc" | "title_asc" | "title_desc";
+        /** Find content that has a relationship pointing to this content ID (reverse query) */
+        relatedTo?: string;
+        /** Filter reverse query to a specific relationship field name */
+        relField?: string;
+    }): Promise<ContentListResult>;
+    getContent(contentId: string): Promise<ContentItem>;
+    /**
+     * 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.
+     */
+    getContentBySlug(collection: string, slug: string): Promise<ContentItem | undefined>;
+    getSingleton(collection: string): Promise<ContentItem>;
+    /**
+     * Fetch multiple content items with bodies in a single request.
+     * Max 50 IDs per call. Items not found or unpublished are listed in `missing`.
+     */
+    getBatchContent(ids: string[]): Promise<BatchContentResult>;
+    listCollections(): Promise<CollectionListResult>;
+    getCollection(name: string): Promise<Collection>;
+    listBlockTypes(): Promise<BlockTypeListResult>;
+    getVersion(): Promise<number>;
+}
+
+export { type BatchContentResult, type Block, type BlockTypeDef, type BlockTypeListResult, type Collection, type CollectionListResult, type CollectionSummary, type ContentItem, type ContentListResult, type ContentMetadata, type ContentRef, type FieldDef, HeadroomClient, type HeadroomConfig, HeadroomError, type HeadroomErrorBody, type InlineContent, type LinkContent, type PublicContentRef, type RefsMap, type RelationshipDef, type TableContent, type TableRow, type TextContent, type TextStyles, type TransformOptions };

package/dist/index.js

@@ -0,0 +1,174 @@
+// 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;
+  }
+};
+export {
+  HeadroomClient,
+  HeadroomError
+};