@backmatter/core 0.0.18 → 0.0.20

package/src/preview-session.ts

@@ -2,11 +2,15 @@
 import { signPayload, verifyPayload } from "./signed-token";
 
 export const PREVIEW_COOKIE = "backmatter_preview";
+export const PREVIEW_SESSION_COOKIE = "backmatter_preview_session";
+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";
 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 const PREVIEW_SESSION_TTL_MS = 12 * 60 * 60 * 1000;
 
 export type PreviewCheckout = {
   branch?: string;
@@ -19,6 +23,21 @@ export type PreviewTicket = {
   redirect: string;
   branch?: string;
   tree?: string;
+  /** Preview session token. The host stores it and drops it from the URL. */
+  session?: string;
+  exp: number;
+};
+
+/** One user, one workspace, one branch, one working tree. */
+export type PreviewSessionClaims = {
+  v: 1;
+  kind: "preview-session";
+  userId: string;
+  workspaceId: string;
+  branch: string;
+  tree: string;
+  role: string;
+  epoch: number;
   exp: number;
 };
 
@@ -42,6 +61,7 @@ export async function mintPreviewTicket(
     redirect: string;
     branch?: string;
     tree?: string;
+    session?: string;
     exp: number;
   },
 ): Promise<string> {
@@ -55,10 +75,25 @@ export async function mintPreviewTicket(
     exp: input.exp,
     ...(input.branch ? { branch: input.branch } : {}),
     ...(input.tree ? { tree: input.tree } : {}),
+    ...(input.session ? { session: input.session } : {}),
   };
   return signPayload(secret, payload);
 }
 
+export async function mintPreviewSession(
+  secret: string,
+  input: Omit<PreviewSessionClaims, "v" | "kind">,
+): Promise<string> {
+  if (input.tree !== input.userId) {
+    throw new Error("preview session tree must be the user");
+  }
+  if (!input.branch || !input.workspaceId || !input.userId) {
+    throw new Error("preview session is missing scope");
+  }
+  const payload: PreviewSessionClaims = { v: 1, kind: "preview-session", ...input };
+  return signPayload(secret, payload);
+}
+
 function asTicket(value: unknown): PreviewTicket | null {
   if (!value || typeof value !== "object") return null;
   const v = value as Record<string, unknown>;
@@ -74,13 +109,85 @@ function asTicket(value: unknown): PreviewTicket | null {
     exp: v.exp,
     ...(typeof v.branch === "string" && v.branch ? { branch: v.branch } : {}),
     ...(typeof v.tree === "string" && v.tree ? { tree: v.tree } : {}),
+    ...(typeof v.session === "string" && v.session ? { session: v.session } : {}),
+  };
+}
+
+function asSession(value: unknown): PreviewSessionClaims | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (v.v !== 1 || v.kind !== "preview-session") return null;
+  if (typeof v.userId !== "string" || typeof v.workspaceId !== "string") return null;
+  if (typeof v.branch !== "string" || typeof v.tree !== "string" || typeof v.role !== "string") {
+    return null;
+  }
+  if (v.tree !== v.userId) return null;
+  if (typeof v.epoch !== "number" || typeof v.exp !== "number" || v.exp <= Date.now()) return null;
+  return {
+    v: 1,
+    kind: "preview-session",
+    userId: v.userId,
+    workspaceId: v.workspaceId,
+    branch: v.branch,
+    tree: v.tree,
+    role: v.role,
+    epoch: v.epoch,
+    exp: v.exp,
   };
 }
 
+/** Workspace id from an unverified body, so the server can load the signing secret. */
+export function peekPreviewSessionWorkspace(token: string): string | null {
+  const dot = token.lastIndexOf(".");
+  if (dot <= 0) return null;
+  try {
+    const padded = token.slice(0, dot).replace(/-/g, "+").replace(/_/g, "/");
+    const pad = padded.length % 4 === 0 ? "" : "=".repeat(4 - (padded.length % 4));
+    const json = JSON.parse(atob(padded + pad)) as Record<string, unknown>;
+    return json.kind === "preview-session" && typeof json.workspaceId === "string"
+      ? json.workspaceId
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 export async function readPreviewTicket(secret: string, token: string): Promise<PreviewTicket | null> {
   return asTicket(await verifyPayload(secret, token));
 }
 
+export async function readPreviewSession(
+  secret: string,
+  token: string | undefined,
+): Promise<PreviewSessionClaims | null> {
+  if (!token) return null;
+  return asSession(await verifyPayload(secret, token));
+}
+
+/**
+ * A session token may read and write only its own tree. A workspace preview
+ * token keeps the caller's query.
+ */
+export function scopePreviewAccess(
+  auth: { mode: "workspace" } | { mode: "session"; branch: string; tree: string },
+  query: { branch: string; tree: string | null },
+): { branch: string; tree: string | null } | null {
+  if (auth.mode === "workspace") return query;
+  if (query.tree && query.tree !== auth.tree) return null;
+  if (query.branch && query.branch !== auth.branch) return null;
+  return { branch: auth.branch, tree: auth.tree };
+}
+
+/** Pull a session token out of the URL. The returned search no longer contains it. */
+export function takePreviewSessionFromSearch(search: string): { token: string | null; search: string } {
+  const params = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search);
+  const token = params.get(PREVIEW_SESSION_QUERY)?.trim() || null;
+  if (!token) return { token: null, search };
+  params.delete(PREVIEW_SESSION_QUERY);
+  const next = params.toString();
+  return { token, search: next ? `?${next}` : "" };
+}
+
 export function previewLocationWithCheckout(
   origin: string,
   redirect: string,

package/src/preview.ts

@@ -1,5 +1,5 @@
 // packages/core/src/preview.ts
-import type { BackmatterDoc } from "./doc";
+import type { BackmatterDoc, BackmatterDocSummary } from "./doc";
 
 export type PreviewDocRef = {
   locale: string;
@@ -164,6 +164,14 @@ export function previewStreamUrl(
   return `${docPath(options, ref)}/stream?${previewParams(options, ref)}`;
 }
 
+/** Tree-wide stream: added, modified, removed, and HEAD moves for one checkout. */
+export function previewTreeStreamUrl(
+  options: PreviewClientOptions,
+  checkout: { branch?: string; tree?: string },
+): string {
+  return `${baseUrl(options.apiUrl)}/preview/workspaces/${options.workspaceId}/tree/stream?${previewParams(options, { locale: "", type: "", slug: "", ...checkout })}`;
+}
+
 export async function fetchPreviewDoc(
   options: PreviewClientOptions,
   ref: PreviewDocRef,
@@ -176,6 +184,38 @@ export async function fetchPreviewDoc(
   return data.doc;
 }
 
+/**
+ * HEAD overlaid with the checkout's working tree. Follows cursors so a list
+ * page sees every document of the type, not just the first page.
+ */
+export async function fetchPreviewDocs(
+  options: PreviewClientOptions,
+  query: { branch?: string; tree?: string; type?: string; locale?: string },
+): Promise<BackmatterDocSummary[]> {
+  const docs: BackmatterDocSummary[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < 100; page++) {
+    const params = previewParams(options, {
+      locale: query.locale ?? "",
+      type: "",
+      slug: "",
+      branch: query.branch,
+      tree: query.tree,
+    });
+    if (query.type) params.set("type", query.type);
+    if (query.locale) params.set("locale", query.locale);
+    if (cursor) params.set("cursor", cursor);
+    const url = `${baseUrl(options.apiUrl)}/preview/workspaces/${options.workspaceId}/docs?${params}`;
+    const res = await fetch(url, { cache: "no-store" });
+    if (!res.ok) throw new Error(`preview listDocs failed: ${res.status}`);
+    const data = (await res.json()) as { docs: BackmatterDocSummary[]; nextCursor: string | null };
+    docs.push(...data.docs);
+    if (!data.nextCursor) break;
+    cursor = data.nextCursor;
+  }
+  return docs;
+}
+
 /** Browser EventSource subscribe to one working tree's saves; returns unsubscribe. */
 export function subscribePreview(
   options: PreviewClientOptions,
@@ -203,3 +243,38 @@ export function subscribePreview(
     source.close();
   };
 }
+
+export {
+  createLocalPreviewTransport,
+  createPostMessageTransport,
+  createWindowPreviewTransport,
+  isAllowedPreviewOrigin,
+  normalizePreviewOrigin,
+  parsePreviewMessage,
+  PREVIEW_CHANNEL_VERSION,
+  samePreviewRef,
+} from "./preview-channel";
+export type {
+  PostMessageTransportOptions,
+  PreviewChannelMessage,
+  PreviewChannelRef,
+  PreviewDocMessage,
+  PreviewHelloMessage,
+  PreviewMessageEvent,
+  PreviewNavigateMessage,
+  PreviewRemovedMessage,
+  PreviewStatusMessage,
+  PreviewTransport,
+  PreviewWindowLike,
+} from "./preview-channel";
+export { createPreviewEditor, createPreviewPage } from "./preview-client";
+export type {
+  PreviewEditorSession,
+  PreviewPageHandlers,
+  PreviewPageSession,
+  PreviewRenderDoc,
+  PreviewRenderResult,
+  PreviewRenderer,
+  PreviewSchedule,
+  PreviewSseEvent,
+} from "./preview-client";

package/src/source.ts

@@ -0,0 +1,24 @@
+// packages/core/src/source.ts
+// A source resolves the outside record behind an `external` model's route.
+// Host code only (`sources/{type}.ts`); never serialized into the schema.
+
+export type SourceRef = { locale: string; slug: string };
+
+export type SourceDef<T = unknown> = {
+  /** The outside record for a route hit. `null` means the record does not exist (404). */
+  load: (ref: SourceRef) => Promise<T | null>;
+  /** Slugs to prerender, per locale. Omit to prerender only slugs that have a CMS file. */
+  list?: (locale: string) => Promise<readonly string[]>;
+  /** One representative record for template preview. Omit to preview the template with `data: null`. */
+  sample?: (locale: string) => Promise<T | null>;
+  /** Metadata when the document has no `title`. */
+  metadata?: (record: T) => { title?: string };
+};
+
+/** Identity helper that validates the definition and keeps the record type. */
+export function defineSource<T>(def: SourceDef<T>): SourceDef<T> {
+  if (!def || typeof def !== "object" || typeof def.load !== "function") {
+    throw new Error("source.load is required and must be a function");
+  }
+  return def;
+}