Skip to content

The Open Standard for Generative UI

3.2 KB
Raw Blame
import { fetchSourceFile } from "../../../lib/checkout";
import { CreateError } from "../../../lib/errors";
import type { RetryAttemptInfo } from "../../../lib/retry";

export const TEMPLATES_CATALOG_PATH = "templates/templates.json";

export const DEFAULT_TEMPLATE_KEY = "openui-cloud";

export type CatalogOverlay = {
  name: string;
  key: string;
  description: string;
};

export type CatalogTemplate = {
  name: string;
  key: string;
  description: string;
  overlays: CatalogOverlay[];
};

function catalogError(message: string): CreateError {
  return new CreateError("args_resolution", message, "invalid_input", "TEMPLATE_CATALOG_INVALID");
}

function parseOverlay(item: unknown): CatalogOverlay {
  const overlay = item as CatalogOverlay;
  if (
    typeof overlay?.name !== "string" ||
    typeof overlay?.key !== "string" ||
    typeof overlay?.description !== "string"
  ) {
    throw catalogError(
      `${TEMPLATES_CATALOG_PATH} has an overlay missing name, key, or description.`,
    );
  }
  return overlay;
}

function parseTemplate(item: unknown): CatalogTemplate {
  const template = item as CatalogTemplate;
  if (
    typeof template?.name !== "string" ||
    typeof template?.key !== "string" ||
    typeof template?.description !== "string"
  ) {
    throw catalogError(
      `${TEMPLATES_CATALOG_PATH} has a template missing name, key, or description.`,
    );
  }
  if (!Array.isArray(template.overlays) || template.overlays.length === 0) {
    throw catalogError(`Template "${template.key}" has no overlays.`);
  }
  return { ...template, overlays: template.overlays.map(parseOverlay) };
}

function parseTemplatesCatalog(raw: string): CatalogTemplate[] {
  const parsed = JSON.parse(raw) as { templates?: unknown };
  if (!Array.isArray(parsed.templates) || parsed.templates.length === 0) {
    throw catalogError(`${TEMPLATES_CATALOG_PATH} must contain a non-empty "templates" array.`);
  }
  return parsed.templates.map(parseTemplate);
}

/** Prefetch the template catalog from GitHub. */
export async function loadTemplatesCatalog(
  opts: {
    onRetry?: (info: RetryAttemptInfo) => void;
  } = {},
): Promise<CatalogTemplate[]> {
  const { content } = await fetchSourceFile(TEMPLATES_CATALOG_PATH, { onRetry: opts.onRetry });
  return parseTemplatesCatalog(content);
}

export function findCatalogTemplate(templates: CatalogTemplate[], key: string): CatalogTemplate {
  const normalized = key.toLowerCase();
  const match = templates.find((entry) => entry.key.toLowerCase() === normalized);
  if (!match) {
    const available = templates.map((entry) => entry.key).join(" | ");
    throw new CreateError(
      "args_resolution",
      `unknown template "${key}". Use: ${available}.`,
      "invalid_input",
      "INVALID_TEMPLATE",
    );
  }
  return match;
}

export function findCatalogOverlay(template: CatalogTemplate, key: string): CatalogOverlay {
  const normalized = key.toLowerCase();
  const match = template.overlays.find((entry) => entry.key.toLowerCase() === normalized);
  if (!match) {
    const available = template.overlays.map((entry) => entry.key).join(" | ");
    throw new CreateError(
      "args_resolution",
      `unknown backend framework "${key}". Use: ${available}.`,
      "invalid_input",
      "INVALID_BACKEND_FRAMEWORK",
    );
  }
  return match;
}