@backmatter/core 0.0.6

package/src/preview-session.ts

@@ -0,0 +1,131 @@
+// packages/core/src/preview-session.ts
+import { signPayload, verifyPayload } from "./signed-token";
+
+export const PREVIEW_COOKIE = "backmatter_preview";
+export const PREVIEW_QUERY = "backmatter_preview";
+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;
+
+export type PreviewCheckout = {
+  branch?: string;
+  tree?: string;
+};
+
+export type PreviewTicket = {
+  v: 1;
+  workspaceId: string;
+  redirect: string;
+  branch?: string;
+  tree?: string;
+  exp: number;
+};
+
+export type PreviewCookiePayload = {
+  v: 1;
+  branch?: string;
+  tree?: string;
+  exp: number;
+};
+
+export function isSafeRedirectPath(path: string): boolean {
+  if (!path.startsWith("/") || path.startsWith("//")) return false;
+  if (path.includes("://")) return false;
+  return true;
+}
+
+export async function mintPreviewTicket(
+  secret: string,
+  input: {
+    workspaceId: string;
+    redirect: string;
+    branch?: string;
+    tree?: string;
+    exp: number;
+  },
+): Promise<string> {
+  if (!isSafeRedirectPath(input.redirect)) {
+    throw new Error("preview ticket redirect must be a same-origin path");
+  }
+  const payload: PreviewTicket = {
+    v: 1,
+    workspaceId: input.workspaceId,
+    redirect: input.redirect,
+    exp: input.exp,
+    ...(input.branch ? { branch: input.branch } : {}),
+    ...(input.tree ? { tree: input.tree } : {}),
+  };
+  return signPayload(secret, payload);
+}
+
+function asTicket(value: unknown): PreviewTicket | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (v.v !== 1 || typeof v.workspaceId !== "string" || typeof v.redirect !== "string") {
+    return null;
+  }
+  if (typeof v.exp !== "number" || v.exp <= Date.now()) return null;
+  if (!isSafeRedirectPath(v.redirect)) return null;
+  return {
+    v: 1,
+    workspaceId: v.workspaceId,
+    redirect: v.redirect,
+    exp: v.exp,
+    ...(typeof v.branch === "string" && v.branch ? { branch: v.branch } : {}),
+    ...(typeof v.tree === "string" && v.tree ? { tree: v.tree } : {}),
+  };
+}
+
+export async function readPreviewTicket(secret: string, token: string): Promise<PreviewTicket | null> {
+  return asTicket(await verifyPayload(secret, token));
+}
+
+export async function writePreviewCookie(
+  secret: string,
+  input: PreviewCheckout & { exp: number },
+): Promise<string> {
+  const payload: PreviewCookiePayload = {
+    v: 1,
+    exp: input.exp,
+    ...(input.branch ? { branch: input.branch } : {}),
+    ...(input.tree ? { tree: input.tree } : {}),
+  };
+  return signPayload(secret, payload);
+}
+
+export async function readPreviewCookie(
+  secret: string,
+  token: string | undefined,
+): Promise<PreviewCheckout | null> {
+  if (!token) return null;
+  const value = await verifyPayload(secret, token);
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (v.v !== 1 || typeof v.exp !== "number" || v.exp <= Date.now()) return null;
+  return {
+    ...(typeof v.branch === "string" && v.branch ? { branch: v.branch } : {}),
+    ...(typeof v.tree === "string" && v.tree ? { tree: v.tree } : {}),
+  };
+}
+
+export type PreviewMiddlewareDecision =
+  | { type: "redirect"; location: string }
+  | { type: "headers"; headers: Record<string, string> }
+  | { type: "next" };
+
+export const PREVIEW_CACHE_HEADERS = {
+  "Cache-Control": "private, no-store",
+  "X-Robots-Tag": "noindex",
+} as const;
+
+/** Edge-safe: no CMS API. Ticket query → enable route; draft → no-store. */
+export function previewMiddlewareDecision(url: URL, draftEnabled: boolean): PreviewMiddlewareDecision {
+  const ticket = url.searchParams.get(PREVIEW_QUERY)?.trim();
+  if (ticket) {
+    return { type: "redirect", location: `${PREVIEW_ENABLE_PATH}?ticket=${encodeURIComponent(ticket)}` };
+  }
+  if (draftEnabled) {
+    return { type: "headers", headers: { ...PREVIEW_CACHE_HEADERS } };
+  }
+  return { type: "next" };
+}

package/src/preview.ts

@@ -0,0 +1,205 @@
+// packages/core/src/preview.ts
+import type { BackmatterDoc } from "./doc";
+
+export type PreviewDocRef = {
+  locale: string;
+  type: string;
+  slug: string;
+  /** Editor checkout branch. Omit to read the workspace default branch. */
+  branch?: string;
+  /**
+   * Working tree owner (the editing user's id). With it the preview shows that
+   * user's uncommitted copy and streams their saves; without it, branch HEAD.
+   */
+  tree?: string;
+};
+
+export type PreviewChangeEvent = PreviewDocRef & {
+  updatedAt: string;
+  frontmatter?: Record<string, unknown>;
+  body?: string;
+  raw?: string;
+};
+
+export type PreviewClientOptions = {
+  apiUrl: string;
+  workspaceId: string;
+  previewToken: string;
+};
+
+export {
+  installPreviewHotkeys,
+  parsePreviewHotkey,
+  previewHotkeyFromKeyboardEvent,
+} from "./preview-hotkeys";
+export type { PreviewHotkeyMessage } from "./preview-hotkeys";
+
+function baseUrl(apiUrl: string) {
+  return apiUrl.replace(/\/$/, "");
+}
+
+/** First non-empty value from a Next.js `searchParams` field. */
+function queryValue(value: string | string[] | undefined): string | undefined {
+  const raw = Array.isArray(value) ? value[0] : value;
+  const trimmed = raw?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+/**
+ * Read `branch` and `tree` off the host preview URL so the snapshot and SSE
+ * match the editor checkout. Empty values mean branch HEAD (no live stream).
+ */
+export function previewCheckoutFromQuery(query: {
+  branch?: string | string[];
+  tree?: string | string[];
+}): Pick<PreviewDocRef, "branch" | "tree"> {
+  const branch = queryValue(query.branch);
+  const tree = queryValue(query.tree);
+  return {
+    ...(branch ? { branch } : {}),
+    ...(tree ? { tree } : {}),
+  };
+}
+
+export type DevMode = {
+  mode: "preview" | "live";
+  branch?: string;
+  tree?: string;
+};
+
+export function resolveDevMode(session: {
+  enabled: boolean;
+  branch?: string;
+  tree?: string;
+}): DevMode {
+  return {
+    mode: session.enabled ? "preview" : "live",
+    ...(session.branch ? { branch: session.branch } : {}),
+    ...(session.tree ? { tree: session.tree } : {}),
+  };
+}
+
+export async function fetchHostPreviewSession(
+  origin = "",
+): Promise<{ enabled: boolean; branch?: string; tree?: string }> {
+  try {
+    const res = await fetch(`${origin.replace(/\/$/, "")}/api/backmatter/preview?session=1`, {
+      credentials: "same-origin",
+      cache: "no-store",
+    });
+    if (!res.ok) return { enabled: false };
+    const data = (await res.json()) as {
+      mode?: string;
+      branch?: string;
+      tree?: string;
+    };
+    if (data.mode !== "preview") return { enabled: false };
+    return {
+      enabled: true,
+      ...(typeof data.branch === "string" && data.branch ? { branch: data.branch } : {}),
+      ...(typeof data.tree === "string" && data.tree ? { tree: data.tree } : {}),
+    };
+  } catch {
+    return { enabled: false };
+  }
+}
+
+export async function clearHostPreviewSession(origin = ""): Promise<boolean> {
+  try {
+    const res = await fetch(`${origin.replace(/\/$/, "")}/api/backmatter/preview`, {
+      method: "POST",
+      credentials: "same-origin",
+      cache: "no-store",
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export type CmsSessionUser = { id: string; email: string; name: string };
+
+/** Cookie session on the CMS API. Fail closed: empty URL, 401, errors → null. */
+export async function fetchCmsSession(
+  apiUrl: string,
+): Promise<CmsSessionUser | null> {
+  const base = baseUrl(apiUrl.trim());
+  if (!base) return null;
+  try {
+    const res = await fetch(`${base}/me`, {
+      credentials: "include",
+      cache: "no-store",
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { user?: CmsSessionUser };
+    if (!data.user?.id) return null;
+    return data.user;
+  } catch {
+    return null;
+  }
+}
+
+function previewParams(options: PreviewClientOptions, ref: PreviewDocRef) {
+  const params = new URLSearchParams({ token: options.previewToken });
+  if (ref.branch) params.set("branch", ref.branch);
+  if (ref.tree) params.set("tree", ref.tree);
+  return params;
+}
+
+function docPath(options: PreviewClientOptions, ref: PreviewDocRef) {
+  return `${baseUrl(options.apiUrl)}/preview/workspaces/${options.workspaceId}/docs/${ref.locale}/${ref.type}/${ref.slug}`;
+}
+
+export function previewDocRequestUrl(
+  options: PreviewClientOptions,
+  ref: PreviewDocRef,
+): string {
+  return `${docPath(options, ref)}?${previewParams(options, ref)}`;
+}
+
+export function previewStreamUrl(
+  options: PreviewClientOptions,
+  ref: PreviewDocRef,
+): string {
+  return `${docPath(options, ref)}/stream?${previewParams(options, ref)}`;
+}
+
+export async function fetchPreviewDoc(
+  options: PreviewClientOptions,
+  ref: PreviewDocRef,
+): Promise<BackmatterDoc | null> {
+  const url = previewDocRequestUrl(options, ref);
+  const res = await fetch(url, { cache: "no-store" });
+  if (res.status === 404) return null;
+  if (!res.ok) throw new Error(`preview getDoc failed: ${res.status}`);
+  const data = (await res.json()) as { doc: BackmatterDoc };
+  return data.doc;
+}
+
+/** Browser EventSource subscribe to one working tree's saves; returns unsubscribe. */
+export function subscribePreview(
+  options: PreviewClientOptions,
+  ref: PreviewDocRef,
+  onEvent: (event: PreviewChangeEvent) => void,
+): () => void {
+  if (typeof EventSource === "undefined") {
+    throw new Error("subscribePreview requires a browser EventSource");
+  }
+  const source = new EventSource(previewStreamUrl(options, ref));
+
+  const onChange = (ev: MessageEvent) => {
+    try {
+      const data = JSON.parse(String(ev.data)) as PreviewChangeEvent;
+      onEvent(data);
+    } catch {
+      // ignore malformed
+    }
+  };
+
+  source.addEventListener("change", onChange as EventListener);
+
+  return () => {
+    source.removeEventListener("change", onChange as EventListener);
+    source.close();
+  };
+}

package/src/query.ts

@@ -0,0 +1,152 @@
+// packages/core/src/query.ts
+import type { BackmatterDoc, BackmatterDocSummary } from "./doc";
+import type { FieldKind } from "./fields";
+import type { InferFrontmatter, ModelDef } from "./model";
+import { normalizeFrontmatter } from "./zod";
+
+/** Loader the query layer sits on: the FS or API loaders behind createBackmatter. */
+export type DocLoader = {
+  listDocs(filter?: { type?: string; locale?: string }): Promise<BackmatterDocSummary[]>;
+  getDoc(locale: string, type: string, slug: string): Promise<BackmatterDoc | null>;
+};
+
+export type TypedDoc<M extends ModelDef> = Omit<BackmatterDoc, "type" | "frontmatter"> & {
+  type: M["type"];
+  frontmatter: InferFrontmatter<M>;
+};
+
+type KeysOfKind<M extends ModelDef, K extends FieldKind> = {
+  [N in keyof M["fields"]]: M["fields"][N]["kind"] extends K ? N : never;
+}[keyof M["fields"]];
+
+type ScalarKind = "text" | "slug" | "locale" | "number" | "boolean";
+
+/** Equality filters on slug and scalar frontmatter fields. */
+export type Where<M extends ModelDef> = Partial<
+  { slug: string } & Pick<
+    InferFrontmatter<M>,
+    Extract<KeysOfKind<M, ScalarKind>, keyof InferFrontmatter<M>>
+  >
+>;
+
+/** Relation fields that may be resolved (depth 1, same locale). */
+export type Include<M extends ModelDef> = Partial<Record<KeysOfKind<M, "relation">, true>>;
+
+type RelationTarget<
+  M extends ModelDef,
+  N extends keyof M["fields"],
+  Models extends readonly ModelDef[],
+> = M["fields"][N] extends { relationTo?: infer To }
+  ? Extract<Models[number], { type: Exclude<To, undefined> }>
+  : never;
+
+export type Resolved<
+  M extends ModelDef,
+  Models extends readonly ModelDef[],
+  I extends Include<M>,
+> = {
+  [N in keyof I as I[N] extends true ? N : never]: N extends keyof M["fields"]
+    ? TypedDoc<RelationTarget<M, N, Models>> | null
+    : never;
+};
+
+export type ModelQuery<M extends ModelDef, Models extends readonly ModelDef[]> = {
+  get(locale: string, slug: string): Promise<TypedDoc<M> | null>;
+  findMany<I extends Include<M> = {}>(opts?: {
+    locale?: string;
+    where?: Where<M>;
+    include?: I;
+  }): Promise<Array<TypedDoc<M> & Resolved<M, Models, I>>>;
+};
+
+export type Query<Models extends readonly ModelDef[]> = {
+  [M in Models[number] as M["type"]]: ModelQuery<M, Models>;
+};
+
+type RawOpts = {
+  locale?: string;
+  where?: Record<string, unknown>;
+  include?: Record<string, boolean | undefined>;
+};
+
+export function createQuery<const Models extends readonly ModelDef[]>(
+  models: Models,
+  loader: DocLoader,
+): Query<Models> {
+  const byType = new Map<string, ModelDef>(models.map((m) => [m.type, m]));
+
+  async function get(type: string, locale: string, slug: string): Promise<BackmatterDoc | null> {
+    const doc = await loader.getDoc(locale, type, slug);
+    if (!doc) return null;
+    return { ...doc, frontmatter: normalizeFrontmatter(doc.frontmatter) };
+  }
+
+  function matchesWhere(doc: BackmatterDoc, where: Record<string, unknown>): boolean {
+    for (const [key, expected] of Object.entries(where)) {
+      if (expected === undefined) continue;
+      const actual = key === "slug" ? doc.slug : doc.frontmatter[key];
+      if (actual !== expected) return false;
+    }
+    return true;
+  }
+
+  async function findMany(type: string, opts?: RawOpts): Promise<BackmatterDoc[]> {
+    const model = byType.get(type);
+    const whereSlug = opts?.where?.slug;
+
+    let docs: BackmatterDoc[];
+    // Truthy gate: the loaders' locale filter is truthiness-based, so a falsy
+    // locale ("") must fall back to the list path like an omitted one.
+    if (typeof whereSlug === "string" && opts?.locale) {
+      // Slug fast-path: identity lookup instead of list + load fan-out.
+      const doc = await get(type, opts.locale, whereSlug);
+      docs = doc ? [doc] : [];
+    } else {
+      const summaries = await loader.listDocs({ type, locale: opts?.locale });
+      const loaded = await Promise.all(summaries.map((s) => get(type, s.locale, s.slug)));
+      docs = loaded.filter((d): d is BackmatterDoc => d !== null);
+    }
+
+    const filtered = opts?.where ? docs.filter((d) => matchesWhere(d, opts.where!)) : docs;
+    const include = opts?.include;
+    if (!include || !model) return filtered;
+
+    // Memoize relation loads per call: N posts sharing one author load it once.
+    const relationCache = new Map<string, Promise<BackmatterDoc | null>>();
+    const getCached = (target: string, locale: string, slug: string) => {
+      const key = `${target}:${locale}:${slug}`;
+      let promise = relationCache.get(key);
+      if (!promise) {
+        promise = get(target, locale, slug);
+        relationCache.set(key, promise);
+      }
+      return promise;
+    };
+
+    return Promise.all(
+      filtered.map(async (doc) => {
+        const extra: Record<string, BackmatterDoc | null> = {};
+        for (const [name, on] of Object.entries(include)) {
+          if (!on) continue;
+          const field = model.fields[name];
+          const target = field?.kind === "relation" ? field.relationTo : undefined;
+          const slug = doc.frontmatter[name];
+          extra[name] =
+            target && typeof slug === "string" && slug.length > 0
+              ? await getCached(target, doc.locale, slug)
+              : null;
+        }
+        return { ...doc, ...extra };
+      }),
+    );
+  }
+
+  const query: Record<string, unknown> = {};
+  for (const m of models) {
+    query[m.type] = {
+      get: (locale: string, slug: string) => get(m.type, locale, slug),
+      findMany: (opts?: RawOpts) => findMany(m.type, opts),
+    };
+  }
+  return query as Query<Models>;
+}

package/src/routes.ts

@@ -0,0 +1,110 @@
+// packages/core/src/routes.ts
+// Pure URL ↔ document mapping for the host catch-all route. No framework code.
+import type { ModelSnapshot } from "./model";
+
+export const DEFAULT_ROUTE = "/{locale}/{type}/{slug}";
+
+export type RouteModel = Pick<ModelSnapshot, "type" | "route" | "indexSlug">;
+
+export type RouteMatch = {
+  type: string;
+  locale: string;
+  slug: string;
+};
+
+export type MatchRouteOptions = {
+  /** Locale for routes without a `{locale}` placeholder. */
+  defaultLocale: string;
+  /** When set, `{locale}` only matches one of these values. */
+  locales?: readonly string[];
+};
+
+/** The model's route template with `{type}` already substituted. */
+export function routeTemplate(model: RouteModel): string {
+  return (model.route ?? DEFAULT_ROUTE).replaceAll("{type}", model.type);
+}
+
+/** Build the public URL path for a document, e.g. "/en/blog/hello". */
+export function routeFor(model: RouteModel, locale: string, slug: string): string {
+  if (model.indexSlug && slug === model.indexSlug) return "/";
+  return routeTemplate(model)
+    .replaceAll("{locale}", encodeURIComponent(locale))
+    .replaceAll("{slug}", slug.split("/").map(encodeURIComponent).join("/"));
+}
+
+/** URL segments for Next `generateStaticParams` (["en", "blog", "hello"]). */
+export function routeSegments(model: RouteModel, locale: string, slug: string): string[] {
+  return routeFor(model, locale, slug)
+    .split("/")
+    .filter(Boolean)
+    .map(decodeURIComponent);
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function compileRoutePattern(template: string): RegExp {
+  const parts = template.split(/(\{locale\}|\{slug\})/g);
+  let pattern = "^";
+  for (const part of parts) {
+    if (part === "{locale}") pattern += "(?<locale>[^/]+)";
+    else if (part === "{slug}") pattern += "(?<slug>[^/]+)";
+    else pattern += escapeRegex(part);
+  }
+  return new RegExp(`${pattern}/?$`);
+}
+
+function specificity(template: string): [staticSegments: number, placeholders: number] {
+  const segments = template.split("/").filter(Boolean);
+  const placeholders = segments.filter((s) => s.includes("{")).length;
+  return [segments.length - placeholders, placeholders];
+}
+
+/** Most static segments first, then fewer placeholders, then declaration order. */
+export function sortByRouteSpecificity<M extends RouteModel>(models: readonly M[]): M[] {
+  return models
+    .map((model, index) => ({ model, index, spec: specificity(routeTemplate(model)) }))
+    .sort((a, b) => {
+      if (a.spec[0] !== b.spec[0]) return b.spec[0] - a.spec[0];
+      if (a.spec[1] !== b.spec[1]) return a.spec[1] - b.spec[1];
+      return a.index - b.index;
+    })
+    .map((entry) => entry.model);
+}
+
+export function normalizePathname(pathname: string): string {
+  let out = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  if (out.length > 1) out = out.replace(/\/+$/, "");
+  return out;
+}
+
+/** Resolve a URL path to a document identity, or null when no model claims it. */
+export function matchRoute(
+  models: readonly RouteModel[],
+  pathname: string,
+  options: MatchRouteOptions,
+): RouteMatch | null {
+  const target = normalizePathname(pathname);
+  if (target === "/") {
+    const index = models.find((model) => model.indexSlug);
+    if (index?.indexSlug) {
+      return { type: index.type, locale: options.defaultLocale, slug: index.indexSlug };
+    }
+    return null;
+  }
+  for (const model of sortByRouteSpecificity(models)) {
+    const template = routeTemplate(model);
+    const m = compileRoutePattern(template).exec(target);
+    if (!m?.groups?.slug) continue;
+    let locale = options.defaultLocale;
+    if (template.includes("{locale}")) {
+      const raw = m.groups.locale;
+      if (!raw) continue;
+      locale = decodeURIComponent(raw);
+      if (options.locales && !options.locales.includes(locale)) continue;
+    }
+    return { type: model.type, locale, slug: decodeURIComponent(m.groups.slug) };
+  }
+  return null;
+}

package/src/signed-token.ts

@@ -0,0 +1,63 @@
+// packages/core/src/signed-token.ts
+// HMAC-SHA256 tokens for Edge + Node (Web Crypto). Payload is JSON.
+
+function bytesToB64Url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function b64UrlToBytes(value: string): Uint8Array | null {
+  try {
+    const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = padded.length % 4 === 0 ? "" : "=".repeat(4 - (padded.length % 4));
+    const bin = atob(padded + pad);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+async function hmacSha256(secret: string, message: string): Promise<Uint8Array> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));
+  return new Uint8Array(sig);
+}
+
+function timingEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i]! ^ b[i]!;
+  return diff === 0;
+}
+
+export async function signPayload(secret: string, payload: unknown): Promise<string> {
+  const body = bytesToB64Url(new TextEncoder().encode(JSON.stringify(payload)));
+  const sig = bytesToB64Url(await hmacSha256(secret, body));
+  return `${body}.${sig}`;
+}
+
+export async function verifyPayload(secret: string, token: string): Promise<unknown | null> {
+  const dot = token.lastIndexOf(".");
+  if (dot <= 0) return null;
+  const body = token.slice(0, dot);
+  const sig = b64UrlToBytes(token.slice(dot + 1));
+  if (!sig) return null;
+  const expected = await hmacSha256(secret, body);
+  if (!timingEqual(sig, expected)) return null;
+  const json = b64UrlToBytes(body);
+  if (!json) return null;
+  try {
+    return JSON.parse(new TextDecoder().decode(json));
+  } catch {
+    return null;
+  }
+}