@drawnagency/primitives 0.1.98 → 0.1.100

package/src/lib/platform-broker.ts

@@ -7,6 +7,21 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * A broker call that reached apps/admin and got a non-2xx back. The `status` is
+ * carried so callers can distinguish a MISSING endpoint (404/405/501 — the
+ * stale-admin window, where the client site has been upgraded ahead of the
+ * platform) from a real auth or config failure. Without it every such case
+ * surfaces as an opaque 500 the editor cannot act on. `status` is null when the
+ * request never got a response at all.
+ */
+export class PlatformBrokerError extends Error {
+  constructor(public readonly status: number | null, message: string) {
+    super(message);
+    this.name = "PlatformBrokerError";
+  }
+}
+
 /** True when this runtime should broker privileged ops through the platform. */
 export function isPlatformMode(): boolean {
   return Boolean(env("PLATFORM_API_URL") && env("PLATFORM_API_KEY"));
@@ -60,15 +75,15 @@ export async function platformBroker<T = unknown>(
     }
 
     if (res.status >= 500 && !isLast) {
-      lastError = new Error(`Platform broker error (${res.status})`);
+      lastError = new PlatformBrokerError(res.status, `Platform broker error (${res.status})`);
       await sleep(RETRY_BASE_MS * 2 ** attempt);
       continue;
     }
 
-    throw new Error(`Platform broker error (${res.status}): ${await res.text()}`);
+    throw new PlatformBrokerError(res.status, `Platform broker error (${res.status}): ${await res.text()}`);
   }
 
-  throw lastError instanceof Error ? lastError : new Error("Platform broker unreachable");
+  throw lastError instanceof Error ? lastError : new PlatformBrokerError(null, "Platform broker unreachable");
 }
 
 /**

package/src/lib/registry.ts

@@ -62,6 +62,15 @@ export type SettingsFieldDef =
       label: string;
       default: VideoSource;
       target?: "content" | "options";
+    }
+  | {
+      /** Opens the media library filtered to documents (PDF/HTML). The renderer
+       *  lives in SettingsForm; an unrendered kind falls through its `default`
+       *  arm, so this type can land ahead of the field component. */
+      type: "document-source";
+      label: string;
+      default: { documentId: string };
+      target?: "content" | "options";
     };
 
 export type SettingsSchema = Record<string, SettingsFieldDef>;

package/src/lib/save-chunks.ts

@@ -51,3 +51,45 @@ export function packUploads(uploads: MediaUploadPayload[], budget = SAVE_CHUNK_B
   if (current.length > 0) chunks.push(current);
   return { chunks, oversized };
 }
+
+export interface DocumentUploadPayload {
+  id: string;
+  path: string;
+  base64: string;
+}
+
+/** Approximate serialized size of one document upload — base64 dominates; the
+ *  allowance covers JSON keys, quoting, and the manifest entry riding along. */
+export function documentUploadSizeBytes(upload: DocumentUploadPayload): number {
+  return upload.base64.length + upload.path.length + 576;
+}
+
+/** Greedy in-order packing of document uploads. A 2.5MiB document base64s to
+ *  ~3.4MB, so two never share a request — hence chunking rather than one blob
+ *  request. Documents are never packed with sections/index. */
+export function packDocumentUploads(
+  uploads: DocumentUploadPayload[],
+  budget = SAVE_CHUNK_BUDGET_BYTES,
+): { chunks: DocumentUploadPayload[][]; oversized: DocumentUploadPayload[] } {
+  const chunks: DocumentUploadPayload[][] = [];
+  const oversized: DocumentUploadPayload[] = [];
+  let current: DocumentUploadPayload[] = [];
+  let currentBytes = 0;
+
+  for (const upload of uploads) {
+    const size = documentUploadSizeBytes(upload);
+    if (size > budget) {
+      oversized.push(upload);
+      continue;
+    }
+    if (current.length > 0 && currentBytes + size > budget) {
+      chunks.push(current);
+      current = [];
+      currentBytes = 0;
+    }
+    current.push(upload);
+    currentBytes += size;
+  }
+  if (current.length > 0) chunks.push(current);
+  return { chunks, oversized };
+}

package/src/lib/scroll-lock.ts

@@ -0,0 +1,27 @@
+/**
+ * Refcounted body-scroll lock.
+ *
+ * EditorModal and ChatPanel each save/restore `body.style.overflow` themselves,
+ * which collides when two lockers overlap — the first to release restores
+ * "hidden" as if it were the resting value, or unlocks the page under a still-
+ * open surface. The doc overlay and the mobile chat sheet CAN be open at the
+ * same time, so this one counts.
+ */
+let depth = 0;
+let previousOverflow = "";
+
+export function lockBodyScroll(): () => void {
+  if (typeof document === "undefined") return () => {};
+  if (depth === 0) {
+    previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+  }
+  depth++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    depth--;
+    if (depth === 0) document.body.style.overflow = previousOverflow;
+  };
+}

package/src/schemas/documents.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+
+/**
+ * Document metadata lives in its OWN file, not in image-manifest.json.
+ *
+ * The image manifest is hard-`.parse`d on every page load across five routes,
+ * its remote-merge guard fails open on parse failure, and the authoring CLI
+ * parse-catch-WRITES it — so one entry a stale package version cannot
+ * represent means whole-site 500s or a wiped manifest. A sidecar is simply
+ * absent from an older writer's file list and survives untouched. Same
+ * structural answer as nav.json; do not "simplify" this back into either
+ * index.json or image-manifest.json.
+ */
+export const DOCUMENT_MANIFEST_PATH = "src/content/document-manifest.json";
+
+/**
+ * Git-tier cap. 2.5 MiB base64-encodes to ~3.4 MB, inside the 4 MB post-base64
+ * chunk budget with envelope headroom.
+ */
+export const DOCUMENT_GIT_MAX_BYTES = 2_621_440;
+
+/** Bucket-tier cap. Its lower bound is DOCUMENT_GIT_MAX_BYTES — no dead zone. */
+export const DOCUMENT_BUCKET_MAX_BYTES = 209_715_200;
+
+/**
+ * The only two accepted upload types, and the ONLY source of a document's file
+ * extension — never the media pipeline's `?? "bin"` fallback.
+ */
+export const DOCUMENT_MIME_TO_EXT = {
+  "application/pdf": "pdf",
+  "text/html": "html",
+} as const;
+
+/** Reverse of DOCUMENT_MIME_TO_EXT, for setting Content-Type when serving. */
+export const DOCUMENT_KIND_TO_MIME = {
+  pdf: "application/pdf",
+  html: "text/html",
+} as const;
+
+export const DocumentManifestEntrySchema = z.object({
+  filename: z.string(),
+  size: z.number().int().positive(),
+  kind: z.enum(["pdf", "html"]),
+  storage: z.enum(["git", "bucket"]),
+  /** git: repo path under assets/documents/…; bucket: site-relative object key. */
+  path: z.string(),
+});
+
+export const DocumentManifestSchema = z.record(z.string(), DocumentManifestEntrySchema);
+
+export type DocumentManifest = z.infer<typeof DocumentManifestSchema>;
+export type DocumentManifestEntry = z.infer<typeof DocumentManifestEntrySchema>;
+
+/**
+ * The gated URL for a document, at BOTH storage tiers. Single-sourced here so
+ * the section row, the overlay, the nav group and the tests cannot drift — a
+ * bucket-tier document is still fetched through this route, which authorizes
+ * the requester and only then 302s to a short-lived presigned GET.
+ */
+export function documentFileUrl(
+  documentId: string,
+  filename: string,
+  opts: { download?: boolean } = {},
+): string {
+  const base = `/api/document-file/${documentId}/${encodeURIComponent(filename)}`;
+  return opts.download ? `${base}?download=1` : base;
+}
+
+/** Git-tier repo path. `slugName` comes from sanitizeMediaName(file.name). */
+export function documentGitPath(slugName: string, hash: string, kind: "pdf" | "html"): string {
+  return `assets/documents/${slugName}-${hash}/original.${kind}`;
+}
+
+/**
+ * Bucket-tier object key, SITE-RELATIVE — the store prepends the tenant prefix,
+ * so this is also the form stored in the manifest, matched by the delete
+ * broker's regex, and compared by the publish-time GC. The id is the 32-hex
+ * `documentId` minted by upload-intent, never the client's content hash.
+ */
+export function documentBucketPath(documentId: string, kind: "pdf" | "html"): string {
+  return `documents/${documentId}/original.${kind}`;
+}

package/src/schemas/index.ts

@@ -7,3 +7,4 @@ export * from "./audience";
 export * from "./media-grid-options";
 export * from "./auth";
 export * from "./link";
+export * from "./documents";

package/src/schemas/nav.ts

@@ -19,9 +19,9 @@ export const NavEntrySchema = z.discriminatedUnion("kind", [
     /** May be blank — agent-authored files can omit it; UI falls back to "Untitled group". */
     label: z.string().default(""),
     startCollapsed: z.boolean().default(false),
-    // Everything but `id` defaults: NavFileSchema is all-or-nothing, and the
-    // loader degrades a failed parse to a flat nav — so one agent-authored group
-    // missing a key would silently discard every group on the site.
+    // Everything but `id` defaults: the loader parses entries individually and
+    // drops the ones that fail — defaulting here keeps an agent-authored group
+    // missing a key from being dropped (and its drop marking the nav degraded).
     pageIds: z.array(z.string().min(1)).default([]),
   }),
 ]);

package/src/storage/index.ts

@@ -1,2 +1,2 @@
-export type { StorageProvider, FileWrite, AssetStore } from "./types";
-export { StorageConflictError, ASSET_CACHE_CONTROL, IDEMPOTENCY_TRAILER, IDEMPOTENCY_KEY_RE, withIdempotencyTrailer } from "./types";
+export type { StorageProvider, FileWrite, AssetStore, DocumentStore } from "./types";
+export { StorageConflictError, IdempotencyLookupUnavailableError, ASSET_CACHE_CONTROL, DOCUMENT_CACHE_CONTROL, IDEMPOTENCY_TRAILER, IDEMPOTENCY_KEY_RE, withIdempotencyTrailer } from "./types";

package/src/storage/types.ts

@@ -46,11 +46,18 @@ export interface StorageProvider {
    * OPTIONAL: providers that cannot search history omit it, and callers fall
    * back to surfacing the plain conflict.
    *
-   * Best-effort by contract. It searches a BOUNDED window, so an old key reads
-   * as absent, and an implementation may answer "not found" when the history
-   * read itself fails — failing closed keeps the conflict rather than inventing
-   * a replay. So `null` means "could not confirm", NOT "your write did not
-   * land": a caller must not tell the user the earlier attempt failed.
+   * `null` means "searched, and this key is not in the window" — which still is
+   * NOT proof the write did not land, because the window is BOUNDED and an old
+   * key reads as absent. A caller must not tell the user the earlier attempt
+   * failed.
+   *
+   * A failure of the history read itself MUST throw
+   * {@link IdempotencyLookupUnavailableError} rather than answer `null`. The two
+   * are not interchangeable: a caller deciding whether it is safe to APPLY a
+   * write reads `null` as "nothing landed, go ahead", so collapsing a failed
+   * read into it turns at-most-once into at-least-once. Callers that are merely
+   * REPORTING on a key (or choosing between replay and conflict) can catch it
+   * and fall back to the pessimistic answer.
    */
   findCommitByIdempotencyKey?(
     key: string,
@@ -58,6 +65,19 @@ export interface StorageProvider {
   ): Promise<string | null>;
 }
 
+/**
+ * The idempotency history read failed, so whether the key landed is UNKNOWN.
+ *
+ * Distinct from a `null` answer, which means the provider successfully searched
+ * and did not find it. See {@link StorageProvider.findCommitByIdempotencyKey}.
+ */
+export class IdempotencyLookupUnavailableError extends Error {
+  constructor(override readonly cause?: unknown) {
+    super("Could not search draft history for the idempotency key");
+    this.name = "IdempotencyLookupUnavailableError";
+  }
+}
+
 /**
  * Commit-message trailer carrying a write's idempotency key. The commit itself is
  * the store — no table, and no TTL to tune: keys live exactly as long as the
@@ -131,3 +151,49 @@ export interface AssetStore {
   /** Recursive listing under a site-relative prefix. */
   list(prefix: string): Promise<{ path: string; size: number; updatedAt: string }[]>;
 }
+
+/**
+ * `Cache-Control` every DOCUMENT upload must set. Deliberately NOT
+ * ASSET_CACHE_CONTROL: documents live in a PRIVATE bucket reachable only
+ * through short-lived presigned GETs, and a shared cache keyed on the full
+ * signed URL would otherwise retain the bytes for a year after the signature
+ * expired. `private` keeps the copy in the requesting browser only.
+ */
+export const DOCUMENT_CACHE_CONTROL = "private, max-age=31536000, immutable";
+
+/**
+ * Optional PRIVATE document store — a second bucket with no public domain.
+ *
+ * Deliberately not an AssetStore: the assets bucket is public by configuration
+ * at R2_PUBLIC_BASE (videos depend on it), so a signed GET there would protect
+ * nothing and hosted HTML would render unsandboxed on a sibling origin. Hence
+ * no `getPublicUrl` here at all — every read is a short-lived signed GET,
+ * minted only after the gated route has authorized the requester.
+ *
+ * Paths are SITE-RELATIVE ("documents/{hash}/original.pdf"); implementations
+ * prepend the tenant prefix themselves so a caller can never address another
+ * tenant's objects.
+ */
+export interface DocumentStore {
+  /** Mint a signed direct-upload URL for the browser (PUT). */
+  createUploadUrl(
+    path: string,
+    opts: { contentType: string },
+  ): Promise<{ uploadUrl: string; path: string }>;
+
+  /**
+   * Mint a short-lived signed GET. `downloadFilename`, when given, signs
+   * `response-content-disposition: attachment` into the URL — R2 sends no
+   * Content-Disposition of its own, so this is the only way ?download=1 can
+   * force a download on the bucket tier.
+   */
+  createDownloadUrl(
+    path: string,
+    opts: { expiresInSeconds: number; downloadFilename?: string },
+  ): Promise<string>;
+
+  delete(paths: string[]): Promise<void>;
+
+  /** Recursive listing under a site-relative prefix. */
+  list(prefix: string): Promise<Array<{ path: string; size: number; updatedAt: string }>>;
+}

package/src/types/database.ts

@@ -759,6 +759,20 @@ export type Database = {
           retry_after_ms: number
         }[]
       }
+      oauth_rotate_refresh_token: {
+        Args: {
+          p_expected_client_id: string
+          p_next_expires_at: string
+          p_next_token_hash: string
+          p_token_hash: string
+        }
+        Returns: {
+          status: string
+          family_id: string | null
+          client_id: string | null
+          platform_user_id: string | null
+        }[]
+      }
       provision_claim: { Args: { p_site_id: string }; Returns: boolean }
       rate_limit_cleanup: { Args: { p_max_age_ms: number }; Returns: undefined }
       rate_limit_hit: {