@graph8/sdk 0.373.0 → 0.374.0

package/blocks/quotes/lib/quote-admin.ts

@@ -0,0 +1,264 @@
+"use client";
+
+/**
+ * Pure helpers for the quote administration screens: templates, org settings, the document library, evidence
+ * uploads, batch actions and manual products. No network, so the rules below are unit-tested directly.
+ *
+ * What the API really does (read from the handlers, not assumed):
+ *   - PUT /quote-templates/{id} REPLACES the template. A field left out is cleared, so the form always sends the whole
+ *     template. The API body has no `accepted_payment_methods`, `marketing_rights` or `contract_start_on_signature`,
+ *     so saving through the API resets those three (see `fieldsLostOnTemplateSave`).
+ *   - PUT /quote-settings only writes non-null values: a field that has a value cannot be cleared through the API
+ *     (see `unclearableSettings`). Everything it does accept is a partial update, so we send only what changed.
+ *   - Uploads are PDF only. The API allows 10 MB, but the app proxy caps a whole request at 5 MiB (413 beyond that),
+ *     so the screens refuse anything over `UPLOAD_LIMIT_BYTES` up front.
+ *   - POST /quotes/batch takes `quote_ids` (1 to 200) and an action of archive, expire or revoke, and answers a row per
+ *     id (`success`, `skipped` or `error`). A 200 means the batch ran, not that every quote moved. Expire skips a draft or
+ *     a quote with a final outcome; revoke skips anything not sent, viewed or link generated; archive skips an archived quote.
+ */
+import { asRec, text, type LineItem, type Rec } from "./quotes";
+
+/** The app proxy rejects a request body over 5 MiB (blocks/_foundation/server/proxy.ts DEFAULT_MAX_BODY). */
+export const UPLOAD_LIMIT_BYTES = 4_800_000;
+export const UPLOAD_LIMIT_LABEL = "about 5 MB";
+export const BATCH_MAX = 200;
+
+/** Why a file cannot be uploaded as a quote PDF, or null when it can. */
+export function pdfProblem(file: File | null | undefined): string | null {
+  if (!file) return "Choose a PDF file first.";
+  if (!file.name.toLowerCase().endsWith(".pdf")) return "Only PDF files are accepted.";
+  if (file.size === 0) return "That file is empty.";
+  if (file.size > UPLOAD_LIMIT_BYTES) {
+    return `That file is ${(file.size / 1_000_000).toFixed(1)} MB. This app accepts PDFs up to ${UPLOAD_LIMIT_LABEL} (the whole request is capped); compress the PDF and try again.`;
+  }
+  return null;
+}
+
+export function fileSize(bytes: unknown): string {
+  const n = Number(bytes);
+  if (!Number.isFinite(n) || n <= 0) return "";
+  return n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1000))} KB`;
+}
+
+// ---------------------------------------------------------------------------
+// Templates
+// ---------------------------------------------------------------------------
+
+export const DURATION_UNITS = ["months", "weeks", "days"] as const;
+export type DurationUnit = (typeof DURATION_UNITS)[number];
+
+export interface TemplateDraft {
+  name: string;
+  description: string;
+  default_payment_terms: string;
+  default_valid_days: string;
+  terms_override: string;
+  is_default: boolean;
+  contract_duration_value: string;
+  contract_duration_unit: DurationUnit | "";
+  document_ids: string[];
+  lines: LineItem[];
+}
+
+export const emptyTemplateDraft = (): TemplateDraft => ({
+  name: "", description: "", default_payment_terms: "", default_valid_days: "", terms_override: "", is_default: false,
+  contract_duration_value: "", contract_duration_unit: "", document_ids: [], lines: [],
+});
+
+const numText = (v: unknown): string => (v == null || v === "" ? "" : String(Number(v)));
+
+/** A stored template row -> the form. A template that only has the older `contract_months` shows it as months. */
+export function draftFromTemplate(row: Rec, lines: LineItem[]): TemplateDraft {
+  const hasDuration = row.contract_duration_value != null;
+  const unit = text(row.contract_duration_unit);
+  return {
+    name: text(row.name),
+    description: text(row.description),
+    default_payment_terms: text(row.default_payment_terms),
+    default_valid_days: numText(row.default_valid_days),
+    terms_override: text(row.terms_override),
+    is_default: row.is_default === true,
+    contract_duration_value: hasDuration ? numText(row.contract_duration_value) : numText(row.contract_months),
+    contract_duration_unit: hasDuration ? ((DURATION_UNITS as readonly string[]).includes(unit) ? (unit as DurationUnit) : "months") : row.contract_months != null ? "months" : "",
+    document_ids: Array.isArray(row.document_ids) ? row.document_ids.map(String) : [],
+    lines,
+  };
+}
+
+/** What is wrong with the draft, in the order the form shows it. Empty means it can be saved. */
+export function templateProblems(d: TemplateDraft): string[] {
+  const out: string[] = [];
+  if (!d.name.trim()) out.push("Give the template a name.");
+  if (d.name.trim().length > 255) out.push("The name can be at most 255 characters.");
+  if (d.default_valid_days) {
+    const n = Number(d.default_valid_days);
+    if (!Number.isInteger(n) || n < 1 || n > 365) out.push("Valid days must be a whole number from 1 to 365.");
+  }
+  const hasValue = d.contract_duration_value !== "";
+  if (hasValue !== (d.contract_duration_unit !== "")) out.push("Set both the contract length and its unit, or neither.");
+  if (hasValue) {
+    const n = Number(d.contract_duration_value);
+    const max = d.contract_duration_unit === "months" ? 120 : 3650;
+    if (!Number.isFinite(n) || n < 0.1 || n > max) out.push(`A contract length in ${d.contract_duration_unit || "months"} must be from 0.1 to ${max}.`);
+  }
+  return out;
+}
+
+/** The full PUT/POST body. Blank optional fields are sent as null so a save clears them, which is what PUT means. */
+export function templateBody(d: TemplateDraft, lines: Rec[]): Rec {
+  const hasLength = d.contract_duration_value !== "" && d.contract_duration_unit !== "";
+  const length = hasLength ? Number(d.contract_duration_value) : null;
+  return {
+    name: d.name.trim(),
+    description: d.description.trim() || null,
+    default_payment_terms: d.default_payment_terms || null,
+    default_valid_days: d.default_valid_days ? Number(d.default_valid_days) : null,
+    terms_override: d.terms_override.trim() || null,
+    is_default: d.is_default,
+    contract_duration_value: length,
+    contract_duration_unit: hasLength ? d.contract_duration_unit : null,
+    contract_months: hasLength && d.contract_duration_unit === "months" ? length : null,
+    document_ids: d.document_ids,
+    default_line_items: lines,
+  };
+}
+
+/**
+ * Settings the app lets people set on a template that the API's PUT body cannot carry, and that therefore reset when the
+ * template is saved from here. Used to warn before saving, never to guess: it reads the stored row.
+ */
+export function fieldsLostOnTemplateSave(row: Rec): string[] {
+  const out: string[] = [];
+  if (Array.isArray(row.accepted_payment_methods) && row.accepted_payment_methods.length > 0) out.push("accepted payment methods");
+  if (Array.isArray(row.marketing_rights) && row.marketing_rights.length > 0) out.push("marketing rights");
+  if (row.contract_start_on_signature === false) out.push("the contract starts on signature setting (it goes back to on)");
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Settings
+// ---------------------------------------------------------------------------
+
+export type SettingsField =
+  | "company_name" | "company_logo_url" | "company_address" | "company_phone" | "company_email" | "default_terms" | "default_privacy"
+  | "terms_url" | "privacy_url" | "footer_text" | "accent_color" | "quote_number_prefix" | "default_payment_terms" | "sender_name" | "sender_email"
+  | "sender_mode" | "default_billing_provider" | "quote_acceptance_roam_channel_id" | "quote_acceptance_roam_channel_name";
+export type SettingsBool = "auto_close_deal_on_acceptance" | "auto_advance_deal_on_quote_send" | "quote_acceptance_roam_notifications_enabled";
+
+export const TEXT_FIELDS: SettingsField[] = [
+  "company_name", "company_logo_url", "company_address", "company_phone", "company_email", "default_terms", "default_privacy", "terms_url", "privacy_url",
+  "footer_text", "accent_color", "quote_number_prefix", "default_payment_terms", "sender_name", "sender_email", "sender_mode", "default_billing_provider",
+  "quote_acceptance_roam_channel_id", "quote_acceptance_roam_channel_name",
+];
+export const BOOL_FIELDS: SettingsBool[] = ["auto_close_deal_on_acceptance", "auto_advance_deal_on_quote_send", "quote_acceptance_roam_notifications_enabled"];
+export const BILLING_FIELDS = ["legal_name", "primary_email", "billing_email", "address"] as const;
+/** The billing providers that actually provision on acceptance. QuickBooks, Xero and Chargebee are registered stubs. */
+export const BILLING_PROVIDERS: Array<[string, string]> = [["none", "Manual (finance bills it elsewhere)"], ["stripe", "Stripe (invoice or subscription on acceptance)"]];
+
+export interface TermsEntry { name: string; payment_terms: string; content: string }
+
+export interface SettingsDraft {
+  text: Record<SettingsField, string>;
+  flags: Record<SettingsBool, boolean>;
+  default_valid_days: string;
+  required_billing_fields: string[];
+  terms_library: TermsEntry[];
+}
+
+export function draftFromSettings(row: Rec): SettingsDraft {
+  const t = {} as Record<SettingsField, string>;
+  for (const k of TEXT_FIELDS) t[k] = text(row[k]);
+  const f = {} as Record<SettingsBool, boolean>;
+  for (const k of BOOL_FIELDS) f[k] = row[k] === true;
+  const lib = Array.isArray(row.terms_library) ? row.terms_library : [];
+  return {
+    text: t, flags: f,
+    default_valid_days: numText(row.default_valid_days),
+    required_billing_fields: Array.isArray(row.required_billing_fields) ? row.required_billing_fields.map(String) : [],
+    terms_library: lib.map((e) => ({ name: text(asRec(e).name), payment_terms: text(asRec(e).payment_terms), content: text(asRec(e).content) })),
+  };
+}
+
+const sameList = (a: unknown[], b: unknown[]) => a.length === b.length && a.every((x, i) => JSON.stringify(x) === JSON.stringify(b[i]));
+
+/** Only the fields that differ from the loaded settings. A field that was blank and is still blank is not sent. */
+export function settingsChanges(was: SettingsDraft, now: SettingsDraft): Rec {
+  const out: Rec = {};
+  for (const k of TEXT_FIELDS) if (now.text[k] !== was.text[k] && now.text[k].trim() !== "") out[k] = now.text[k].trim();
+  for (const k of BOOL_FIELDS) if (now.flags[k] !== was.flags[k]) out[k] = now.flags[k];
+  if (now.default_valid_days !== was.default_valid_days && now.default_valid_days !== "") out.default_valid_days = Number(now.default_valid_days);
+  if (!sameList(now.required_billing_fields, was.required_billing_fields)) out.required_billing_fields = now.required_billing_fields;
+  if (!sameList(now.terms_library, was.terms_library)) out.terms_library = now.terms_library.map((e) => ({ name: e.name.trim(), payment_terms: e.payment_terms, content: e.content }));
+  return out;
+}
+
+/** Fields that had a value and are now blank: the API ignores null, so the save would silently keep the old value. */
+export function unclearableSettings(was: SettingsDraft, now: SettingsDraft): string[] {
+  const out: string[] = [];
+  for (const k of TEXT_FIELDS) if (was.text[k].trim() !== "" && now.text[k].trim() === "") out.push(k);
+  if (was.default_valid_days !== "" && now.default_valid_days === "") out.push("default_valid_days");
+  return out;
+}
+
+export function settingsProblems(now: SettingsDraft): string[] {
+  const out: string[] = [];
+  const days = Number(now.default_valid_days);
+  if (now.default_valid_days && (!Number.isInteger(days) || days < 1)) out.push("Default valid days must be a whole number of at least 1.");
+  if (now.text.sender_email && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(now.text.sender_email.trim())) out.push("The sender email is not a valid address.");
+  if (now.text.company_email && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(now.text.company_email.trim())) out.push("The company email is not a valid address.");
+  if (now.terms_library.some((e) => !e.name.trim())) out.push("Every saved terms entry needs a name.");
+  return out;
+}
+
+export const FIELD_LABEL: Record<string, string> = {
+  company_name: "Company name", company_logo_url: "Logo URL", company_address: "Company address", company_phone: "Company phone", company_email: "Company email",
+  default_terms: "Default terms", default_privacy: "Default privacy text", terms_url: "Terms URL", privacy_url: "Privacy URL", footer_text: "Footer text", accent_color: "Accent color",
+  quote_number_prefix: "Quote number prefix", default_payment_terms: "Default payment terms", sender_name: "Sender name", sender_email: "Sender email", sender_mode: "Who quotes are sent as",
+  default_billing_provider: "Billing provider", default_valid_days: "Default valid days", quote_acceptance_roam_channel_id: "Roam channel id", quote_acceptance_roam_channel_name: "Roam channel name",
+};
+
+/** What a settings save does beyond storing text, so the confirm can say it. Empty means a plain save needs no confirm. */
+export function settingsEffects(changes: Rec, was: SettingsDraft): string[] {
+  const out: string[] = [];
+  if ("sender_email" in changes || "sender_name" in changes || "sender_mode" in changes) out.push("Every quote email sent from now on goes out under the new sender identity.");
+  if ("default_billing_provider" in changes) {
+    out.push(changes.default_billing_provider === "stripe"
+      ? "Quotes signed from now on create a Stripe customer, and a subscription or invoice, in the connected Stripe account."
+      : "Quotes signed from now on create no invoice or subscription: finance bills them elsewhere.");
+  }
+  if ("auto_close_deal_on_acceptance" in changes) out.push(changes.auto_close_deal_on_acceptance ? "An accepted quote moves its deal to Closed Won." : "An accepted quote no longer moves its deal to Closed Won.");
+  if ("auto_advance_deal_on_quote_send" in changes) out.push(changes.auto_advance_deal_on_quote_send ? "Sending a quote moves an earlier open deal to Proposal Sent." : "Sending a quote no longer moves the deal to Proposal Sent.");
+  void was;
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Batch actions
+// ---------------------------------------------------------------------------
+
+export type BatchAction = "archive" | "expire" | "revoke";
+
+const NOT_EXPIRABLE = new Set(["draft", "accepted", "expired", "declined", "voided", "completed", "archived"]);
+const REVOCABLE = new Set(["sent", "viewed", "link_generated"]);
+
+/**
+ * Whether a batch action applies to a quote with this status (the same rules the API applies row by row, so a quote it
+ * would only skip is left out of the request and out of the confirm count). Archive: not already archived. Expire: not a
+ * draft or already final. Revoke: out for signature (sent, viewed or link generated).
+ */
+export function batchEligible(action: BatchAction, row: Rec): boolean {
+  const status = text(row.status);
+  if (action === "archive") return status !== "archived" && !row.archived_at && row.is_archived !== true && row.archived !== true;
+  if (action === "expire") return status !== "" && !NOT_EXPIRABLE.has(status);
+  return REVOCABLE.has(status);
+}
+
+export interface BatchOutcome { quote_id: string; status: string; detail?: string }
+
+/** Read the per-row answer of POST /quotes/batch. */
+export function batchOutcomes(res: unknown): BatchOutcome[] {
+  const data = asRec(asRec(res).data ?? res);
+  return (Array.isArray(data.results) ? data.results : []).map((r) => ({ quote_id: text(asRec(r).quote_id), status: text(asRec(r).status), detail: text(asRec(r).detail) || undefined }));
+}
+
+export const BATCH_REASON: Record<string, string> = { not_found: "no longer exists", forbidden: "you cannot change it", invalid_id: "not a valid id" };

package/blocks/sequencer/README.md

@@ -20,6 +20,37 @@ deep-linkable (`?id=` the sequence, `?dtab=` the tab, `?step=` a step, `?enrollm
 - **`SequenceEnrollments`**: each enrolled contact is a record (state, step, the full contact); pause directly,
   resume confirmed.
 
+**Managing a sequence (new).** Everything a sequence needs after it is built is reachable from the screen:
+
+- **Edit** (`SequenceEditForm`, in the detail's action row): rename it and change its description, stop-on-reply,
+  same-thread and pick-up-new-contacts settings. The form loads the sequence first, saves only the fields you changed
+  (a partial `PATCH`), and confirms (**external**: a live sequence's contacts are affected). The audience list cannot be
+  changed after creation (the API has no way).
+- **Sync audience**: re-pulls the audience list so contacts added since launch are enrolled (**external**, confirmed;
+  shown for live and paused sequences).
+- **Delete sequence**: **destructive**, confirmed. The API's `DELETE` is a soft delete identical to archive (the sequence
+  stops and is hidden, and cannot be restored through the API); the Archive button stays for backwards compatibility.
+- **Senders** tab (`SequenceSendersPanel`): the mailboxes, numbers and LinkedIn accounts the sequence sends from, with
+  remove (**destructive**, confirmed; the dialog says when it is the only sender of that kind).
+- **Remove from sequence** on an enrolled contact (`WithdrawContactButton`): takes one contact out of this sequence,
+  recording removed / completed / not interested (**destructive**, confirmed; never "all sequences").
+- **Templates** (header button, `SequenceTemplates` and `StepTemplates`): sequence templates (list, create, edit, archive,
+  restore) and step templates (the same, plus an AI draft of a batch: **billable**, confirmed, nothing saved until you keep
+  one). **Use template** opens the new-sequence sheet with the template's name and steps filled in; you add the audience
+  list and senders. In the builder, **From a step template** inserts one step. **Save as template** (detail) copies a
+  sequence's steps. A template is a copy: it never changes a sequence built from it.
+- **AI help on a step** (`StepAiAssist`, inside the builder's step form): improve the instructions of an AI-written email,
+  and preview a draft for one contact (email or LinkedIn). Every AI call is **billable** and confirmed; the email draft
+  shows the exact credit estimate (`estimateEmailDraft`, free) first. Nothing is sent: the draft is shown, and "Use as my
+  copy" writes it into the step as plain copy you can edit.
+
+Not offered, with the reason: reordering the steps of a saved sequence (the API has no reorder operation and
+`updateSequenceStep` has no order field; unsaved steps can still be moved); linking a sequence to a campaign
+(`linkSequenceCampaign`, because `GET /sequences/{id}` does not return the current link, so the UI could not show it);
+`setSequenceStatus` and `terminateSequence` (raw status writes; pause, resume, archive and delete already cover them);
+`generateSequenceSpintax`, `placeVoiceTestCall` (rings a real phone), `getSequenceReports`, `getSequenceRoutingSummary`,
+`listSequenceContactIds`, schedules, WhatsApp/SMS templates.
+
 Slot props: `toolbarActions`, `renderDetailActions(sequence)`, `extraDetailTabs`, `ownerEmail`. Needs a connected
 sender mailbox and a contact list (see Prerequisites). `SequenceList` gained an optional `onChanged`; `EnrollDialog`
 an optional `note`.
@@ -37,6 +68,13 @@ the enrollments page being shown (the API has no single-enrollment read), so a l
 | `StepEditor` | One step's form, with the rules the API only enforces at send time. | read |
 | `EnrollDialog` | Confirm and enroll contacts, with the recipient count and a deliverability warning. | read, external |
 | `SequenceStats` | Totals, per-step progress, skip reasons, per-contact state with pause and resume. | read, write, external |
+| `SequenceEditForm` | Rename and edit a sequence's settings; loads first, sends changed fields only, confirmed. | read, external |
+| `SequenceManageActions` | Edit, sync audience, save as template, delete. | read, write, external, destructive |
+| `SequenceSendersPanel` | A sequence's senders, with remove. | read, destructive |
+| `SequenceTemplates` | Sequence templates: list, create, edit, archive, restore, use. | read, write, destructive |
+| `StepTemplates` (+ `StepTemplatePicker`) | Step templates: list, create, edit, archive, restore, AI drafts; insert one into a sequence. | read, write, billable, destructive |
+| `StepAiAssist` | AI help for one step: improve instructions, preview a draft for a contact. | read, billable |
+| `WithdrawContactButton` | Take one contact out of one sequence, recording the outcome. | write |
 
 Launch, pause, resume, enroll and step edits reach or change what real people receive, so each opens
 `ConfirmSpendDialog` first (with the recipient count where it applies). Archive is destructive and the API cannot
@@ -89,6 +127,8 @@ un-archive.
 ## Defaults (do not ask the human)
 
 - Two days between steps; stop on reply; the person writes the email copy.
+- AI copy is opt-in and always previewed: nothing is drafted without a confirm that says it uses credits, and a draft is
+  never sent or saved until the person uses it.
 - **Ask the human**: who to enroll and when to launch. Never launch or enroll without approval of the count.
 - SMS and WhatsApp steps exist in the API (`SMS`, `WHATSAPP`, `message_body`) but this block's builder covers email, LinkedIn, call and call task.
 
@@ -124,6 +164,20 @@ un-archive.
 | `pause_sequence_contact_sequences__sequence_id__contacts__contact_id__pause_post` | POST /sequences/{sequence_id}/contacts/{contact_id}/pause | write | SequenceStats |
 | `resume_sequence_contact_sequences__sequence_id__contacts__contact_id__resume_post` | POST /sequences/{sequence_id}/contacts/{contact_id}/resume | external | SequenceStats |
 
+| `update_sequence_sequences__sequence_id__patch` | PATCH /sequences/{sequence_id} | external | SequenceEditForm (changed fields only) |
+| `delete_sequence_sequences__sequence_id__delete` | DELETE /sequences/{sequence_id} | destructive | SequenceManageActions |
+| `sync_sequence_sequences__sequence_id__sync_post` | POST /sequences/{sequence_id}/sync | external | SequenceManageActions |
+| `remove_sequence_channel_sequences__sequence_id__channels__sequence_channel_id__delete` | DELETE /sequences/{sequence_id}/channels/{sequence_channel_id} | destructive | SequenceSendersPanel |
+| `list/create/update_sequence_template(s)`, `archive_sequence_template` | GET, POST /sequencer/templates/sequences; PATCH .../{id} and .../{id}/archive | read, write, destructive | SequenceTemplates, SequenceManageActions |
+| `list/create/update_step_template(s)`, `archive_step_template` | GET, POST /sequencer/templates/steps; PATCH .../{id} and .../{id}/archive | read, write, destructive | StepTemplates |
+| `generate_step_templates_sequencer_templates_steps_generate_post` | POST /sequencer/templates/steps/generate | billable | StepTemplates |
+| `list_sequencer_textual_agents_sequencer_agents_textual_get` | GET /sequencer/agents/textual | read | StepTemplates, StepAiAssist |
+| `improve_step_instruction_sequencer_content_instructions_improve_post` | POST /sequencer/content/instructions/improve | billable | StepAiAssist |
+| `estimate_email_draft_sequencer_content_email_estimate_post` | POST /sequencer/content/email/estimate | read (free) | StepAiAssist |
+| `draft_email_sequencer_content_email_generate_post` | POST /sequencer/content/email/generate | billable | StepAiAssist |
+| `draft_linkedin_message_sequencer_content_linkedin_generate_post` | POST /sequencer/content/linkedin/generate | billable | StepAiAssist |
+| `withdraw_contacts_from_sequences_contacts_withdraw_from_sequences_post` | POST /contacts/withdraw-from-sequences | write | WithdrawContactButton |
+
 Recipes (`recipes/`): `create-multichannel-sequence.ts`, `launch-and-enroll.ts`, `sequence-report.ts`, `pause-when-unsafe.ts`.
 
 ## Cross-block glue
@@ -131,3 +185,4 @@ Recipes (`recipes/`): `create-multichannel-sequence.ts`, `launch-and-enroll.ts`,
 - `AddToSequenceButton` (`components/add-to-sequence-button.tsx`): "Add to sequence" for any selection of contacts (live sequences only, then the enroll dialog with its preflight and confirmation). `SequencesScreen` gains optional `onOpenContact`: an enrolled person gets an "Open in contacts" button.
 
 - `RecordSequencesTab` (`components/record-sequences-tab.tsx`): a contact's enrollments with state and step (`getContactSequences`, the API's 50 most recent, with a notice when full), `AddToSequenceButton`, and a confirmed Withdraw from one sequence (`withdrawContactsFromSequences`, needs `contacts:write`). `extraDetailTabs` entry for ContactsScreen.
+- `SequenceCampaignLink` (`components/sequence-campaign-link.tsx`): which campaign a sequence belongs to. Shows the linked campaign with "Open campaign" and "Unlink campaign" (destructive confirm; both records are kept), or a picker to link one. Use it in `SequencesScreen.renderDetailActions`; the row it receives carries `campaign_builder_campaign_id`.

package/blocks/sequencer/block.json

@@ -2,12 +2,16 @@
   "$schema": "../block.schema.json",
   "id": "sequencer",
   "title": "Sequencer",
-  "summary": "Build multi-channel outreach sequences (email, LinkedIn, calls), launch and pause them, enroll contacts, and read performance.",
+  "summary": "Build multi-channel outreach sequences, launch, pause, rename and delete them, start from templates, get AI help with copy, enroll and withdraw contacts, and read performance.",
   "features": [
     "multi-channel step builder with send-time rule checks",
     "launch, pause, resume, duplicate and archive with recipient-count confirmation",
     "enroll contacts with deliverability warning",
-    "per-step stats, skip reasons and per-contact control"
+    "per-step stats, skip reasons and per-contact control",
+    "rename, edit, sync and delete a sequence (confirmed)",
+    "sequence and step templates, and AI-drafted step templates (billable, confirmed)",
+    "AI help on a step: improve instructions, preview a draft for a contact (billable, confirmed)",
+    "remove a sender from a sequence, withdraw one contact"
   ],
   "dependsOn": [
     "lists",
@@ -18,15 +22,28 @@
     "add_sequence_channels_sequences__sequence_id__channels_post",
     "add_sequence_steps_sequences__sequence_id__steps_post",
     "archive_sequence_sequences__sequence_id__archive_post",
+    "archive_sequence_template_sequencer_templates_sequences__sequence_template_id__archive_patch",
+    "archive_step_template_sequencer_templates_steps__step_template_id__archive_patch",
     "create_sequence_sequences_post",
+    "create_sequence_template_sequencer_templates_sequences_post",
+    "create_step_template_sequencer_templates_steps_post",
+    "delete_sequence_sequences__sequence_id__delete",
     "delete_sequence_step_sequences__sequence_id__steps__step_id__delete",
+    "draft_email_sequencer_content_email_generate_post",
+    "draft_linkedin_message_sequencer_content_linkedin_generate_post",
     "duplicate_sequence_sequences__sequence_id__duplicate_post",
+    "estimate_email_draft_sequencer_content_email_estimate_post",
+    "generate_step_templates_sequencer_templates_steps_generate_post",
+    "get_campaign_campaigns__campaign_id__get",
     "get_contact_sequences_contacts__contact_id__sequences_get",
     "get_outreach_connection_integrations_linkedin_outreach_connection_get",
     "get_safe_to_send_deliverability_safe_to_send_get",
     "get_sequence_analytics_sequences__sequence_id__analytics_get",
     "get_sequence_sequences__sequence_id__get",
     "get_sequence_stats_sequences__sequence_id__stats_get",
+    "improve_step_instruction_sequencer_content_instructions_improve_post",
+    "link_sequence_campaign_sequences__sequence_id__campaign_put",
+    "list_campaigns_for_picker_campaigns_picker_get",
     "list_contacts_contacts_get",
     "list_linkedin_accounts_sequencer_channels_linkedin_accounts_get",
     "list_lists_lists_get",
@@ -34,15 +51,24 @@
     "list_sequence_channels_sequences__sequence_id__channels_get",
     "list_sequence_contacts_sequences__sequence_id__contacts_get",
     "list_sequence_steps_sequences__sequence_id__steps_get",
+    "list_sequence_templates_sequencer_templates_sequences_get",
     "list_sequencer_phone_numbers_sequencer_channels_phone_numbers_get",
+    "list_sequencer_textual_agents_sequencer_agents_textual_get",
     "list_sequences_sequences_get",
+    "list_step_templates_sequencer_templates_steps_get",
     "pause_sequence_contact_sequences__sequence_id__contacts__contact_id__pause_post",
     "pause_sequence_sequences__sequence_id__pause_post",
     "preview_sequence_sequences__sequence_id__preview_get",
+    "remove_sequence_channel_sequences__sequence_id__channels__sequence_channel_id__delete",
     "resume_sequence_contact_sequences__sequence_id__contacts__contact_id__resume_post",
     "resume_sequence_sequences__sequence_id__resume_post",
     "run_sequence_sequences__sequence_id__run_post",
+    "sync_sequence_sequences__sequence_id__sync_post",
+    "unlink_sequence_campaign_sequences__sequence_id__campaign_delete",
+    "update_sequence_sequences__sequence_id__patch",
     "update_sequence_step_sequences__sequence_id__steps__step_id__patch",
+    "update_sequence_template_sequencer_templates_sequences__sequence_template_id__patch",
+    "update_step_template_sequencer_templates_steps__step_template_id__patch",
     "withdraw_contacts_from_sequences_contacts_withdraw_from_sequences_post"
   ],
   "components": [
@@ -94,7 +120,7 @@
     {
       "name": "StepEditor",
       "file": "components/step-editor.tsx",
-      "purpose": "Controlled form for one step with the rules the API only enforces at send time; shows LinkedIn sender readiness.",
+      "purpose": "Controlled form for one step with the rules the API only enforces at send time; shows LinkedIn sender readiness. Optional renderAssist slot for AI help.",
       "operations": [
         "get_outreach_connection_integrations_linkedin_outreach_connection_get"
       ],
@@ -133,10 +159,116 @@
         "external"
       ]
     },
+    {
+      "name": "SequenceEditForm",
+      "file": "components/sequence-edit-form.tsx",
+      "purpose": "Rename a sequence and change its settings (description, stop on reply, same thread, new contacts). Loads the record first, saves only the changed fields, and confirms before changing a sequence that may be live.",
+      "operations": [
+        "get_sequence_sequences__sequence_id__get",
+        "update_sequence_sequences__sequence_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "SequenceManageActions",
+      "file": "components/sequence-manage-actions.tsx",
+      "purpose": "Edit, sync the audience list (confirmed), save as template and delete (confirmed) for one sequence.",
+      "operations": [
+        "create_sequence_template_sequencer_templates_sequences_post",
+        "delete_sequence_sequences__sequence_id__delete",
+        "list_sequence_steps_sequences__sequence_id__steps_get",
+        "sync_sequence_sequences__sequence_id__sync_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SequenceSendersPanel",
+      "file": "components/sequence-senders-panel.tsx",
+      "purpose": "The senders (mailboxes, numbers, LinkedIn accounts) a sequence sends from, with remove (confirmed).",
+      "operations": [
+        "list_sequence_channels_sequences__sequence_id__channels_get",
+        "remove_sequence_channel_sequences__sequence_id__channels__sequence_channel_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SequenceTemplates",
+      "file": "components/sequence-templates.tsx",
+      "purpose": "Sequence templates: list, create, edit (only changes are sent), archive (confirmed) and restore, and use one to start a new sequence.",
+      "operations": [
+        "archive_sequence_template_sequencer_templates_sequences__sequence_template_id__archive_patch",
+        "create_sequence_template_sequencer_templates_sequences_post",
+        "list_sequence_templates_sequencer_templates_sequences_get",
+        "update_sequence_template_sequencer_templates_sequences__sequence_template_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "StepTemplates",
+      "file": "components/step-templates.tsx",
+      "purpose": "Step templates (also exports StepTemplatePicker): list, create, edit, archive (confirmed), restore, and have an agent draft a batch (billable, confirmed).",
+      "operations": [
+        "archive_step_template_sequencer_templates_steps__step_template_id__archive_patch",
+        "create_step_template_sequencer_templates_steps_post",
+        "generate_step_templates_sequencer_templates_steps_generate_post",
+        "list_sequencer_textual_agents_sequencer_agents_textual_get",
+        "list_step_templates_sequencer_templates_steps_get",
+        "update_step_template_sequencer_templates_steps__step_template_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "StepAiAssist",
+      "file": "components/step-ai-assist.tsx",
+      "purpose": "AI help for one email or LinkedIn step: improve the instructions and preview a draft for one contact; each AI call is billable and confirmed (the email draft shows its credit estimate), nothing is sent.",
+      "operations": [
+        "draft_email_sequencer_content_email_generate_post",
+        "draft_linkedin_message_sequencer_content_linkedin_generate_post",
+        "estimate_email_draft_sequencer_content_email_estimate_post",
+        "improve_step_instruction_sequencer_content_instructions_improve_post",
+        "list_contacts_contacts_get",
+        "list_sequencer_textual_agents_sequencer_agents_textual_get"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "WithdrawContactButton",
+      "file": "components/enrollment-withdraw.tsx",
+      "purpose": "Take one contact out of one sequence, recording the outcome (removed, completed, not interested); confirmed.",
+      "operations": [
+        "withdraw_contacts_from_sequences_contacts_withdraw_from_sequences_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
     {
       "name": "SequencesScreen",
       "file": "components/sequences-screen.tsx",
-      "purpose": "Finished sequences page: status stats and filter, list with launch/pause/resume, new-sequence sheet, detail with results, steps and enroll-contacts.",
+      "purpose": "Finished sequences page: status stats and filter, list with launch/pause/resume, new-sequence sheet, templates, detail with results, steps, senders, edit, sync, delete and enroll-contacts.",
       "operations": [
         "list_sequences_sequences_get"
       ],
@@ -147,7 +279,7 @@
     {
       "name": "SequenceDetail",
       "file": "components/sequence-detail.tsx",
-      "purpose": "One sequence, complete: every field, tabs for steps, contacts and results; launch (refused with the reasons when a step has no sender or the copy would block it), pause, resume, duplicate, archive and enroll (confirmed).",
+      "purpose": "One sequence, complete: every field, tabs for steps, contacts and results; launch (refused with the reasons when a step has no sender or the copy would block it), pause, resume, duplicate, archive and enroll (confirmed). Also edit, sync audience, save as template, delete and a Senders tab.",
       "operations": [
         "get_sequence_sequences__sequence_id__get",
         "preview_sequence_sequences__sequence_id__preview_get",
@@ -215,6 +347,22 @@
         "read",
         "write"
       ]
+    },
+    {
+      "name": "SequenceCampaignLink",
+      "file": "components/sequence-campaign-link.tsx",
+      "purpose": "Which campaign a sequence belongs to: the linked campaign with an Open campaign button and Unlink, or a picker to link one. Drop into SequencesScreen.renderDetailActions.",
+      "operations": [
+        "get_campaign_campaigns__campaign_id__get",
+        "list_campaigns_for_picker_campaigns_picker_get",
+        "link_sequence_campaign_sequences__sequence_id__campaign_put",
+        "unlink_sequence_campaign_sequences__sequence_id__campaign_delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
     }
   ],
   "hooks": [],
@@ -222,6 +370,10 @@
     {
       "file": "lib/sequencer-utils.ts",
       "purpose": "Step kinds and the draft-to-API mapping, send-time rule checks, status helpers and envelope readers."
+    },
+    {
+      "file": "lib/sequencer-manage.ts",
+      "purpose": "Edit-only-what-changed diffs, sequence and step template readers and bodies, contact and agent readers for AI drafting."
     }
   ],
   "recipes": [
@@ -312,6 +464,21 @@
       "decision": "Audience list",
       "default": "Required when creating a draft (the API cannot set it later, and a sequence without one cannot launch)",
       "askHuman": false
+    },
+    {
+      "decision": "Deleting versus archiving a sequence",
+      "default": "Both are the API's soft delete (the sequence stops and is hidden, and cannot be restored through the API). Delete and Archive are both offered and both confirmed",
+      "askHuman": false
+    },
+    {
+      "decision": "Reordering the steps of a saved sequence",
+      "default": "Not offered: the API has no reorder operation and a saved step has no order field to patch. Unsaved steps can be moved before they are added",
+      "askHuman": false
+    },
+    {
+      "decision": "Who may spend credits on AI drafts",
+      "default": "Every AI call (improve instructions, preview a draft, draft step templates) goes through a confirm dialog that says it uses credits; the email draft shows the exact estimate first",
+      "askHuman": false
     }
   ],
   "peerDependencies": {