@graph8/sdk 0.370.0 → 0.374.0

package/blocks/programmatic-pages/components/programmatic-source.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+/**
+ * ProgrammaticSource: the rows the pages are made from: what the source is, its columns and first rows, switching it, and
+ * importing a sitemap as the source.
+ *
+ * SDK operations, in order:
+ *   1. getProgrammaticWorkspace (GET /programmatic-campaigns/{id}/workspace)               read    source, columns, sample rows, row count
+ *   2. updateProgrammaticWorkspace (PATCH /programmatic-campaigns/{id}/workspace)          write   switch to another list or table (works at any status)
+ *   3. importProgrammaticSitemap (POST /programmatic-campaigns/{id}/imports/sitemap)       write   REPLACES the source with a table of the sitemap's URLs
+ * A source change marks the pages as changed; render again to apply it. The sitemap import fetches the sitemap (and, if asked,
+ * each page) from the public web; the maximum is left to the API's default unless a number is typed.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyValue, KeyValueList } from "@/g8/components/screen/key-value-list";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import { text } from "@/g8/pages/lib/studio";
+import { useProgrammaticWorkspace } from "../hooks/use-programmatic-workspace";
+import { SOURCE_TYPES, sourceComplete, sourceOf } from "../lib/programmatic-types";
+import type { Campaign, SourceType } from "../lib/programmatic-types";
+import { ProgrammaticSourceFields } from "./programmatic-source-fields";
+import type { SourceValue } from "./programmatic-source-fields";
+
+export interface ProgrammaticSourceProps {
+  campaign: Campaign;
+}
+
+export function ProgrammaticSource({ campaign }: ProgrammaticSourceProps) {
+  const ws = useProgrammaticWorkspace(campaign.id);
+  if (ws.error && !ws.data) return <ApiError error={ws.error} title="Could not load the source" onRetry={() => void ws.refetch()} />;
+  if (!ws.data) return <Skeleton className="h-32 w-full" aria-busy="true" />;
+  const src = sourceOf({ data_source: ws.data.data?.source, data_source_type: campaign.data_source_type, list_id: campaign.list_id });
+  const cols = (ws.data.data?.columns ?? []).slice(0, 6);
+  const rows = ws.data.data?.sample_rows ?? [];
+  const total = ws.data.data?.total_rows ?? null;
+  return (
+    <div className="grid gap-4">
+      <KeyValueList columns={2} items={[
+        { label: "Source", value: SOURCE_TYPES.find((t) => t.value === src.type)?.label ?? null },
+        { label: "Name", value: src.name || null },
+        { label: "Rows", value: total == null ? null : total.toLocaleString() },
+        { label: "Columns", value: (ws.data.data?.columns ?? []).length ? (ws.data.data?.columns ?? []).join(", ") : null, wide: true },
+      ]} />
+      {rows.length > 0 ? (
+        <div className="overflow-x-auto rounded-md border">
+          <table aria-label="First source rows" className="w-full text-sm">
+            <thead className="text-muted-foreground text-left text-xs"><tr>{cols.map((c) => <th key={c} className="p-2">{c}</th>)}</tr></thead>
+            <tbody>{rows.map((r, i) => <tr key={i} className="border-t">{cols.map((c) => <td key={c} className="max-w-48 truncate p-2">{text(r[c]) || <EmptyValue />}</td>)}</tr>)}</tbody>
+          </table>
+        </div>
+      ) : <p className="text-muted-foreground text-sm">The source has no rows to show.</p>}
+      <SwitchSource campaign={campaign} current={src} />
+      <ImportSitemap campaign={campaign} rows={total} />
+    </div>
+  );
+}
+
+function SwitchSource({ campaign, current }: { campaign: Campaign; current: { type: string; id: string; name: string } }) {
+  const [v, setV] = useState<SourceValue>({ type: (SOURCE_TYPES.find((t) => t.value === current.type)?.value ?? "list") as SourceType, listId: current.type === "list" && current.id ? Number(current.id) : null, tableId: current.type !== "list" ? current.id : "", tableName: current.name });
+  const same = v.type === current.type && (v.type === "list" ? String(v.listId ?? "") === current.id : v.tableId === current.id);
+  const save = useG8Mutation(() => g8Patch(`/programmatic-campaigns/${encodeURIComponent(campaign.id)}/workspace`, v.type === "list" ? { data_source_type: v.type, list_id: v.listId } : { data_source_type: v.type, data_source_id: v.tableId, ...(v.tableName ? { data_source_name: v.tableName } : {}) }), { invalidates: [["programmatic"]] });
+  return (
+    <form className="grid gap-3 rounded-md border p-3" onSubmit={(e) => { e.preventDefault(); if (!same && sourceComplete({ source_type: v.type, list_id: v.listId, table_id: v.tableId })) void save.mutate(undefined); }}>
+      <h3 className="text-sm font-medium">Use a different source</h3>
+      <ProgrammaticSourceFields value={v} onChange={setV} currentName={current.name} idPrefix="g8-pp-switch" />
+      {save.error ? <ApiError error={save.error} title="Could not change the source" /> : null}
+      {save.data ? <p role="status" className="text-xs">Source changed. Render the pages again to apply it.</p> : null}
+      <div><Button type="submit" size="sm" loading={save.loading} disabled={same || !sourceComplete({ source_type: v.type, list_id: v.listId, table_id: v.tableId })}>Change source</Button></div>
+    </form>
+  );
+}
+
+function ImportSitemap({ campaign, rows }: { campaign: Campaign; rows: number | null }) {
+  const [url, setUrl] = useState("");
+  const [name, setName] = useState("");
+  const [max, setMax] = useState("");
+  const [fetchPages, setFetchPages] = useState(false);
+  const maxOk = max.trim() === "" || (/^\d+$/.test(max.trim()) && Number(max) >= 1);
+  const valid = /^https?:\/\/\S+$/i.test(url.trim()) && maxOk;
+  const run = useG8Mutation(() => {
+    const body: Record<string, unknown> = { sitemap_url: url.trim(), fetch_pages: fetchPages };
+    if (name.trim()) body.source_name = name.trim();
+    if (max.trim()) body.max_urls = Number(max);
+    return g8Post<{ rows_imported?: number }>(`/programmatic-campaigns/${encodeURIComponent(campaign.id)}/imports/sitemap`, body);
+  }, { invalidates: [["programmatic"]] });
+  return (
+    <form className="grid gap-3 rounded-md border p-3" onSubmit={(e) => { e.preventDefault(); if (valid) void run.mutate(undefined); }}>
+      <h3 className="text-sm font-medium">Import a sitemap as the source</h3>
+      <p role="note" className="text-xs">This replaces the current source{rows == null ? "" : ` (${plural(rows, "row")})`} with a new table of the sitemap&apos;s addresses. The current table is not deleted; switch back to it above.</p>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div><Label htmlFor="g8-pp-sitemap" className="mb-1">Sitemap address</Label><Input id="g8-pp-sitemap" type="url" placeholder="https://example.com/sitemap.xml" value={url} onChange={(e) => setUrl(e.target.value)} /></div>
+        <div><Label htmlFor="g8-pp-sitemap-name" className="mb-1">Table name (optional)</Label><Input id="g8-pp-sitemap-name" value={name} onChange={(e) => setName(e.target.value)} /></div>
+        <div><Label htmlFor="g8-pp-sitemap-max" className="mb-1">Most addresses (optional)</Label><Input id="g8-pp-sitemap-max" inputMode="numeric" value={max} onChange={(e) => setMax(e.target.value)} aria-invalid={!maxOk} /></div>
+        <label className="flex items-center gap-2 self-end text-sm"><input type="checkbox" checked={fetchPages} onChange={(e) => setFetchPages(e.target.checked)} />Also read each page</label>
+      </div>
+      {run.error ? <ApiError error={run.error} title="Could not import the sitemap" /> : null}
+      {run.data ? <p role="status" className="text-xs">Imported {run.data.data.rows_imported == null ? "the sitemap" : plural(run.data.data.rows_imported, "address", "addresses")}. It is now the source.</p> : null}
+      <div><Button type="submit" size="sm" variant="outline" loading={run.loading} disabled={!valid}>Replace source with sitemap</Button></div>
+    </form>
+  );
+}

package/blocks/programmatic-pages/components/programmatic-variables.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+/**
+ * ProgrammaticVariables: the {{variables}} of the template and slug, whether the source has a column for each, and the
+ * per-variable rules the renderer applies (a fallback for empty values, a character limit and how to cut).
+ *
+ * SDK operations, in order:
+ *   1. getProgrammaticCampaignVariables (GET /programmatic-campaigns/{id}/variables)  read   variables, matches, sample columns
+ *   2. updateProgrammaticWorkspace (PATCH /programmatic-campaigns/{id}/workspace)     write  the whole variable_config
+ * The API replaces the whole array, so the save merges the edited variables into the stored entries: every other entry, and every
+ * key the form does not show, is sent back unchanged. A cleared fallback or limit is sent as null. Only variables whose values
+ * changed are written. Saving marks the pages as changed; render again to apply it.
+ */
+
+import { useState } from "react";
+import { Button, Input, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Patch } from "@/g8/lib/g8-client";
+import type { Rec } from "@/g8/pages/lib/studio";
+import { changedEdits, editOf, mergeVariableConfig, validMaxChars } from "../lib/programmatic-types";
+import type { Campaign, VariableEdit, VariableStatus } from "../lib/programmatic-types";
+
+export interface ProgrammaticVariablesProps {
+  campaign: Campaign;
+}
+
+interface VariablesPayload { variables?: VariableStatus[]; sample_fields?: string[]; slug_template?: string }
+
+export function ProgrammaticVariables({ campaign }: ProgrammaticVariablesProps) {
+  const q = useG8Query(
+    (signal) => g8Get<VariablesPayload>(`/programmatic-campaigns/${encodeURIComponent(campaign.id)}/variables`, {}, { signal }).then((r) => r.data),
+    [campaign.id], { key: ["programmatic", "variables", campaign.id] },
+  );
+  const stored = useG8Query(
+    (signal) => g8Get<Campaign>(`/programmatic-campaigns/${encodeURIComponent(campaign.id)}`, {}, { signal }).then((r) => r.data),
+    [campaign.id], { key: ["programmatic", "detail", campaign.id] },
+  );
+  if (q.error && !q.data) return <ApiError error={q.error} title="Could not load the variables" onRetry={() => void q.refetch()} />;
+  if (stored.error && !stored.data) return <ApiError error={stored.error} title="Could not load the campaign" onRetry={() => void stored.refetch()} />;
+  if (!q.data || !stored.data) return <Skeleton className="h-32 w-full" aria-busy="true" />;
+  return <Rules key={campaign.id} campaignId={campaign.id} vars={q.data.variables ?? []} columns={q.data.sample_fields ?? []} existing={stored.data.variable_config ?? []} />;
+}
+
+function Rules({ campaignId, vars, columns, existing }: { campaignId: string; vars: VariableStatus[]; columns: string[]; existing: Rec[] }) {
+  const [edits, setEdits] = useState<Record<string, VariableEdit>>(() => Object.fromEntries(vars.map((v) => [v.name, editOf(v)])));
+  const changed = changedEdits(vars, edits);
+  const valid = changed.every((e) => validMaxChars(e.maxChars));
+  const set = (name: string, patch: Partial<VariableEdit>): void => setEdits((cur) => ({ ...cur, [name]: { ...cur[name], ...patch } }));
+  const save = useG8Mutation(() => g8Patch(`/programmatic-campaigns/${encodeURIComponent(campaignId)}/workspace`, { variable_config: mergeVariableConfig(existing, changed) }), {
+    invalidates: [["programmatic"]],
+  });
+  if (vars.length === 0) return <p className="text-muted-foreground text-sm">The template and the address pattern use no {"{{variables}}"}, so every page is the same.</p>;
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (valid && changed.length) void save.mutate(undefined); }}>
+      <p className="text-muted-foreground text-xs">Source columns: {columns.length ? columns.join(", ") : "none found"}. A variable with no matching column renders empty unless it has a fallback.</p>
+      <div className="overflow-x-auto rounded-md border">
+        <table className="w-full text-sm">
+          <thead className="text-muted-foreground text-left text-xs"><tr><th className="p-2">Variable</th><th className="p-2">Source column</th><th className="p-2">Fallback</th><th className="p-2">Character limit</th><th className="p-2">When too long</th></tr></thead>
+          <tbody>
+            {vars.map((v) => {
+              const e = edits[v.name] ?? editOf(v);
+              return (
+                <tr key={v.name} className="border-t">
+                  <td className="p-2 font-mono text-xs">{`{{${v.name}}}`}{v.in_slug ? <span className="text-muted-foreground"> (address)</span> : null}</td>
+                  <td className="p-2"><StatusPill tone={v.matched_in_source ? "positive" : "warning"}>{v.matched_in_source ? "Found" : "No column"}</StatusPill></td>
+                  <td className="p-2"><Input aria-label={`Fallback for ${v.name}`} value={e.fallback} onChange={(ev) => set(v.name, { fallback: ev.target.value })} /></td>
+                  <td className="p-2"><Input aria-label={`Character limit for ${v.name}`} inputMode="numeric" className="w-24" value={e.maxChars} onChange={(ev) => set(v.name, { maxChars: ev.target.value })} aria-invalid={!validMaxChars(e.maxChars)} /></td>
+                  <td className="p-2"><select aria-label={`Cut ${v.name} with`} className="border-input bg-background h-9 rounded-md border px-2 text-sm" value={e.policy} onChange={(ev) => set(v.name, { policy: ev.target.value as "ellipsis" | "clip" })}><option value="ellipsis">Add ...</option><option value="clip">Cut off</option></select></td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+      {!valid ? <p role="alert" className="text-error text-xs">A character limit is a whole number from 1 to 5000.</p> : null}
+      {save.error ? <ApiError error={save.error} title="Could not save the variables" /> : null}
+      {save.data ? <p role="status" className="text-xs">Saved. Render the pages again to apply the new rules.</p> : null}
+      <div><Button type="submit" loading={save.loading} disabled={!valid || changed.length === 0}>Save variable rules</Button></div>
+    </form>
+  );
+}

package/blocks/programmatic-pages/hooks/use-programmatic-workspace.ts

@@ -0,0 +1,19 @@
+"use client";
+
+/**
+ * useProgrammaticWorkspace: the workspace of one campaign (source, readiness, numbers, links, deployment), shared by every tab
+ * through one cache entry so a save on one tab refreshes the others.
+ *
+ * SDK operations: getProgrammaticWorkspace (GET /programmatic-campaigns/{id}/workspace)   read
+ */
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import type { Workspace } from "../lib/programmatic-types";
+
+export function useProgrammaticWorkspace(campaignId: string) {
+  return useG8Query(
+    (signal) => g8Get<Workspace>(`/programmatic-campaigns/${encodeURIComponent(campaignId)}/workspace`, {}, { signal }).then((r) => r.data),
+    [campaignId],
+    { key: ["programmatic", "workspace", campaignId] },
+  );
+}

package/blocks/programmatic-pages/lib/programmatic-types.ts

@@ -0,0 +1,330 @@
+"use client";
+
+/**
+ * Types, vocabularies and pure helpers for the programmatic-pages block.
+ *
+ * A programmatic campaign is ONE template landing page plus ONE data source: the API renders one page per source row
+ * (a page per account, per city, per integration). Every vocabulary below is copied from the contract
+ * (sdk/js/src/generated/schemas.ts and the app's router), not from memory: the API refuses anything else.
+ * Responses are open objects (`StudioContentPayload`), so every field is optional and read defensively.
+ * Calls nothing.
+ */
+
+import type { Rec } from "@/g8/pages/lib/studio";
+
+export type SourceType = "list" | "workbench" | "csv" | "seo_import";
+export const SOURCE_TYPES: { value: SourceType; label: string; hint: string }[] = [
+  { value: "list", label: "A contact list", hint: "One page per person on the list." },
+  { value: "workbench", label: "A Workbench table", hint: "One page per row of a table you built in Workbench." },
+  { value: "csv", label: "An imported CSV table", hint: "One page per row of a table made from a CSV file." },
+  { value: "seo_import", label: "A sitemap import table", hint: "One page per URL imported from a sitemap." },
+];
+
+/** Campaign `status`: where the render run is. */
+export const CAMPAIGN_STATUSES = ["draft", "validating", "generating", "completed", "failed", "paused"] as const;
+/** Campaign and page `lifecycle_state`. */
+export const LIFECYCLE_STATES = ["draft", "ready", "published", "needs_attention", "archived"] as const;
+/** Page `status`: pending, generated, published, failed. */
+export const PAGE_STATUSES = ["pending", "generated", "published", "failed"] as const;
+export const CHANGE_STATES = ["no_changes", "template_changed", "data_changed", "manual_override", "generation_failed", "deploy_failed"] as const;
+
+export const REGENERATION_MODES: { value: string; label: string }[] = [
+  { value: "manual", label: "Only when I start it" },
+  { value: "hourly", label: "Every hour" },
+  { value: "daily", label: "Every day" },
+  { value: "weekly", label: "Every week" },
+  { value: "on_workbench_change", label: "When the Workbench table changes" },
+];
+export const APPROVAL_MODES: { value: string; label: string; hint: string }[] = [
+  { value: "draft_only", label: "Draft only", hint: "Generated pages wait for you." },
+  { value: "require_review", label: "Require review", hint: "Generated pages wait for a review." },
+  { value: "auto_publish", label: "Publish automatically", hint: "Generated pages are marked live as soon as they render." },
+];
+
+/** One generated campaign (the app's `_campaign_to_dict`). */
+export interface Campaign {
+  id: string;
+  name: string;
+  template_page_id?: string | null;
+  list_id?: number | null;
+  data_source_type?: string | null;
+  data_source?: { type?: string | null; id?: string | number | null; name?: string | null } | null;
+  slug_template?: string | null;
+  variable_config?: Rec[] | null;
+  status?: string | null;
+  lifecycle_state?: string | null;
+  change_state?: string | null;
+  total_pages?: number | null;
+  pages_generated?: number | null;
+  pages_failed?: number | null;
+  error_message?: string | null;
+  deployment_run_id?: string | null;
+  settings?: Rec | null;
+  regeneration?: { mode?: string; approval_mode?: string; changed_rows_only?: boolean } | null;
+  last_generated_at?: string | null;
+  last_deployed_at?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+
+/** One generated page (the app's `_page_to_dict`). */
+export interface GeneratedPage {
+  id: string;
+  contact_id?: number | null;
+  slug?: string | null;
+  status?: string | null;
+  lifecycle_state?: string | null;
+  change_state?: string | null;
+  published_url?: string | null;
+  error_message?: string | null;
+  manual_override?: Rec | null;
+  seo_health?: { score?: number | null; issues?: string[] | null; title?: string | null; word_count?: number | null } | null;
+  last_generated_at?: string | null;
+  last_deployed_at?: string | null;
+  created_at?: string | null;
+}
+
+export interface VariableStatus {
+  name: string;
+  in_template?: boolean;
+  in_slug?: boolean;
+  matched_in_source?: boolean;
+  config?: Rec | null;
+}
+
+/** Generation progress (`GET /status`). */
+export interface GenerationStatus {
+  status?: string | null;
+  total_pages?: number | null;
+  pages_generated?: number | null;
+  pages_failed?: number | null;
+  progress_pct?: number | null;
+  error_message?: string | null;
+}
+
+export const wording = (value: string | null | undefined): string => (value ? value.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase()) : "");
+
+/** The campaigns of a list payload: the app's named key `campaigns`, mirrored onto `items`. */
+export function campaignRows(data: unknown): Campaign[] {
+  const rec = (data && typeof data === "object" ? data : {}) as Rec;
+  const rows = Array.isArray(data) ? data : Array.isArray(rec.campaigns) ? rec.campaigns : Array.isArray(rec.items) ? rec.items : [];
+  return rows as Campaign[];
+}
+
+/** Where a campaign draws its rows from: the source record when the API sent one, else the list id. Never invents a default. */
+export function sourceOf(c: Pick<Campaign, "data_source" | "data_source_type" | "list_id">): { type: string; id: string; name: string } {
+  const type = c.data_source?.type || c.data_source_type || "";
+  const id = c.data_source?.id ?? (type === "list" ? c.list_id : null);
+  return { type: type || "", id: id == null || id === "" ? "" : String(id), name: c.data_source?.name || "" };
+}
+
+/** A campaign can only be edited (name, slug, source) while it is a draft or failed; the API answers 400 otherwise. */
+export function canEditCampaign(c: Pick<Campaign, "status">): boolean {
+  return c.status === "draft" || c.status === "failed";
+}
+
+export const isGenerating = (c: Pick<Campaign, "status">): boolean => c.status === "generating";
+
+/** The fields of a campaign form; `null` means the person cleared it. */
+export interface CampaignDraft {
+  name: string;
+  slug_template: string;
+  source_type: SourceType;
+  list_id: number | null;
+  table_id: string;
+  table_name: string;
+}
+
+/** The PATCH body for an edit: only what changed, so saving can never blank a field the form did not load. */
+export function campaignDiff(current: Campaign, draft: CampaignDraft): Rec {
+  const out: Rec = {};
+  if (draft.name.trim() !== (current.name ?? "")) out.name = draft.name.trim();
+  if (draft.slug_template.trim() !== (current.slug_template ?? "")) out.slug_template = draft.slug_template.trim();
+  const was = sourceOf(current);
+  const nextId = draft.source_type === "list" ? (draft.list_id == null ? "" : String(draft.list_id)) : draft.table_id;
+  if (draft.source_type !== was.type || nextId !== was.id) {
+    out.data_source_type = draft.source_type;
+    if (draft.source_type === "list") out.list_id = draft.list_id;
+    else {
+      out.data_source_id = draft.table_id;
+      if (draft.table_name) out.data_source_name = draft.table_name;
+    }
+  }
+  return out;
+}
+
+/** Whether the source part of a draft is complete (the API answers 400 "require a list_id / data_source_id" otherwise). */
+export function sourceComplete(draft: Pick<CampaignDraft, "source_type" | "list_id" | "table_id">): boolean {
+  return draft.source_type === "list" ? draft.list_id != null && draft.list_id > 0 : draft.table_id.trim() !== "";
+}
+
+// ── page actions ────────────────────────────────────────────────────────────────────────────────────────────────
+
+export type PageActionName = "mark_ready_to_deploy" | "unpublish" | "mark_for_regeneration" | "override" | "reset_override";
+export type BulkActionName = "mark_ready_to_deploy_selected" | "unpublish_selected" | "mark_for_regeneration_selected" | "delete_selected" | "export_urls" | "queue_search_console";
+export type DeployActionName = "deploy_pending_changes" | "republish_all" | "rollback_publish";
+
+export const isLive = (p: Pick<GeneratedPage, "status" | "published_url">): boolean => p.status === "published" || Boolean(p.published_url);
+
+/** Why a row action is not available for this page, or "" when it is. The API answers 400 for the first one. */
+export function pageActionBlock(page: GeneratedPage, action: PageActionName): string {
+  if (action === "mark_ready_to_deploy" && (page.status === "failed" || page.status === "pending")) return "This page has no rendered HTML yet.";
+  if (action === "mark_ready_to_deploy" && isLive(page)) return "This page is already live.";
+  if (action === "unpublish" && !isLive(page)) return "This page is not live.";
+  if (action === "reset_override" && !(page.manual_override && Object.keys(page.manual_override).length) && page.change_state !== "manual_override") return "This page has no manual edit to undo.";
+  if (action === "override" && page.status === "failed") return "A failed page has no HTML to replace. Regenerate it first.";
+  return "";
+}
+
+/**
+ * The page ids a bulk action really applies to. The confirm dialog counts this array and the request sends this same array,
+ * so what the person agreed to is exactly what is sent. Live pages only for the actions that touch the live site.
+ */
+export function bulkTargets(pages: GeneratedPage[], selected: ReadonlySet<string>, action: BulkActionName): string[] {
+  const chosen = pages.filter((p) => selected.has(p.id));
+  switch (action) {
+    case "unpublish_selected": return chosen.filter(isLive).map((p) => p.id);
+    case "mark_ready_to_deploy_selected": return chosen.filter((p) => p.status === "generated" && !isLive(p)).map((p) => p.id);
+    case "queue_search_console":
+    case "export_urls": return chosen.filter((p) => Boolean(p.published_url)).map((p) => p.id);
+    default: return chosen.map((p) => p.id);
+  }
+}
+
+// ── variables ───────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface VariableEdit {
+  name: string;
+  fallback: string;
+  maxChars: string;
+  policy: "ellipsis" | "clip";
+}
+
+/** What the renderer reads from one `variable_config` entry. */
+export function editOf(v: VariableStatus): VariableEdit {
+  const cfg = (v.config ?? {}) as Rec;
+  const max = cfg.max_chars;
+  return {
+    name: v.name,
+    fallback: typeof cfg.fallback_value === "string" ? cfg.fallback_value : "",
+    maxChars: typeof max === "number" ? String(max) : "",
+    policy: cfg.truncation_policy === "clip" ? "clip" : "ellipsis",
+  };
+}
+
+export function validMaxChars(value: string): boolean {
+  return value.trim() === "" || (/^\d+$/.test(value.trim()) && Number(value) >= 1 && Number(value) <= 5000);
+}
+
+/**
+ * The new `variable_config` array. The API REPLACES the whole array, so every entry the form did not touch is kept as it was
+ * (with every key it carries), and a cleared field is sent as null rather than dropped.
+ */
+export function mergeVariableConfig(existing: Rec[], edits: VariableEdit[]): Rec[] {
+  const out = existing.map((e) => ({ ...e }));
+  for (const edit of edits) {
+    const at = out.findIndex((e) => String(e.field ?? "").toLowerCase() === edit.name.toLowerCase());
+    const base: Rec = at >= 0 ? out[at] : { field: edit.name };
+    const next: Rec = { ...base, fallback_value: edit.fallback.trim() === "" ? null : edit.fallback, max_chars: edit.maxChars.trim() === "" ? null : Number(edit.maxChars), truncation_policy: edit.policy };
+    if (at >= 0) out[at] = next;
+    else out.push(next);
+  }
+  return out;
+}
+
+/** The edits whose values differ from the stored config, so an untouched variable adds no entry. */
+export function changedEdits(vars: VariableStatus[], edits: Record<string, VariableEdit>): VariableEdit[] {
+  return vars.flatMap((v) => {
+    const now = edits[v.name];
+    const was = editOf(v);
+    return now && (now.fallback !== was.fallback || now.maxChars !== was.maxChars || now.policy !== was.policy) ? [now] : [];
+  });
+}
+
+// ── workspace settings ─────────────────────────────────────────────────────────────────────────────────────────
+
+export interface SettingsDraft {
+  mode: string;
+  approval: string;
+  changedOnly: boolean;
+  basePath: string;
+  domain: string;
+  thinWords: string;
+  schemaRequired: boolean;
+  canonical: string;
+  sitemap: boolean;
+  breadcrumbs: boolean;
+  related: boolean;
+}
+
+const sub = (settings: Rec | null | undefined, key: string): Rec => ((settings?.[key] && typeof settings[key] === "object" ? settings[key] : {}) as Rec);
+
+export function settingsDraftOf(c: Campaign): SettingsDraft {
+  const s = c.settings ?? {};
+  const regen = { ...sub(s, "regeneration"), ...(c.regeneration ?? {}) } as Rec;
+  const dep = sub(s, "deployment");
+  const seo = sub(s, "seo");
+  const links = sub(s, "links");
+  const str = (v: unknown): string => (typeof v === "string" ? v : "");
+  return {
+    mode: str(regen.mode), approval: str(regen.approval_mode), changedOnly: regen.changed_rows_only === undefined ? true : Boolean(regen.changed_rows_only),
+    basePath: str(dep.base_path), domain: str(dep.domain), thinWords: typeof seo.thin_content_words === "number" ? String(seo.thin_content_words) : "",
+    schemaRequired: Boolean(seo.schema_required), canonical: str(seo.canonical_url_template),
+    sitemap: links.sitemap_enabled !== false, breadcrumbs: links.breadcrumbs_enabled !== false, related: links.related_pages_enabled !== false,
+  };
+}
+
+/** The `settings` body of a workspace PATCH: only the groups with a changed key, a cleared text sent as null. */
+export function settingsPatch(was: SettingsDraft, now: SettingsDraft): Rec {
+  const out: Rec = {};
+  const put = (group: string, key: string, value: unknown): void => { out[group] = { ...(out[group] as Rec | undefined), [key]: value }; };
+  const text = (v: string): string | null => (v.trim() === "" ? null : v.trim());
+  if (now.mode !== was.mode) put("regeneration", "mode", now.mode);
+  if (now.approval !== was.approval) put("regeneration", "approval_mode", now.approval);
+  if (now.changedOnly !== was.changedOnly) put("regeneration", "changed_rows_only", now.changedOnly);
+  if (now.basePath !== was.basePath) put("deployment", "base_path", text(now.basePath));
+  if (now.domain !== was.domain) put("deployment", "domain", text(now.domain));
+  if (now.thinWords !== was.thinWords) put("seo", "thin_content_words", now.thinWords.trim() === "" ? null : Number(now.thinWords));
+  if (now.schemaRequired !== was.schemaRequired) put("seo", "schema_required", now.schemaRequired);
+  if (now.canonical !== was.canonical) put("seo", "canonical_url_template", text(now.canonical));
+  if (now.sitemap !== was.sitemap) put("links", "sitemap_enabled", now.sitemap);
+  if (now.breadcrumbs !== was.breadcrumbs) put("links", "breadcrumbs_enabled", now.breadcrumbs);
+  if (now.related !== was.related) put("links", "related_pages_enabled", now.related);
+  return out;
+}
+
+/** Slug preview for the form: the `{{names}}` a slug template uses. */
+export function slugVariables(template: string): string[] {
+  return Array.from(new Set(Array.from(template.matchAll(/\{\{\s*([^{}]+?)\s*\}\}/g)).map((m) => m[1])));
+}
+
+export const PAGE_SIZE = 50;
+
+/** The workspace (`GET /workspace`): the one read that carries the source, readiness, numbers, links and deployment. */
+export interface Workspace {
+  campaign?: Campaign;
+  overview?: {
+    total_rows?: number | null;
+    generated_pages?: number | null;
+    live_pages?: number | null;
+    failed_pages?: number | null;
+    changed_rows?: number | null;
+    manual_overrides?: number | null;
+    last_generation?: string | null;
+    last_publish?: string | null;
+    next_regeneration?: string | null;
+    readiness?: { key: string; label: string; complete: boolean; details?: string[] }[];
+  };
+  template?: { template_page_id?: string | null; slug_template?: string | null; variables?: string[]; preview_row?: Rec | null };
+  data?: { source?: { type?: string | null; id?: string | number | null; name?: string | null }; columns?: string[]; sample_rows?: Rec[]; total_rows?: number | null; changed_rows?: number | null };
+  seo?: { average_score?: number | null; issues?: Record<string, number> };
+  links?: { orphan_pages?: string[]; sitemap_xml?: string };
+  deployment?: {
+    published_pages?: number | null;
+    pending_pages?: number | null;
+    url_pattern_preview?: string | null;
+    history?: { status?: string; message?: string; checked_at?: string; deployment_url?: string | null }[];
+    diagnostics?: { status?: string; message?: string; checked_at?: string };
+  };
+  pages?: { total?: number | null; status_counts?: Record<string, number> };
+}

package/blocks/programmatic-pages/recipes/create-a-programmatic-campaign.ts

@@ -0,0 +1,23 @@
+/**
+ * @title Create a programmatic campaign and preview one page
+ * @when Setting up "a page per row": a template landing page (with {{variables}}) plus a list. Creating renders nothing and
+ * publishes nothing; the preview renders one row without saving it.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const campaign = await g8.api.programmaticPages.createProgrammaticCampaign({
+  body: {
+    name: "Integration pages",
+    template_page_id: process.env.TEMPLATE_PAGE_ID!, // a landing page with HTML, from listLandingPages
+    data_source_type: "list",
+    list_id: Number(process.env.SOURCE_LIST_ID), // from listLists
+    slug_template: "{{company}}-{{first_name}}",
+  },
+});
+
+// Programmatic responses are open objects, so name the fields you read.
+const created = campaign.data as { id: string };
+const preview = (await g8.api.programmaticPages.previewProgrammaticPage({ path: { campaign_id: created.id }, body: {} })).data as { slug?: string; html?: string };
+console.log(created.id, preview.slug, String(preview.html ?? "").length, "characters of HTML");

package/blocks/programmatic-pages/recipes/render-and-follow.ts

@@ -0,0 +1,21 @@
+/**
+ * @title Render every page of a campaign and follow the run
+ * @when After the campaign exists. Rendering is free (no model runs). If the campaign's approval mode is "auto_publish" the API
+ * marks each page live as it renders, so check the mode first and have a person confirm the row count.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+const campaign_id = process.env.CAMPAIGN_ID!;
+
+const ws = await g8.api.programmaticPages.getProgrammaticWorkspace({ path: { campaign_id } });
+const mode = (ws.data as { campaign?: { regeneration?: { approval_mode?: string } } }).campaign?.regeneration?.approval_mode;
+if (mode === "auto_publish") throw new Error("This campaign publishes automatically: a person must confirm before rendering.");
+
+await g8.api.programmaticPages.startProgrammaticGeneration({ path: { campaign_id } });
+for (let i = 0; i < 120; i++) {
+  const status = (await g8.api.programmaticPages.getProgrammaticGenerationStatus({ path: { campaign_id } })).data as { status?: string; pages_generated?: number; pages_failed?: number; total_pages?: number };
+  console.log(status.status, status.pages_generated, "of", status.total_pages, "failed", status.pages_failed);
+  if (["completed", "failed", "paused"].includes(String(status.status))) break;
+  await new Promise((r) => setTimeout(r, 3000));
+}

package/blocks/programmatic-pages/recipes/review-then-publish.ts

@@ -0,0 +1,17 @@
+/**
+ * @title List the rendered pages and publish the waiting ones after a person agrees
+ * @when Putting rendered pages on the live site. Publishing changes what real visitors see, so this script only reads and
+ * prints the numbers; the deploy call is behind PUBLISH_CONFIRMED=yes, set by a person who saw them.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+const campaign_id = process.env.CAMPAIGN_ID!;
+
+const ws = (await g8.api.programmaticPages.getProgrammaticWorkspace({ path: { campaign_id } })).data as { deployment?: { pending_pages?: number; published_pages?: number } };
+console.log("waiting to go live:", ws.deployment?.pending_pages ?? "unknown", "live now:", ws.deployment?.published_pages ?? "unknown");
+
+if (process.env.PUBLISH_CONFIRMED === "yes") {
+  const result = await g8.api.programmaticPages.runProgrammaticBulkPageAction({ path: { campaign_id }, body: { action: "deploy_pending_changes" } });
+  console.log(result.data);
+}