@graph8/sdk 0.373.0 → 0.374.0

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);
+}

package/blocks/quotes/README.md

@@ -11,6 +11,12 @@ Install with `npx @graph8/sdk add quotes`.
 | `QuoteViewer` | One quote with totals and status-based actions: send/resend, edit as draft, duplicate, delete. |
 | `SignatureStatus` | Envelope state, signers, activity, reminder. |
 | `QuoteLifecycleActions` | PDF download, archive and unarchive, and for a sent quote expire, revoke and mark accepted. Each risky action is confirmed. |
+| `QuoteTemplates` | Quote templates: create, edit (a full replace), delete; terms, validity, contract length, attached documents, preset lines. |
+| `QuoteSettings` | Org-wide quote settings: branding, terms, numbering, who quotes are sent as, billing provider, deal automation, saved terms. |
+| `QuoteDocuments` | The legal document library (NDA, MSA, other PDFs) that templates attach. |
+| `QuoteEvidence` | Internal PDF evidence on one quote: list, attach, download. |
+| `QuoteBatchActions` | Archive, expire or revoke the ticked quotes in one confirmed, id-addressed request (mounted by `QuoteList selectable`). |
+| `ManualProducts` | The org's own product catalogue: list, add, edit, retire. |
 | `CreateQuoteFromDeal` | A "Create quote from this deal" button (builder in a side sheet, then the saved quote). Pass it to `DealsScreen`'s `renderQuoteActions`. |
 
 ## Screens
@@ -26,6 +32,24 @@ Install with `npx @graph8/sdk add quotes`.
   destructive confirms) and **Mark accepted**. Mark accepted raises an invoice with your billing provider, so it is an
   external confirm that also requires an evidence type (signed offline, customer email, verbal authorization, payment
   received) and a note. Use it only when the customer paid or signed outside the product.
+- **Batch** (`QuoteList selectable`, on in the screen): tick quotes, then Archive, Expire or Revoke. The request carries the ticked quote
+  ids and nothing else (never a filter); a quote the action does not apply to (expire a draft, revoke a quote that is not out for
+  signature, archive an archived one) is left out of the request and out of the confirm count, and the confirm says how many were
+  left out. The result is read quote by quote ("N of M archived", with the reason for each skipped or failed one). Ticks clear when the
+  filter or page changes and prune to the quotes still listed after a reload. Max 200 per request.
+- **Templates tab**: list, create, edit and delete quote templates. Saving a template REPLACES it, and the API body cannot carry
+  accepted payment methods, marketing rights or the contract-start-on-signature setting, so a template that has any of those asks
+  first and names which ones the save resets. Delete is a destructive confirm (quotes already built from the template are unchanged).
+- **Settings tab**: org-wide settings and the document library. Only changed fields are sent. The API ignores a null, so a field that has
+  a value cannot be cleared from here: the form says so and holds Save instead of reporting a save that changed nothing. Changing who
+  quotes are sent as, the billing provider (Manual or Stripe only: QuickBooks, Xero and Chargebee are not built) or the deal automation
+  confirms first and states the effect. Document uploads take PDFs only, up to about 5 MB (the app proxy caps a whole request at 5 MiB;
+  the API allows 10 MB).
+- **Products tab**: the quotable catalogue, plus the manual products you add, edit (changed fields only) and retire (a soft delete; quotes
+  that already include the product keep the line item).
+- **Evidence tab** of an open quote: attach internal PDFs (checked before upload; the API has no delete, so an attached file stays) and
+  download them through the API's 60 second link.
+- **Preview email**: inside the send confirm, renders the exact email and attachments without sending anything.
 - The Deal tab of a quote offers "Create another quote" for the same deal.
 - **New quote** asks for the deal first (search by name, skipped when `dealId` is given because graph8 attaches every
   quote to a deal), then opens the builder (details, signer, line items from the quotable products, live totals).
@@ -56,7 +80,7 @@ The deal search calls `GET /deals`, so the key also needs `deals:read` and the p
 
 ## Prerequisites
 
-- `foundation` installed (and `deals`, which supplies the `dealId`); proxy `allowedPrefixes` include `quotes`, `quotable-products`, `quote-contacts`, `envelopes`.
+- `foundation` installed (and `deals`, which supplies the `dealId`); proxy `allowedPrefixes` include `quotes`, `quotable-products`, `quote-contacts`, `quote-templates`, `quote-settings`, `manual-products`, `envelopes` (derived from the block's operations; `doctor --fix-prefixes` adds them to an existing app). Templates, settings, documents and manual products need an organization admin key to change.
 - `where: "api"`: at least one quotable product.
 - `where: "app"`: quote settings (company legal name, terms, sender) filled in; Stripe connected for Stripe products and subscriptions.
 

package/blocks/quotes/block.json

@@ -10,15 +10,28 @@
     "send, resend and edit-as-draft behind confirms",
     "e-signature status with reminder",
     "quote lifecycle: PDF download, archive and unarchive, expire, revoke and mark accepted",
-    "create a quote from a deal anywhere with one button"
+    "create a quote from a deal anywhere with one button",
+    "quote templates: create, edit and delete, with attached documents and preset lines",
+    "org quote settings and the legal document library",
+    "internal PDF evidence on a quote",
+    "archive, expire or revoke several quotes at once, id-addressed and confirmed",
+    "manual product catalogue: add, edit and retire",
+    "preview the exact email before sending a quote"
   ],
   "dependsOn": [
     "deals"
   ],
   "operations": [
     "archive_quote_quotes__quote_id__archive_post",
+    "batch_quote_action_quotes_batch_post",
+    "create_manual_product_manual_products_post",
     "create_quote_quotes_post",
+    "create_quote_template_quote_templates_post",
+    "delete_manual_product_manual_products__product_id__delete",
+    "delete_quote_document_quote_settings_documents__doc_id__delete",
     "delete_quote_quotes__quote_id__delete",
+    "delete_quote_template_quote_templates__template_id__delete",
+    "download_quote_evidence_quotes__quote_id__evidence__evidence_id__get",
     "duplicate_quote_quotes__quote_id__duplicate_post",
     "edit_quote_as_draft_quotes__quote_id__edit_as_draft_post",
     "expire_quote_quotes__quote_id__expire_post",
@@ -27,22 +40,33 @@
     "get_deal_deals__deal_id__get",
     "get_quote_pdf_quotes__quote_id__pdf_get",
     "get_quote_quotes__quote_id__get",
+    "get_quote_settings_quote_settings_get",
     "list_deals_deals_get",
+    "list_manual_products_manual_products_get",
     "list_quotable_products_quotable_products_get",
+    "list_quote_documents_quote_settings_documents_get",
+    "list_quote_evidence_quotes__quote_id__evidence_get",
+    "list_quote_templates_quote_templates_get",
     "list_quotes_quotes_get",
     "mark_quote_accepted_quotes__quote_id__mark_accepted_post",
+    "preview_quote_send_quotes__quote_id__send_preview_post",
     "resend_envelope_envelopes__envelope_id__resend_post",
     "revoke_quote_quotes__quote_id__revoke_post",
     "search_quote_contacts_quote_contacts_get",
     "send_quote_quotes__quote_id__send_post",
     "unarchive_quote_quotes__quote_id__unarchive_post",
-    "update_quote_quotes__quote_id__patch"
+    "update_manual_product_manual_products__product_id__patch",
+    "update_quote_quotes__quote_id__patch",
+    "update_quote_settings_quote_settings_put",
+    "update_quote_template_quote_templates__template_id__put",
+    "upload_quote_document_quote_settings_documents_post",
+    "upload_quote_evidence_quotes__quote_id__evidence_post"
   ],
   "components": [
     {
       "name": "QuoteList",
       "file": "components/quote-list.tsx",
-      "purpose": "Quotes with a status filter, totals in the quote currency, and paging; optionally scoped to a deal or company.",
+      "purpose": "Quotes with a status filter, totals in the quote currency, and paging; optionally scoped to a deal or company. With selectable, ticked quotes can be archived, expired or revoked together.",
       "operations": [
         "list_quotes_quotes_get"
       ],
@@ -79,13 +103,14 @@
     {
       "name": "QuoteViewer",
       "file": "components/quote-viewer.tsx",
-      "purpose": "Read a quote with its totals and actions by status: send or resend for signature, edit as draft, duplicate, delete.",
+      "purpose": "Read a quote with its totals and actions by status: send or resend for signature, edit as draft, duplicate, delete. Previews the exact email from the send confirm.",
       "operations": [
         "get_quote_quotes__quote_id__get",
         "send_quote_quotes__quote_id__send_post",
         "edit_quote_as_draft_quotes__quote_id__edit_as_draft_post",
         "duplicate_quote_quotes__quote_id__duplicate_post",
-        "delete_quote_quotes__quote_id__delete"
+        "delete_quote_quotes__quote_id__delete",
+        "preview_quote_send_quotes__quote_id__send_preview_post"
       ],
       "tiers": [
         "read",
@@ -118,6 +143,93 @@
         "read"
       ]
     },
+    {
+      "name": "QuoteTemplates",
+      "file": "components/quote-templates.tsx",
+      "purpose": "Quote templates: list, create, edit (a full replace) and delete; terms, validity, contract length, attached documents and preset lines. Delete is confirmed, and so is a save that would reset settings the API cannot carry.",
+      "operations": [
+        "list_quote_templates_quote_templates_get",
+        "create_quote_template_quote_templates_post",
+        "update_quote_template_quote_templates__template_id__put",
+        "delete_quote_template_quote_templates__template_id__delete",
+        "list_quote_documents_quote_settings_documents_get",
+        "list_quotable_products_quotable_products_get"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "QuoteSettings",
+      "file": "components/quote-settings.tsx",
+      "purpose": "Org-wide quote settings (branding, terms, numbering, sender identity, billing provider, deal automation, required billing details, saved terms). Sends only changed fields, refuses to pretend a value was cleared, and confirms changes to sender identity, billing provider and deal automation.",
+      "operations": [
+        "get_quote_settings_quote_settings_get",
+        "update_quote_settings_quote_settings_put"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "QuoteDocuments",
+      "file": "components/quote-documents.tsx",
+      "purpose": "The legal document library (NDA, MSA, other PDFs): list, upload with client-side PDF and size checks, delete behind a confirm.",
+      "operations": [
+        "list_quote_documents_quote_settings_documents_get",
+        "upload_quote_document_quote_settings_documents_post",
+        "delete_quote_document_quote_settings_documents__doc_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "QuoteEvidence",
+      "file": "components/quote-evidence.tsx",
+      "purpose": "Internal PDF evidence on a quote: list, attach (checked before upload; cannot be removed afterwards) and download via the API's short-lived link.",
+      "operations": [
+        "list_quote_evidence_quotes__quote_id__evidence_get",
+        "upload_quote_evidence_quotes__quote_id__evidence_post",
+        "download_quote_evidence_quotes__quote_id__evidence__evidence_id__get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "QuoteBatchActions",
+      "file": "components/quote-batch-actions.tsx",
+      "purpose": "Archive, expire or revoke the ticked quotes in one confirmed request addressed by quote id; reads the per-quote result.",
+      "operations": [
+        "batch_quote_action_quotes_batch_post"
+      ],
+      "tiers": [
+        "external"
+      ]
+    },
+    {
+      "name": "ManualProducts",
+      "file": "components/manual-products.tsx",
+      "purpose": "The org's own product catalogue: list (including inactive), add, edit changed fields only, and retire behind a confirm.",
+      "operations": [
+        "list_manual_products_manual_products_get",
+        "create_manual_product_manual_products_post",
+        "update_manual_product_manual_products__product_id__patch",
+        "delete_manual_product_manual_products__product_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
     {
       "name": "ProductCatalog",
       "file": "components/quote-related.tsx",
@@ -180,6 +292,10 @@
     {
       "file": "lib/quotes.ts",
       "purpose": "Line-item math in cents, product and line types, request line mapping, status labels."
+    },
+    {
+      "file": "lib/quote-admin.ts",
+      "purpose": "Rules for the admin screens: template save body and what a save resets, settings diff (only changed fields, what the API cannot clear), PDF upload checks, batch eligibility and result reading."
     }
   ],
   "recipes": [
@@ -223,7 +339,8 @@
     "deals:read",
     "quotes:delete",
     "quotes:read",
-    "quotes:run"
+    "quotes:run",
+    "quotes:write"
   ],
   "defaults": [
     {