@backmatter/core 0.0.22 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Experimental Backmatter SDK. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {

package/src/fields.ts

@@ -4,6 +4,7 @@ export type FieldKind =
   | "text"
   | "locale"
   | "image"
+  | "media"
   | "relation"
   | "number"
   | "boolean"
@@ -78,6 +79,7 @@ export const field = {
   text: <const R extends boolean = false>(opts?: Opts<R>) => base("text", opts),
   locale: <const R extends boolean = false>(opts?: Opts<R>) => base("locale", opts),
   image: <const R extends boolean = false>(opts?: Opts<R>) => base("image", opts),
+  media: <const R extends boolean = false>(opts?: Opts<R>) => base("media", opts),
   number: <const R extends boolean = false>(opts?: Opts<R>) => base("number", opts),
   boolean: <const R extends boolean = false>(opts?: Opts<R>) => base("boolean", opts),
   relation: <To extends string, const R extends boolean = false>(to: To, opts?: Opts<R>) =>
@@ -117,6 +119,7 @@ export function parseFieldSnapshot(input: unknown): FieldSnapshot {
     "text",
     "locale",
     "image",
+    "media",
     "relation",
     "number",
     "boolean",

package/src/index.ts

@@ -8,6 +8,19 @@ export type {
   FieldSnapshot,
 } from "./fields";
 export { field, serializeField, parseFieldSnapshot } from "./fields";
+export {
+  MAX_MEDIA_BYTES,
+  MEDIA_CONTENT_TYPES,
+  MEDIA_WIDTHS,
+  isMediaContentType,
+  isMediaId,
+  isMediaWidth,
+  mediaIdFromUrl,
+  mediaOriginalUrl,
+  mediaVariantUrl,
+} from "./media-url";
+export type { MediaContentType, MediaWidth } from "./media-url";
+export { mediaIdsInDocument } from "./media-fields";
 
 export type { ObjectDef, ObjectSnapshot } from "./object";
 export { defineObject, serializeObject, parseObjectSnapshot } from "./object";
@@ -136,6 +149,7 @@ export {
   PREVIEW_ENABLE_PATH,
   PREVIEW_QUERY,
   PREVIEW_CHECKOUT_QUERY,
+  PREVIEW_LOCALE_QUERY,
   previewLocationWithCheckout,
   isSafeRedirectPath,
   mintPreviewSession,

package/src/media-fields.ts

@@ -0,0 +1,55 @@
+// packages/core/src/media-fields.ts
+import type { FieldSnapshot } from "./fields";
+import { mediaIdFromUrl } from "./media-url";
+
+type BlockCatalog = Array<{ name: string; fields: Record<string, FieldSnapshot> }>;
+
+/** Media ids referenced by media fields in a document or block props. */
+export function mediaIdsInDocument(
+  fields: Record<string, FieldSnapshot>,
+  data: Record<string, unknown>,
+  blocks: BlockCatalog = [],
+): string[] {
+  const ids: string[] = [];
+  collect(fields, data, blocks, ids);
+  return ids;
+}
+
+function collect(
+  fields: Record<string, FieldSnapshot>,
+  data: Record<string, unknown>,
+  blocks: BlockCatalog,
+  ids: string[],
+) {
+  for (const [name, field] of Object.entries(fields)) {
+    const value = data[name];
+    if (value == null) continue;
+    if (field.kind === "media") {
+      if (typeof value === "string") {
+        const id = mediaIdFromUrl(value);
+        if (id) ids.push(id);
+      }
+      continue;
+    }
+    if (field.kind === "blocks" && Array.isArray(value)) {
+      for (const item of value) {
+        if (!item || typeof item !== "object") continue;
+        const row = item as { type?: unknown; props?: unknown };
+        const def = blocks.find((block) => block.name === row.type);
+        if (!def || !row.props || typeof row.props !== "object") continue;
+        collect(def.fields, row.props as Record<string, unknown>, blocks, ids);
+      }
+      continue;
+    }
+    if (field.kind === "object" && field.fields && value && typeof value === "object") {
+      collect(field.fields, value as Record<string, unknown>, blocks, ids);
+    }
+    if (field.kind === "array" && field.fields && Array.isArray(value)) {
+      for (const item of value) {
+        if (item && typeof item === "object") {
+          collect(field.fields, item as Record<string, unknown>, blocks, ids);
+        }
+      }
+    }
+  }
+}

package/src/media-url.ts

@@ -0,0 +1,67 @@
+// packages/core/src/media-url.ts
+
+/** Widths the catalog lists for the gallery. A public URL may use any positive width. */
+export const MEDIA_WIDTHS = [400, 800, 1200, 2000] as const;
+
+export type MediaWidth = (typeof MEDIA_WIDTHS)[number];
+
+/** Bytes the catalog accepts for one file. */
+export const MAX_MEDIA_BYTES = 20 * 1024 * 1024;
+
+export const MEDIA_CONTENT_TYPES = [
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "image/gif",
+  "image/avif",
+] as const;
+
+export type MediaContentType = (typeof MEDIA_CONTENT_TYPES)[number];
+
+const MEDIA_ID =
+  /^med_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isMediaId(value: string): boolean {
+  return MEDIA_ID.test(value);
+}
+
+export function isMediaContentType(value: string): value is MediaContentType {
+  return (MEDIA_CONTENT_TYPES as readonly string[]).includes(value);
+}
+
+export function mediaOriginalUrl(origin: string, id: string): string {
+  return `${origin.replace(/\/$/, "")}/img/${id}`;
+}
+
+/** A width variant, or null when the id or width cannot be requested. */
+export function mediaVariantUrl(
+  origin: string,
+  id: string,
+  width: number,
+): string | null {
+  if (!isMediaId(id) || !Number.isInteger(width) || width < 1) return null;
+  return `${origin.replace(/\/$/, "")}/img/${id}/width=${width},format=auto`;
+}
+
+export function isMediaWidth(width: number): width is MediaWidth {
+  return (MEDIA_WIDTHS as readonly number[]).includes(width);
+}
+
+/**
+ * The id inside an original media URL (`/img/med_…`, no options segment).
+ * A transform URL and any other URL return null.
+ */
+export function mediaIdFromUrl(value: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+  if (url.search || url.hash) return null;
+  const parts = url.pathname.split("/").filter(Boolean);
+  if (parts.length !== 2 || parts[0] !== "img") return null;
+  const id = parts[1]!;
+  return isMediaId(id) ? id : null;
+}

package/src/node/cli.ts

@@ -18,6 +18,7 @@ import { discoverModels, discoverBlocks } from "./discover";
 import { walkContentFiles } from "./fs-loader";
 import { detectSdk, findConfigFile, generate, type GenerateResult } from "./generate";
 import { ensureRegistryTsconfig, REGISTRY_SPECIFIER } from "./registry-import";
+import { MEDIA_USAGE, runMediaCli } from "./media-cli";
 
 export type CliArgs = {
   command?: string;
@@ -33,6 +34,10 @@ const USAGE = `Usage:
   backmatter generate  [--root <dir>]      write .backmatter/index.ts (typed cms), blocks.ts, mdx.ts, layouts.ts and sources.ts
   backmatter validate  [--root <dir>] [--models <file>] [--json]
   backmatter schema    [--root <dir>] [--models <file>] [--out <dir>]
+  backmatter login
+  backmatter media upload|list|url
+
+${MEDIA_USAGE}
 
 Defaults: --root .  --out .backmatter/schemas
 Models are discovered from models/*.ts (one \`export default defineModel(...)\` per
@@ -550,6 +555,9 @@ export async function runInit(args: CliArgs): Promise<string[]> {
 }
 
 async function main(argv: string[]): Promise<number> {
+  if (argv[0] === "login" || argv[0] === "media") {
+    return runMediaCli(argv);
+  }
   let args: CliArgs;
   try {
     args = parseArgs(argv);

package/src/node/media-cli.ts

@@ -0,0 +1,211 @@
+// packages/core/src/node/media-cli.ts
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { mediaOriginalUrl, mediaVariantUrl } from "../media-url";
+
+export const MEDIA_USAGE = `Usage:
+  backmatter login [--api <url>] [--web <url>]
+  backmatter media upload <file...> --workspace <id> [--api <url>]
+  backmatter media list [--q <text>] --workspace <id> [--api <url>]
+  backmatter media url <id> [--width <px>] [--origin <url>]
+
+login opens the browser and stores a personal token in ~/.backmatter/credentials.json.
+media url prints a CDN url. --width <px> appends width and format=auto.`;
+
+type Credentials = { api: string; token: string; origin?: string };
+
+export async function runMediaCli(
+  argv: string[],
+  io: {
+    log?: (line: string) => void;
+    error?: (line: string) => void;
+    open?: (url: string) => void;
+    fetch?: typeof fetch;
+    home?: string;
+    env?: Record<string, string | undefined>;
+  } = {},
+): Promise<number> {
+  const log = io.log ?? ((line) => console.log(line));
+  const error = io.error ?? ((line) => console.error(line));
+  const home = io.home ?? os.homedir();
+  const env = io.env ?? process.env;
+  try {
+    const command = argv[0];
+    if (command === "login") return await login(argv.slice(1), { log, error, open: io.open, fetch: io.fetch, home, env });
+    if (command === "media") return await media(argv.slice(1), { log, error, fetch: io.fetch, home, env });
+    error(MEDIA_USAGE);
+    return 2;
+  } catch (err) {
+    error(`backmatter: ${err instanceof Error ? err.message : String(err)}`);
+    return 2;
+  }
+}
+
+async function login(
+  argv: string[],
+  io: {
+    log: (line: string) => void;
+    error: (line: string) => void;
+    open?: (url: string) => void;
+    fetch?: typeof fetch;
+    home: string;
+    env: Record<string, string | undefined>;
+  },
+): Promise<number> {
+  const flags = readFlags(argv);
+  const api = (flags.api || io.env.BACKMATTER_API_URL || "http://localhost:3001").replace(/\/$/, "");
+  const web = (flags.web || io.env.BACKMATTER_WEB_ORIGIN || "http://localhost:5173").replace(/\/$/, "");
+  const pollSecret = crypto.randomUUID() + crypto.randomUUID();
+  const fetchImpl = io.fetch ?? fetch;
+  const started = await fetchImpl(`${api}/cli/login`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ pollSecret }),
+  });
+  if (!started.ok) throw new Error(`login failed: ${started.status}`);
+  const body = (await started.json()) as { id: string; authorizeUrl: string };
+  const authorizeUrl = body.authorizeUrl || `${web}/cli/authorize?id=${encodeURIComponent(body.id)}`;
+  (io.open ?? openBrowser)(authorizeUrl);
+  io.error(`Open ${authorizeUrl} and approve the CLI.`);
+  const deadline = Date.now() + 10 * 60 * 1000;
+  while (Date.now() < deadline) {
+    await delay(1000);
+    const polled = await fetchImpl(`${api}/cli/login/${body.id}`, {
+      headers: { "x-backmatter-poll": pollSecret },
+    });
+    if (!polled.ok) continue;
+    const status = (await polled.json()) as { status: string; token?: string };
+    if (status.status === "ready" && status.token) {
+      await writeCredentials(io.home, { api, token: status.token });
+      io.log("Logged in.");
+      return 0;
+    }
+  }
+  throw new Error("login timed out");
+}
+
+async function media(
+  argv: string[],
+  io: {
+    log: (line: string) => void;
+    error: (line: string) => void;
+    fetch?: typeof fetch;
+    home: string;
+    env: Record<string, string | undefined>;
+  },
+): Promise<number> {
+  const sub = argv[0];
+  const rest = argv.slice(1);
+  const flags = readFlags(rest);
+  const positionals = rest.filter((arg, index) => {
+    if (arg.startsWith("--")) return false;
+    const prev = rest[index - 1];
+    return prev !== "--workspace" && prev !== "--api" && prev !== "--q" && prev !== "--width" && prev !== "--origin";
+  });
+  if (sub === "url") {
+    const id = positionals[0];
+    if (!id) throw new Error("usage: backmatter media url <id>");
+    const origin = flags.origin || "https://cdn.backmatter.app";
+    if (flags.width) {
+      const width = Number(flags.width);
+      const url = mediaVariantUrl(origin, id, width);
+      if (!url) throw new Error("width must be a positive integer");
+      io.log(url);
+      return 0;
+    }
+    io.log(mediaOriginalUrl(origin, id));
+    return 0;
+  }
+  const creds = await readCredentials(io.home);
+  const api = (flags.api || creds?.api || io.env.BACKMATTER_API_URL || "").replace(/\/$/, "");
+  const token = creds?.token;
+  const workspace = flags.workspace || io.env.BACKMATTER_WORKSPACE;
+  if (!api || !token) throw new Error("run backmatter login first");
+  if (!workspace) throw new Error("pass --workspace <id>");
+  const fetchImpl = io.fetch ?? fetch;
+  if (sub === "list") {
+    const params = new URLSearchParams();
+    if (flags.q) params.set("q", flags.q);
+    const query = params.size ? `?${params}` : "";
+    const res = await fetchImpl(`${api}/workspaces/${workspace}/media${query}`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) throw new Error(`list failed: ${res.status}`);
+    const page = (await res.json()) as { total: number; media: Array<{ id: string; filename: string; url: string }> };
+    io.log(`${page.total} image${page.total === 1 ? "" : "s"}`);
+    for (const item of page.media) io.log(`${item.filename}\t${item.url}`);
+    return 0;
+  }
+  if (sub === "upload") {
+    if (positionals.length === 0) throw new Error("usage: backmatter media upload <file...>");
+    for (const file of positionals) {
+      const bytes = await readFile(file);
+      const body = new FormData();
+      body.set("file", new File([bytes], path.basename(file), { type: contentTypeFor(file) }));
+      const res = await fetchImpl(`${api}/workspaces/${workspace}/media`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+        body,
+      });
+      if (!res.ok) throw new Error(`upload failed for ${file}: ${res.status}`);
+      const payload = (await res.json()) as { media: { url: string; filename: string } };
+      io.log(`${payload.media.filename}\t${payload.media.url}`);
+    }
+    return 0;
+  }
+  io.error(MEDIA_USAGE);
+  return 2;
+}
+
+function contentTypeFor(file: string): string {
+  const ext = path.extname(file).toLowerCase();
+  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
+  if (ext === ".webp") return "image/webp";
+  if (ext === ".gif") return "image/gif";
+  if (ext === ".avif") return "image/avif";
+  return "image/png";
+}
+
+function readFlags(argv: string[]): Record<string, string> {
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (!arg.startsWith("--")) continue;
+    const key = arg.slice(2);
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith("--")) throw new Error(`usage: missing value for --${key}`);
+    flags[key] = value;
+    i += 1;
+  }
+  return flags;
+}
+
+function credentialsPath(home: string): string {
+  return path.join(home, ".backmatter", "credentials.json");
+}
+
+async function readCredentials(home: string): Promise<Credentials | null> {
+  try {
+    return JSON.parse(await readFile(credentialsPath(home), "utf8")) as Credentials;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCredentials(home: string, creds: Credentials): Promise<void> {
+  const file = credentialsPath(home);
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, JSON.stringify(creds, null, 2));
+}
+
+function openBrowser(url: string) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  spawn(command, args, { stdio: "ignore", detached: true }).unref();
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/preview-session.ts

@@ -7,6 +7,8 @@ export const PREVIEW_SESSION_QUERY = "backmatter_session";
 export const PREVIEW_SESSION_STORAGE_KEY = "backmatter_preview_session";
 export const PREVIEW_QUERY = "backmatter_preview";
 export const PREVIEW_CHECKOUT_QUERY = "backmatter_checkout";
+/** File locale for routes whose template has no `{locale}`. `-` means none. */
+export const PREVIEW_LOCALE_QUERY = "backmatter_locale";
 export const PREVIEW_ENABLE_PATH = "/api/backmatter/preview";
 export const PREVIEW_TICKET_TTL_MS = 10 * 60 * 1000;
 export const PREVIEW_COOKIE_TTL_MS = 12 * 60 * 60 * 1000;

package/src/preview.ts

@@ -1,5 +1,6 @@
 // packages/core/src/preview.ts
 import type { BackmatterDoc, BackmatterDocSummary } from "./doc";
+import { encodeDocLocale } from "./path";
 
 export type PreviewDocRef = {
   locale: string;
@@ -106,6 +107,7 @@ export async function fetchHostPreviewSession(origin = ""): Promise<HostPreviewS
     if (!res.ok) return { enabled: false, reason: "unavailable" };
     const data = (await res.json()) as {
       mode?: string;
+      signedIn?: boolean;
       branch?: string;
       tree?: string;
       reason?: unknown;
@@ -196,7 +198,10 @@ function previewParams(options: PreviewClientOptions, ref: PreviewDocRef) {
 }
 
 function docPath(options: PreviewClientOptions, ref: PreviewDocRef) {
-  return `${baseUrl(options.apiUrl)}/preview/workspaces/${options.workspaceId}/docs/${ref.locale}/${ref.type}/${ref.slug}`;
+  const locale = encodeURIComponent(encodeDocLocale(ref.locale));
+  const type = encodeURIComponent(ref.type);
+  const slug = encodeURIComponent(ref.slug);
+  return `${baseUrl(options.apiUrl)}/preview/workspaces/${options.workspaceId}/docs/${locale}/${type}/${slug}`;
 }
 
 export function previewDocRequestUrl(

package/src/validate.ts

@@ -33,6 +33,8 @@ export function validateFrontmatter(
     const missing = data[name] === undefined;
     if (issue.code === "too_small" || (issue.code === "invalid_type" && missing)) {
       errors.push(`${name} is required`);
+    } else if (field.kind === "media" && !missing) {
+      errors.push(`${name} must be a media URL`);
     } else {
       errors.push(`${name} must be a ${expectedTypeFor(field.kind)}`);
     }

package/src/zod.ts

@@ -1,6 +1,7 @@
 // packages/core/src/zod.ts
 import { z } from "zod";
 import type { FieldKind, FieldSnapshot } from "./fields";
+import { mediaIdFromUrl } from "./media-url";
 import type { Frontmatter } from "./mdx";
 import type { ModelSnapshot } from "./model";
 
@@ -21,6 +22,7 @@ export function expectedTypeFor(
     case "text":
     case "locale":
     case "image":
+    case "media":
     case "relation":
       return "string";
     default: {
@@ -44,6 +46,8 @@ export function exampleValueFor(kind: FieldKind): unknown {
       return {};
     case "image":
       return "https://example.com/image.jpg";
+    case "media":
+      return "https://cdn.backmatter.app/img/med_018f6b3e-7c2a-7b1d-8e4f-9a0b1c2d3e4f";
     case "locale":
       return "en";
     case "relation":
@@ -84,6 +88,15 @@ function fieldZod(field: FieldSnapshot): z.ZodType {
     const arr = z.array(objectZod(field));
     return field.required ? arr : arr.optional();
   }
+  if (field.kind === "media") {
+    const url = z.string().refine((value) => value.trim() === "" || mediaIdFromUrl(value) !== null);
+    if (!field.required) return url.optional();
+    return z
+      .string()
+      .trim()
+      .min(1)
+      .refine((value) => mediaIdFromUrl(value) !== null);
+  }
   let base: z.ZodType;
   switch (expectedTypeFor(field.kind)) {
     case "number":