@graph8/sdk 0.370.0 → 0.374.0

package/blocks/pickers/hooks/use-picker-pages.ts

@@ -0,0 +1,73 @@
+"use client";
+
+/**
+ * usePickerPages: the paging + search engine behind ContactPicker and CompanyPicker.
+ *
+ * Page-number lists (`?page&limit`, `pagination.has_next`) with a search box: the text is debounced, a new search
+ * starts over from page 1, "load more" appends the next page to the ones already shown, and a response for an
+ * earlier search or page is dropped (latest wins). Nothing is fetched until `enabled` (the picker is open).
+ *
+ * It calls no operation itself: `fetchPage` does, so the caller's component declares the operation.
+ */
+import { useEffect, useState } from "react";
+import { useDebounced } from "../lib/use-debounced";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+
+export interface PickerPage<T> {
+  rows: T[];
+  hasNext: boolean;
+}
+
+export interface UsePickerPages<T> {
+  search: string;
+  setSearch: (value: string) => void;
+  /** The debounced, trimmed search text the loaded rows belong to. */
+  q: string;
+  rows: T[];
+  hasMore: boolean;
+  /** The first page of this search is loading and nothing is shown yet. */
+  loading: boolean;
+  /** A following page is loading. */
+  loadingMore: boolean;
+  error: unknown;
+  refetch: () => void;
+  loadMore: () => void;
+}
+
+interface Loaded<T> extends PickerPage<T> { q: string; page: number }
+
+export function usePickerPages<T>(
+  enabled: boolean,
+  fetchPage: (q: string, page: number, signal: AbortSignal) => Promise<PickerPage<T>>,
+): UsePickerPages<T> {
+  const [search, setSearchText] = useState("");
+  const [page, setPage] = useState({ q: "", n: 1 });
+  const [store, setStore] = useState<{ q: string | null; pages: T[][]; hasNext: boolean }>({ q: null, pages: [], hasNext: false });
+  const q = useDebounced(search.trim());
+  const n = page.q === q ? page.n : 1;
+  const query = useG8Query(
+    async (signal): Promise<Loaded<T>> => ({ ...(await fetchPage(q, n, signal)), q, page: n }),
+    [q, n],
+    { enabled },
+  );
+  useEffect(() => {
+    const d = query.data;
+    if (!d || d.q !== q || d.page !== n) return; // a response for an earlier search or page
+    setStore((s) => ({ q, pages: [...(s.q === q ? s.pages.slice(0, n - 1) : []), d.rows], hasNext: d.hasNext }));
+  }, [query.data, q, n]);
+
+  const current = store.q === q;
+  const rows = current ? store.pages.flat() : [];
+  return {
+    search,
+    setSearch: (value) => { setSearchText(value); setPage({ q: value.trim(), n: 1 }); },
+    q,
+    rows,
+    hasMore: current && store.hasNext,
+    loading: enabled && (query.loading || !current) && rows.length === 0,
+    loadingMore: query.loading && rows.length > 0,
+    error: query.error,
+    refetch: () => { void query.refetch(); },
+    loadMore: () => setPage({ q, n: n + 1 }),
+  };
+}

package/blocks/pickers/lib/use-debounced.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** `value`, but only after it has stopped changing for `ms`. The search box of every picker reads through this. */
+export function useDebounced<T>(value: T, ms = 250): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}

package/blocks/programmatic-pages/README.md

@@ -0,0 +1,82 @@
+# programmatic-pages
+
+One **template landing page** plus one **data source** makes **one page per row**: a page per account, per city, per integration. A campaign holds the template, the source (a contact list, or a Workbench, CSV or sitemap-import table), an address pattern such as `{{company}}-{{first_name}}`, and per-variable rules. Rendering is free (no model runs). Putting pages on the live site is a separate, confirmed step.
+
+## Screens
+
+`ProgrammaticPagesScreen` (`components/programmatic-pages-screen.tsx`) is the finished page.
+
+```tsx
+import { ProgrammaticPagesScreen } from "@/g8/programmatic-pages/components/programmatic-pages-screen";
+export default function Page() { return <ProgrammaticPagesScreen />; }
+```
+
+Open a campaign (`?id=`) for Overview, Pages, Preview, Variables, Source, Settings, Edit and Details (`?tab=`); `&view=full` shows it as a full page. The Overview links to the template page in the `pages` screen (`/pages?id=`; override with `pagesHref`).
+
+Flows: see every campaign with state, source and page counts (search; filter by state and source; the list is complete, the API does not page it); create one from a template page and a list or table; render all pages and follow the run; read, search and filter the generated pages; mark pages ready, regenerate them, replace one page's HTML and undo it; take pages off the live site, delete them, export their addresses, send live ones to Search Console (each confirmed); publish waiting pages, republish everything or roll the last publish back (each confirmed with its page count); preview one row; set a fallback, character limit and cut rule per variable; switch the source or import a sitemap as the source; set regeneration, publishing, search and link settings; edit the name and address pattern; delete a campaign (confirmed). Optional props: `pagesHref`, `renderRowActions`, `renderDetailActions`, `extraDetailTabs`, `toolbarActions`.
+
+Parts to mount alone: `ProgrammaticCampaignForm`, `ProgrammaticOverview`, `ProgrammaticGenerate`, `ProgrammaticPublish`, `ProgrammaticGeneratedPages`, `ProgrammaticPreview`, `ProgrammaticVariables`, `ProgrammaticSource`, `ProgrammaticSettings`.
+
+## Install
+
+```
+npx @graph8/sdk add programmatic-pages
+```
+
+Installs `foundation`, `crm` and `pages` first if missing. Everything lands under `g8/programmatic-pages/`.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| graph8 | A **template landing page** with HTML and `{{variables}}` (make it in the pages block). It cannot be changed after the campaign exists. | `GET /api/v1/landing-pages` lists it. |
+| graph8 | A **source** with a column for each variable (a contact list or a Workbench table). | `GET /api/v1/programmatic-campaigns/{id}/variables` shows every variable as found. |
+| graph8 | **Publishing** needs a connected Cloudflare website or hosted publishing. Rendering does not. | A person publishes one test campaign. |
+| graph8 key | `campaigns:read`, `campaigns:write`, `campaigns:delete`; `campaigns:run` for page actions and publish (separate from `campaigns:write`); `lists:read`. | `g8.api.me.describeCurrentKey()` |
+| Your app | `allowedPrefixes` must include `programmatic-campaigns`, `landing-pages`, `workbench`, `lists`. | The route file lists them. |
+
+## The flow, in order (ids passed between steps)
+
+1. **Create**: `createProgrammaticCampaign({ name, template_page_id, data_source_type, list_id | data_source_id, slug_template? })` -> **`campaign.id`** (a UUID). `template_page_id` comes from `listLandingPages`, `list_id` from `listLists`, a table id from `listWorkbenchTables`.
+2. **Check**: `getProgrammaticCampaignVariables` shows each `{{variable}}`, whether the source has a column for it, and the rule stored for it. `updateProgrammaticWorkspace({ variable_config })` REPLACES the whole array: send the existing entries back with your change.
+3. **Preview**: `previewProgrammaticPage({ contact_id? })` renders one row and saves nothing.
+4. **Render**: `startProgrammaticGeneration` (202) then poll `getProgrammaticGenerationStatus` until `completed`, `failed` or `paused`. Free.
+5. **Review**: `listProgrammaticGeneratedPages` (50 per read, up to 500) and `getProgrammaticWorkspace` (counts, search health, deployment).
+6. **Page actions**: `runProgrammaticPageAction` (`mark_ready_to_deploy`, `unpublish`, `mark_for_regeneration`, `override`, `reset_override`) and `runProgrammaticBulkPageAction` on a selection.
+7. **Publish**: `runProgrammaticBulkPageAction({ action: "deploy_pending_changes" | "republish_all" | "rollback_publish" })`, confirmed with the page count.
+8. **Source**: `updateProgrammaticWorkspace` switches list or table; `importProgrammaticSitemap` REPLACES the source with a table of the sitemap's addresses.
+9. **Remove**: `deleteProgrammaticCampaign` removes the campaign and its pages (confirmed); live copies are not taken down.
+
+## Default decisions (do not ask the human unless marked)
+
+| Decision | Default | Ask? |
+|---|---|---|
+| Data source | None: a person picks the list or table | **yes** |
+| Address pattern | Left blank: the API's own `{{company}}-{{first_name}}` | no |
+| Rendering | Free; makes drafts. Confirmed first when the approval mode is "Publish automatically" | no |
+| Publishing | Never without a person confirming the page count | **yes** |
+| Stopping | Unpublish first; a delete does not take live pages down | no |
+
+## Operation coverage (15 programmaticPages operations, all used)
+
+`listProgrammaticCampaigns`, `createProgrammaticCampaign`, `getProgrammaticCampaign`, `updateProgrammaticCampaign`, `deleteProgrammaticCampaign`, `getProgrammaticCampaignVariables`, `previewProgrammaticPage`, `startProgrammaticGeneration`, `getProgrammaticGenerationStatus`, `listProgrammaticGeneratedPages`, `getProgrammaticWorkspace`, `updateProgrammaticWorkspace`, `importProgrammaticSitemap`, `runProgrammaticPageAction`, `runProgrammaticBulkPageAction`. Tiers: `deleteProgrammaticCampaign` is destructive; both page-action operations are external (they can change the live site); none is billable. The block also reads `listLandingPages`, `getLandingPage`, `listWorkbenchTables` and (through the crm `ListSelect`) `listLists`.
+
+## API gaps (found while building; not edited, the backend is colleague-owned)
+
+| Asked for | Reality | What the block does |
+|---|---|---|
+| "Generated as drafts; nothing goes live until a deploy" | With approval mode `auto_publish` the render task marks every page `published` with a public address as it renders. | Confirms the render (external, sized by the source rows) in that mode and says so. |
+| Re-render replaces pages | The render does not clear earlier pages and `cb_programmatic_pages` has no unique slug, so a second run can add a second set. | A visible warning before "Generate again"; delete duplicates with the bulk delete. |
+| Read a page's HTML | No endpoint returns a generated page's HTML. | "Replace HTML" asks for the full replacement. |
+| Filter or search generated pages | `listProgrammaticGeneratedPages` takes `offset` and `limit` only. | Search and the status filter act on the loaded pages and say so. |
+| Map a variable to a differently named column | The workspace shows `source_column`, but the renderer matches `{{name}}` to a column of the same name only. | Only the rules the renderer reads are offered: fallback, character limit, cut rule. |
+| Edit a running or finished campaign | `updateProgrammaticCampaign` answers 400 unless the status is draft or failed. | The Edit tab says so; source, variables and settings go through the workspace, which has no such rule. |
+| Change the template | `updateProgrammaticCampaign` has no template field. | Shown read-only; make a new campaign. |
+| Rename the source list | The list source carries no name. | Shown as "Current list" until the options load. |
+| `deploy_pending_changes` count | The workspace counts pages in status `generated`; the API also redeploys live pages whose data changed. | The confirm shows the waiting count and the changed-row count. |
+| Responses | Every programmatic response is an open object (`StudioContentPayload`); the list key is `campaigns` / `pages`, mirrored onto `items`. | Read defensively; a missing value shows a dash. |
+
+## Things that surprise people
+
+- Page action `publish` and `regenerate` are aliases (`mark_ready_to_deploy`, `mark_for_regeneration`); marking ready does not put a page on the live site, only a publish does.
+- Preview needs a numeric row id; workbench rows without one can only be previewed as "First row".

package/blocks/programmatic-pages/block.json

@@ -0,0 +1,292 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "programmatic-pages",
+  "title": "Programmatic pages",
+  "summary": "One template landing page plus a list or table makes a page per row: create campaigns, render, preview, tune variables and source, publish, unpublish and roll back with confirmations.",
+  "features": [
+    "campaign list with search, state and source filters and stats",
+    "create from a template page and a list or table; edit while draft or failed; delete with confirmation",
+    "render every page (free), follow the run, preview one row in a sandboxed frame",
+    "per-variable fallback, character limit and cut rule; merged into the stored config",
+    "switch the source or import a sitemap as the source",
+    "generated pages with search, filters, row and bulk actions, HTML replacement, address export",
+    "publish waiting pages, republish everything, roll back the last publish, send live pages to Search Console; each confirmed with a real page count",
+    "regeneration, publishing, search and link settings"
+  ],
+  "dependsOn": [
+    "crm",
+    "pages"
+  ],
+  "operations": [
+    "create_programmatic_campaign_programmatic_campaigns_post",
+    "delete_programmatic_campaign_programmatic_campaigns__campaign_id__delete",
+    "get_landing_page_landing_pages__landing_page_id__get",
+    "get_programmatic_campaign_programmatic_campaigns__campaign_id__get",
+    "get_programmatic_campaign_variables_programmatic_campaigns__campaign_id__variables_get",
+    "get_programmatic_generation_status_programmatic_campaigns__campaign_id__status_get",
+    "get_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_get",
+    "import_programmatic_sitemap_programmatic_campaigns__campaign_id__imports_sitemap_post",
+    "list_landing_pages_landing_pages_get",
+    "list_programmatic_campaigns_programmatic_campaigns_get",
+    "list_programmatic_generated_pages_programmatic_campaigns__campaign_id__pages_get",
+    "list_workbench_tables_workbench_tables_get",
+    "preview_programmatic_page_programmatic_campaigns__campaign_id__preview_post",
+    "run_programmatic_bulk_page_action_programmatic_campaigns__campaign_id__pages_actions_post",
+    "run_programmatic_page_action_programmatic_campaigns__campaign_id__pages__page_id__actions_post",
+    "start_programmatic_generation_programmatic_campaigns__campaign_id__generate_post",
+    "update_programmatic_campaign_programmatic_campaigns__campaign_id__patch",
+    "update_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_patch"
+  ],
+  "components": [
+    {
+      "name": "ProgrammaticPagesScreen",
+      "file": "components/programmatic-pages-screen.tsx",
+      "purpose": "Finished programmatic pages workspace: campaign list with search, filters and stats, create, delete (confirmed), and per-campaign overview, pages, preview, variables, source, settings, edit and details; deep link ?id= and ?tab=.",
+      "operations": [
+        "delete_programmatic_campaign_programmatic_campaigns__campaign_id__delete",
+        "list_programmatic_campaigns_programmatic_campaigns_get"
+      ],
+      "tiers": [
+        "read",
+        "destructive"
+      ]
+    },
+    {
+      "name": "ProgrammaticCampaignForm",
+      "file": "components/programmatic-campaign-form.tsx",
+      "purpose": "Create a campaign (template page, address pattern, list or table source) or edit one; edit reads the full record first and sends only changed fields, and only while the campaign is a draft or failed.",
+      "operations": [
+        "create_programmatic_campaign_programmatic_campaigns_post",
+        "get_programmatic_campaign_programmatic_campaigns__campaign_id__get",
+        "list_landing_pages_landing_pages_get",
+        "update_programmatic_campaign_programmatic_campaigns__campaign_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "ProgrammaticSourceFields",
+      "file": "components/programmatic-source-fields.tsx",
+      "purpose": "Choose a campaign source: a contact list, or a Workbench, CSV or sitemap-import table, with no typed ids.",
+      "operations": [
+        "list_workbench_tables_workbench_tables_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ProgrammaticOverview",
+      "file": "components/programmatic-overview.tsx",
+      "purpose": "Readiness checks, counts, search health, template link and publish state of one campaign; hosts the generate and publish panels.",
+      "operations": [
+        "get_landing_page_landing_pages__landing_page_id__get",
+        "get_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ProgrammaticGenerate",
+      "file": "components/programmatic-generate.tsx",
+      "purpose": "Render every page (free) and follow the run; confirmed when the approval mode publishes automatically, sized by the source row count.",
+      "operations": [
+        "get_programmatic_generation_status_programmatic_campaigns__campaign_id__status_get",
+        "get_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_get",
+        "start_programmatic_generation_programmatic_campaigns__campaign_id__generate_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "ProgrammaticPublish",
+      "file": "components/programmatic-publish.tsx",
+      "purpose": "Publish waiting pages, republish everything or roll the last publish back, each confirmed with the number of pages it touches.",
+      "operations": [
+        "get_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_get",
+        "run_programmatic_bulk_page_action_programmatic_campaigns__campaign_id__pages_actions_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "ProgrammaticGeneratedPages",
+      "file": "components/programmatic-generated-pages.tsx",
+      "purpose": "Generated pages with search, status filter, selection, row and bulk lifecycle actions (unpublish, delete, Search Console confirmed), HTML replacement and address export.",
+      "operations": [
+        "list_programmatic_generated_pages_programmatic_campaigns__campaign_id__pages_get",
+        "run_programmatic_bulk_page_action_programmatic_campaigns__campaign_id__pages_actions_post",
+        "run_programmatic_page_action_programmatic_campaigns__campaign_id__pages__page_id__actions_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "ProgrammaticPreview",
+      "file": "components/programmatic-preview.tsx",
+      "purpose": "Render one page for one source row in a sandboxed frame without saving it.",
+      "operations": [
+        "get_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_get",
+        "preview_programmatic_page_programmatic_campaigns__campaign_id__preview_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "ProgrammaticVariables",
+      "file": "components/programmatic-variables.tsx",
+      "purpose": "Template variables with source matches and per-variable fallback, character limit and cut rule; merges edits into the stored variable config.",
+      "operations": [
+        "get_programmatic_campaign_programmatic_campaigns__campaign_id__get",
+        "get_programmatic_campaign_variables_programmatic_campaigns__campaign_id__variables_get",
+        "update_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "ProgrammaticSource",
+      "file": "components/programmatic-source.tsx",
+      "purpose": "Source details with columns and first rows, switching to another list or table, and importing a sitemap as the source.",
+      "operations": [
+        "get_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_get",
+        "import_programmatic_sitemap_programmatic_campaigns__campaign_id__imports_sitemap_post",
+        "list_workbench_tables_workbench_tables_get",
+        "update_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "ProgrammaticSettings",
+      "file": "components/programmatic-settings.tsx",
+      "purpose": "Regeneration, publishing, search and link settings; sends only changed keys; confirms turning on automatic publishing.",
+      "operations": [
+        "get_programmatic_campaign_programmatic_campaigns__campaign_id__get",
+        "update_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useProgrammaticWorkspace",
+      "file": "hooks/use-programmatic-workspace.ts",
+      "purpose": "The workspace of one campaign through a shared cache entry, so a save on one tab refreshes the others.",
+      "operations": [
+        "get_programmatic_workspace_programmatic_campaigns__campaign_id__workspace_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/programmatic-types.ts",
+      "purpose": "Campaign, page and workspace types; the API's exact vocabularies; changed-fields diff, bulk target selection, variable-config merge and settings patch helpers."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/create-a-programmatic-campaign.ts",
+      "title": "Create a campaign and preview one page",
+      "when": "Setting up a page per row from a template page and a list; nothing is rendered or published."
+    },
+    {
+      "file": "recipes/render-and-follow.ts",
+      "title": "Render every page and follow the run",
+      "when": "After the campaign exists; free, but a campaign set to publish automatically needs a person's confirmation first."
+    },
+    {
+      "file": "recipes/review-then-publish.ts",
+      "title": "Read the publish numbers, then publish after a person agrees",
+      "when": "Putting rendered pages on the live site, which changes what visitors see."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "template-page",
+      "description": "A landing page with HTML and {{variables}} where each row's values go (create it with the pages block). The campaign's template cannot be changed later.",
+      "where": "api",
+      "verify": "GET /api/v1/landing-pages lists the page."
+    },
+    {
+      "id": "source",
+      "description": "A contact list or a Workbench table with a column for each {{variable}}. A variable with no matching column renders empty unless it has a fallback.",
+      "where": "api",
+      "verify": "GET /api/v1/programmatic-campaigns/{id}/variables shows every variable as found."
+    },
+    {
+      "id": "publishing",
+      "description": "Publishing needs a connected Cloudflare website or hosted publishing on the workspace; otherwise the publish call answers 500 'not configured'. Rendering needs neither.",
+      "where": "api",
+      "verify": "A publish of one test campaign succeeds, confirmed by a person."
+    },
+    {
+      "id": "campaign-scopes",
+      "description": "The key needs campaigns:read, campaigns:write, campaigns:delete and, for the page actions and publish, campaigns:run (separate from campaigns:write). Picking a list or table needs lists:read.",
+      "where": "api",
+      "verify": "g8.api.me.describeCurrentKey() lists the scopes."
+    },
+    {
+      "id": "proxy-allowlist",
+      "description": "Add \"programmatic-campaigns\", \"landing-pages\", \"workbench\" and \"lists\" to allowedPrefixes in app/api/g8/[...path]/route.ts.",
+      "where": "app",
+      "verify": "The route file's allowedPrefixes contains them."
+    }
+  ],
+  "scopes": [
+    "campaigns:delete",
+    "campaigns:read",
+    "campaigns:run",
+    "campaigns:write",
+    "lists:read"
+  ],
+  "defaults": [
+    {
+      "decision": "Data source",
+      "default": "A person picks the list or table; never guessed",
+      "askHuman": true
+    },
+    {
+      "decision": "Address pattern",
+      "default": "Left blank: the API's own {{company}}-{{first_name}}",
+      "askHuman": false
+    },
+    {
+      "decision": "Rendering",
+      "default": "Free; creates drafts. Never run on a campaign set to publish automatically without a person's confirmation",
+      "askHuman": false
+    },
+    {
+      "decision": "Publishing",
+      "default": "Never without a person confirming the number of pages",
+      "askHuman": true
+    },
+    {
+      "decision": "Stopping",
+      "default": "Unpublish the pages first; deleting a campaign does not take live pages down",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
+  }
+}

package/blocks/programmatic-pages/components/programmatic-campaign-form.tsx

@@ -0,0 +1,136 @@
+"use client";
+
+/**
+ * ProgrammaticCampaignForm: create a programmatic campaign (a template landing page plus a data source: one page per row) or
+ * edit one.
+ *
+ * SDK operations, in order:
+ *   1. listLandingPages (GET /landing-pages)                          read   the template choices (100 per read, offset paged)
+ *   2. the source choice: ProgrammaticSourceFields (lists, or listWorkbenchTables for a table source)
+ *   3. getProgrammaticCampaign (GET /programmatic-campaigns/{id})     read   edit only: the FULL record is read before the form shows
+ *   4. createProgrammaticCampaign (POST /programmatic-campaigns)      write  nothing is rendered yet; free
+ *   5. updateProgrammaticCampaign (PATCH /programmatic-campaigns/{id}) write only the fields that changed
+ * The template page is fixed once a campaign exists (the update takes none). The API only accepts an edit while the campaign is
+ * a draft or failed, so the form says so up front instead of failing on save. A blank URL pattern is left out and the API's own
+ * default is used. Nothing here renders or publishes a page.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
+import { useAllPages } from "@/g8/hooks/use-all-pages";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { asRec, num, rowsOf } from "@/g8/pages/lib/studio";
+import type { LandingPageRow, Rec } from "@/g8/pages/lib/studio";
+import { ProgrammaticSourceFields } from "./programmatic-source-fields";
+import type { SourceValue } from "./programmatic-source-fields";
+import { SOURCE_TYPES, campaignDiff, canEditCampaign, slugVariables, sourceComplete, sourceOf, wording } from "../lib/programmatic-types";
+import type { Campaign, CampaignDraft, SourceType } from "../lib/programmatic-types";
+
+export interface ProgrammaticCampaignFormProps {
+  /** Edit this campaign; omit to create a new one. */
+  campaign?: Campaign;
+  /** Called with the saved campaign. */
+  onSaved: (campaign: Campaign) => void;
+  onCancel?: () => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm disabled:opacity-50";
+const SLUG_DEFAULT = "{{company}}-{{first_name}}";
+const PAGE_READ = 100;
+const NAME_MAX = 200;
+
+/** Edit mode reads the full campaign first: a list row may omit fields, and saving a form seeded from it would blank them. */
+export function ProgrammaticCampaignForm({ campaign, onSaved, onCancel }: ProgrammaticCampaignFormProps) {
+  const full = useG8Query(
+    (signal) => g8Get<Campaign>(`/programmatic-campaigns/${encodeURIComponent(campaign!.id)}`, {}, { signal }).then((r) => r.data),
+    [campaign?.id],
+    { enabled: Boolean(campaign), key: ["programmatic", "detail", campaign?.id ?? ""], placeholderData: campaign },
+  );
+  if (!campaign) return <CampaignFields onSaved={onSaved} onCancel={onCancel} />;
+  if (full.error && (!full.data || full.isPlaceholderData)) return <ApiError error={full.error} title="Could not load this campaign" onRetry={() => void full.refetch()} />;
+  if (!full.data || full.isPlaceholderData || full.data.id !== campaign.id) return <Skeleton className="h-40 w-full" aria-label="Loading campaign" />;
+  return <CampaignFields key={full.data.id} campaign={full.data} onSaved={onSaved} onCancel={onCancel} />;
+}
+
+function CampaignFields({ campaign, onSaved, onCancel }: ProgrammaticCampaignFormProps) {
+  const editing = Boolean(campaign);
+  const was = campaign ? sourceOf(campaign) : { type: "", id: "", name: "" };
+  const locked = campaign ? !canEditCampaign(campaign) : false;
+  const [name, setName] = useState(campaign?.name ?? "");
+  const [templateId, setTemplateId] = useState(campaign?.template_page_id ?? "");
+  const [slug, setSlug] = useState(campaign?.slug_template ?? "");
+  const [src, setSrc] = useState<SourceValue>({
+    type: (SOURCE_TYPES.find((t) => t.value === was.type)?.value ?? "list") as SourceType,
+    listId: was.type === "list" && was.id ? Number(was.id) : null,
+    tableId: was.type !== "list" ? was.id : "",
+    tableName: was.name,
+  });
+  const { type: sourceType, listId, tableId, tableName } = src;
+  const draft: CampaignDraft = { name, slug_template: slug, source_type: sourceType, list_id: listId, table_id: tableId, table_name: tableName };
+
+  const templates = useAllPages<LandingPageRow>(async (page, signal) => {
+    const offset = (page - 1) * PAGE_READ;
+    const data = asRec((await g8Get("/landing-pages", { limit: PAGE_READ, offset: offset || undefined }, { signal })).data);
+    const rows = rowsOf<LandingPageRow>(data, "landing_pages");
+    const total = num(data.total);
+    return { rows, hasNext: total === undefined ? undefined : offset + rows.length < total };
+  }, [], { enabled: !editing, pageSize: PAGE_READ });
+  const valid = name.trim() !== "" && name.trim().length <= NAME_MAX && sourceComplete(draft) && (editing || templateId !== "");
+  const diff = campaign ? campaignDiff(campaign, draft) : {};
+  const save = useG8Mutation(async (): Promise<Campaign> => {
+    if (campaign) {
+      if (Object.keys(diff).length === 0) return campaign;
+      return (await g8Patch<Campaign>(`/programmatic-campaigns/${encodeURIComponent(campaign.id)}`, diff)).data;
+    }
+    const body: Rec = { name: name.trim(), template_page_id: templateId, data_source_type: sourceType };
+    if (sourceType === "list") body.list_id = listId;
+    else {
+      body.data_source_id = tableId;
+      if (tableName) body.data_source_name = tableName;
+    }
+    if (slug.trim()) body.slug_template = slug.trim();
+    return (await g8Post<Campaign>("/programmatic-campaigns", body)).data;
+  }, { onSuccess: onSaved, invalidates: (saved) => [["programmatic", "list"], ["programmatic", "detail", saved.id], ["programmatic", "workspace", saved.id]] });
+
+  const names = slugVariables(slug || SLUG_DEFAULT);
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (valid && !locked) void save.mutate(undefined); }}>
+      {locked ? <p role="status" className="text-muted-foreground bg-muted rounded-md p-2 text-sm">The API accepts edits while a campaign is a draft or has failed. This one is {wording(campaign?.status).toLowerCase()}: change its source, variables and settings from the other tabs.</p> : null}
+      <div>
+        <Label htmlFor="g8-pp-name" className="mb-1">Name</Label>
+        <Input id="g8-pp-name" value={name} maxLength={NAME_MAX} disabled={locked} onChange={(e) => setName(e.target.value)} placeholder="Integration pages" />
+      </div>
+      <div>
+        <Label htmlFor="g8-pp-template" className="mb-1">Template page</Label>
+        {editing ? (
+          <p className="text-muted-foreground text-sm">The template is fixed once a campaign exists. To use another template, make a new campaign.</p>
+        ) : (
+          <>
+            <select id="g8-pp-template" className={SELECT} value={templateId} onChange={(e) => setTemplateId(e.target.value)} disabled={templates.loading && templates.items.length === 0}>
+              <option value="">{templates.loading && templates.items.length === 0 ? "Loading pages" : "Choose a landing page"}</option>
+              {templates.items.map((p) => <option key={p.id} value={p.id}>{p.name} ({wording(p.status).toLowerCase()})</option>)}
+            </select>
+            {templates.error ? <ApiError error={templates.error} title="Could not load landing pages" onRetry={templates.refetch} /> : null}
+            <FirstNotice shown={templates.items.length} limit={PAGE_READ} noun="landing pages" force={templates.truncated} />
+            <p className="text-muted-foreground mt-1 text-xs">A landing page with HTML. Put {"{{variable}}"} where each row&apos;s value goes.</p>
+          </>
+        )}
+      </div>
+      <div>
+        <Label htmlFor="g8-pp-slug" className="mb-1">Page address pattern</Label>
+        <Input id="g8-pp-slug" value={slug} disabled={locked} onChange={(e) => setSlug(e.target.value)} placeholder={SLUG_DEFAULT} />
+        <p className="text-muted-foreground mt-1 text-xs">Built from each row: {names.map((n) => `{{${n}}}`).join(", ") || "no variables"}. {slug.trim() ? "" : "Left blank, the default pattern shown is used."}</p>
+      </div>
+      <ProgrammaticSourceFields value={src} onChange={setSrc} disabled={locked} currentName={was.name} />
+      {save.error ? <ApiError error={save.error} title={editing ? "Could not save the campaign" : "Could not create the campaign"} /> : null}
+      <div className="flex gap-2">
+        <Button type="submit" loading={save.loading} disabled={!valid || locked || (editing && Object.keys(diff).length === 0)}>{editing ? "Save changes" : "Create campaign"}</Button>
+        {onCancel ? <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+    </form>
+  );
+}