@graph8/sdk 0.373.0 → 0.374.0

package/blocks/sequencer/components/step-templates.tsx

@@ -0,0 +1,224 @@
+"use client";
+
+/**
+ * StepTemplates: reusable single steps (an email, a LinkedIn touch, a call). List, create, edit, archive and restore
+ * them, and have an agent draft a batch for you. StepTemplatePicker (exported here) inserts one into a sequence being
+ * built.
+ *
+ * SDK operations, in order:
+ *   1. GET   /sequencer/templates/steps                 (sequences.listStepTemplates)      read   (archived ones included; filtered here)
+ *   2. POST  /sequencer/templates/steps                 (sequences.createStepTemplate)     write
+ *   3. PATCH /sequencer/templates/steps/{id}            (sequences.updateStepTemplate)     write  - ONLY the changed fields
+ *   4. PATCH /sequencer/templates/steps/{id}/archive    (sequences.archiveStepTemplate)    DESTRUCTIVE to archive -> ConfirmSpendDialog; restoring is a plain write
+ *   5. GET   /sequencer/agents/textual                  (sequences.listSequencerTextualAgents)  read - the agents that can draft
+ *      POST  /sequencer/templates/steps/generate        (sequences.generateStepTemplates)  BILLABLE -> ConfirmSpendDialog first.
+ *            Nothing is saved by generating: the drafts come back and each one is kept with "Save as template" or ignored.
+ * The edit form is seeded from a LOADED template (Save stays disabled until something changed) and never writes one that
+ * was not loaded. The step form is StepEditor, so the template obeys the same send-time rules as a step in a sequence.
+ */
+import { useState } from "react";
+import { Archive, ArchiveRestore, Pencil, Plus, Sparkles } from "lucide-react";
+import { Button, Input, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { agentOptions, stepTemplateBody, stepTemplateChanges, stepTemplates } from "../lib/sequencer-manage";
+import type { StepTemplate } from "../lib/sequencer-manage";
+import { KIND_LABEL, KINDS, newStep, stepIssues, stepSummary } from "../lib/sequencer-utils";
+import type { DraftStep, StepKind } from "../lib/sequencer-utils";
+import { StepEditor } from "./step-editor";
+
+export interface StepTemplatesProps {
+  className?: string;
+}
+
+function TemplateForm({ loaded, onDone }: { loaded: StepTemplate | null; onDone: (changed: boolean) => void }) {
+  const [name, setName] = useState(loaded?.name ?? "");
+  const [step, setStep] = useState<DraftStep>(loaded?.step ?? newStep("email"));
+  const changes = loaded ? stepTemplateChanges(loaded, name, step) : {};
+  const save = useG8Mutation(async () => {
+    if (loaded) await g8Patch(`/sequencer/templates/steps/${encodeURIComponent(loaded.id)}`, changes);
+    else await g8Post("/sequencer/templates/steps", stepTemplateBody(name, step));
+  }, { invalidates: ["sequences"] });
+  const valid = name.trim().length > 0 && stepIssues(step).length === 0 && (loaded ? Object.keys(changes).length > 0 : true);
+  const submit = async () => {
+    try {
+      await save.mutateAsync(undefined);
+      onDone(true);
+    } catch {
+      /* shown below */
+    }
+  };
+  return (
+    <form className="space-y-3 rounded-md border border-border p-3" aria-label={loaded ? `Edit ${loaded.name}` : "New step template"} onSubmit={(e) => { e.preventDefault(); if (valid) void submit(); }}>
+      <Input aria-label="Template name" placeholder="Template name" value={name} onChange={(e) => setName(e.target.value)} />
+      {!loaded ? (
+        <label className="flex items-center gap-2 text-sm">
+          Kind
+          <select aria-label="Step kind" className="h-8 rounded border border-input px-1" value={step.kind} onChange={(e) => setStep(newStep(e.target.value as StepKind))}>
+            {KINDS.map((k) => <option key={k} value={k}>{KIND_LABEL[k]}</option>)}
+          </select>
+        </label>
+      ) : null}
+      <StepEditor step={step} index={1} onChange={setStep} lockInputType={loaded != null} />
+      {save.error ? <ApiError error={save.error} title="Could not save the template" /> : null}
+      <div className="flex justify-end gap-2">
+        <Button type="button" variant="outline" size="sm" onClick={() => onDone(false)}>Cancel</Button>
+        <Button type="submit" size="sm" disabled={!valid || save.loading}>{loaded ? "Save changes" : "Create template"}</Button>
+      </div>
+    </form>
+  );
+}
+
+function GeneratePanel({ onSaved }: { onSaved: () => void }) {
+  const [agent, setAgent] = useState("");
+  const [confirming, setConfirming] = useState(false);
+  const [drafts, setDrafts] = useState<StepTemplate[]>([]);
+  const agents = useG8Query(async (signal) => agentOptions(await g8Get("/sequencer/agents/textual", undefined, { signal })), []);
+  const generate = useG8Mutation(async () => {
+    const env = await g8Post("/sequencer/templates/steps/generate", { agent_name: agent });
+    setDrafts(stepTemplates(env, true));
+    setConfirming(false);
+  }, { onError: () => setConfirming(false) });
+  const keep = useG8Mutation(async (t: StepTemplate) => {
+    await g8Post("/sequencer/templates/steps", stepTemplateBody(t.name, t.step));
+    setDrafts((all) => all.filter((x) => x.id !== t.id));
+    onSaved();
+  }, { invalidates: ["sequences"] });
+  return (
+    <div className="space-y-3 rounded-md border border-border p-3" aria-label="Draft templates with AI">
+      <p className="text-sm text-muted-foreground">An agent drafts a set of step templates. You keep the ones you like; nothing is saved until you do.</p>
+      <div className="flex flex-wrap items-center gap-2">
+        <select aria-label="Agent" className="h-9 min-w-48 rounded-md border border-border bg-background px-2 text-sm" value={agent} disabled={agents.loading} onChange={(e) => setAgent(e.target.value)}>
+          <option value="">{agents.loading ? "Loading agents..." : "Choose the agent to draft"}</option>
+          {(agents.data ?? []).map((a) => <option key={a.value} value={a.value}>{a.label}</option>)}
+        </select>
+        <Button size="sm" disabled={!agent || generate.loading} onClick={() => setConfirming(true)}><Sparkles className="mr-1 size-4" aria-hidden />Draft with AI</Button>
+      </div>
+      {agents.error ? <ApiError error={agents.error} title="Could not load the agents" onRetry={() => void agents.refetch()} /> : null}
+      {agents.data && agents.data.length === 0 ? <p className="text-sm text-muted-foreground">No agent is set up yet, so there is nobody to draft. Create one in the Agents block.</p> : null}
+      {generate.error ? <ApiError error={generate.error} title="Could not draft the templates" /> : null}
+      {keep.error ? <ApiError error={keep.error} title="Could not save the template" /> : null}
+      {drafts.length > 0 ? (
+        <ul aria-label="Drafted templates" className="divide-y rounded-md border border-border text-sm">
+          {drafts.map((t) => (
+            <li key={t.id} className="flex items-center gap-2 p-2">
+              <span className="min-w-0 flex-1"><span className="font-medium">{t.name}</span><span className="block truncate text-xs text-muted-foreground">{stepSummary(t.step)}</span></span>
+              <Button size="sm" variant="outline" loading={keep.loading} onClick={() => void keep.mutate(t)}>Save as template</Button>
+              <Button size="sm" variant="ghost" onClick={() => setDrafts((all) => all.filter((x) => x.id !== t.id))}>Discard</Button>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      <ConfirmSpendDialog
+        open={confirming}
+        tier="billable"
+        title="Draft step templates with AI?"
+        description="The agent writes a set of templates. Each draft uses credits, even the ones you discard. Nothing is sent to anyone."
+        confirmLabel="Draft templates"
+        confirming={generate.loading}
+        onConfirm={() => void generate.mutate(undefined)}
+        onCancel={() => setConfirming(false)}
+      />
+    </div>
+  );
+}
+
+export function StepTemplates({ className }: StepTemplatesProps) {
+  const [editing, setEditing] = useState<StepTemplate | "new" | null>(null);
+  const [archiving, setArchiving] = useState<StepTemplate | null>(null);
+  const [showArchived, setShowArchived] = useState(false);
+  const [restoringId, setRestoringId] = useState<string | null>(null);
+  const [drafting, setDrafting] = useState(false);
+  const list = useG8Query(async (signal) => stepTemplates(await g8Get("/sequencer/templates/steps", undefined, { signal })), [], { key: ["sequences", "step-templates"] });
+  const archive = useG8Mutation(async (v: { template: StepTemplate; archived: boolean }) => {
+    await g8Patch(`/sequencer/templates/steps/${encodeURIComponent(v.template.id)}/archive`, { is_archived: v.archived });
+    setArchiving(null);
+  }, { invalidates: ["sequences"], onError: () => setArchiving(null) });
+
+  if (list.error) return <ApiError error={list.error} title="Could not load the step templates" onRetry={() => void list.refetch()} className={className} />;
+  if (list.loading && !list.data) return <div aria-busy="true" className={`space-y-2 ${className ?? ""}`}><Skeleton className="h-10 w-full" /><Skeleton className="h-10 w-full" /></div>;
+  const all = list.data ?? [];
+  const rows = all.filter((t) => showArchived || !t.archived);
+  const done = (changed: boolean) => { setEditing(null); if (changed) void list.refetch(); };
+
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <h3 className="font-medium">Step templates</h3>
+        <div className="flex items-center gap-2">
+          <label className="flex items-center gap-1 text-xs"><input type="checkbox" checked={showArchived} onChange={(e) => setShowArchived(e.target.checked)} />Show archived</label>
+          <Button size="sm" variant="outline" onClick={() => setDrafting((d) => !d)}><Sparkles className="mr-1 size-4" aria-hidden />AI drafts</Button>
+          <Button size="sm" disabled={editing != null} onClick={() => setEditing("new")}><Plus className="mr-1 size-4" aria-hidden />New template</Button>
+        </div>
+      </div>
+      {drafting ? <GeneratePanel onSaved={() => void list.refetch()} /> : null}
+      {editing === "new" ? <TemplateForm loaded={null} onDone={done} /> : null}
+      {rows.length === 0 && editing !== "new" ? (
+        <EmptyState compact title="No step templates yet" description="Save an email or LinkedIn touch once, then drop it into any sequence." action={<Button size="sm" onClick={() => setEditing("new")}>Create a template</Button>} />
+      ) : (
+        <ul aria-label="Step templates" className="divide-y rounded-md border border-border">
+          {rows.map((t) => (
+            <li key={t.id} className="p-2 text-sm">
+              {editing !== "new" && editing?.id === t.id ? (
+                <TemplateForm loaded={t} onDone={done} />
+              ) : (
+                <div className="flex items-center gap-2">
+                  <StatusPill tone="neutral">{KIND_LABEL[t.step.kind]}</StatusPill>
+                  <span className="min-w-0 flex-1"><span className="font-medium">{t.name}</span><span className="block truncate text-xs text-muted-foreground">{stepSummary(t.step)}</span></span>
+                  {t.archived ? <StatusPill tone="warning">archived</StatusPill> : null}
+                  <Button size="sm" variant="ghost" aria-label={`Edit ${t.name}`} disabled={editing != null} onClick={() => setEditing(t)}><Pencil className="size-4" aria-hidden /></Button>
+                  {t.archived ? (
+                    <Button size="sm" variant="ghost" aria-label={`Restore ${t.name}`} loading={archive.loading && restoringId === t.id} onClick={() => { setRestoringId(t.id); void archive.mutate({ template: t, archived: false }); }}><ArchiveRestore className="size-4" aria-hidden /></Button>
+                  ) : (
+                    <Button size="sm" variant="ghost" aria-label={`Archive ${t.name}`} onClick={() => setArchiving(t)}><Archive className="size-4" aria-hidden /></Button>
+                  )}
+                </div>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+      {archive.error ? <ApiError error={archive.error} title="Could not update the template" /> : null}
+      <ConfirmSpendDialog
+        open={archiving != null}
+        tier="destructive"
+        title={`Archive "${archiving?.name ?? ""}"?`}
+        description="It leaves the template list. Sequences already built from it keep their steps. You can restore it from Show archived."
+        confirmLabel="Archive template"
+        affected={1}
+        confirming={archive.loading}
+        onConfirm={() => archiving && void archive.mutate({ template: archiving, archived: true })}
+        onCancel={() => setArchiving(null)}
+      />
+    </div>
+  );
+}
+
+export interface StepTemplatePickerProps {
+  /** Called with an unsaved copy of the template's step, ready to add to the sequence being built. */
+  onPick: (step: DraftStep, template: { id: string; name: string }) => void;
+  className?: string;
+}
+
+/** A select of the (non-archived) step templates and an Insert button. Loads the templates when it mounts. */
+export function StepTemplatePicker({ onPick, className }: StepTemplatePickerProps) {
+  const [id, setId] = useState("");
+  const list = useG8Query(async (signal) => stepTemplates(await g8Get("/sequencer/templates/steps", undefined, { signal })), [], { key: ["sequences", "step-templates"] });
+  const options = (list.data ?? []).filter((t) => !t.archived);
+  const chosen = options.find((t) => t.id === id);
+  return (
+    <div className={`flex flex-wrap items-center gap-2 ${className ?? ""}`}>
+      <select aria-label="Step template" className="h-8 min-w-48 rounded-md border border-border bg-background px-2 text-sm" value={id} disabled={list.loading} onChange={(e) => setId(e.target.value)}>
+        <option value="">{list.loading ? "Loading templates..." : options.length === 0 ? "No step templates yet" : "Choose a step template"}</option>
+        {options.map((t) => <option key={t.id} value={t.id}>{t.name} ({KIND_LABEL[t.step.kind]})</option>)}
+      </select>
+      <Button size="sm" variant="outline" disabled={!chosen} onClick={() => chosen && onPick({ ...chosen.step, key: `tpl-${chosen.id}-${Date.now().toString(36)}` }, { id: chosen.id, name: chosen.name })}>Insert step</Button>
+      {list.error ? <ApiError error={list.error} compact onRetry={() => void list.refetch()} /> : null}
+    </div>
+  );
+}

package/blocks/sequencer/lib/sequencer-manage.ts

@@ -0,0 +1,235 @@
+"use client";
+
+/**
+ * Pure helpers for managing sequences beyond building them: editing a sequence's own fields (only what changed),
+ * sequence and step templates, and AI drafting of step copy. No SDK calls here.
+ *
+ * Template and draft endpoints answer with open payloads (`{ items: [...] }`, or a bare object), so every reader is
+ * defensive: it takes a list from the usual places and skips rows it cannot use.
+ */
+import { fromApiStep, KIND_LABEL, kindOf, newKey, STEP_TYPE, toApiStep } from "./sequencer-utils";
+import type { ApiStep, DraftStep } from "./sequencer-utils";
+
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+const bool = (v: unknown): boolean => v === true;
+
+/** Rows from `{ data: [...] }`, `{ data: { items: [...] } }` or a named list. */
+export function templateRows<T = Record<string, unknown>>(envelope: unknown, ...names: string[]): T[] {
+  const data = (envelope as { data?: unknown } | null)?.data ?? envelope;
+  if (Array.isArray(data)) return data as T[];
+  const obj = (data ?? {}) as Record<string, unknown>;
+  for (const key of ["items", ...names]) if (Array.isArray(obj[key])) return obj[key] as T[];
+  return [];
+}
+
+// --- Editing a sequence ----------------------------------------------------------------------------------------
+
+export interface EditableSequence {
+  name: string;
+  description: string;
+  finish_on_reply: boolean;
+  send_in_same_thread: boolean;
+  wait_for_new_contacts: boolean;
+}
+
+/** The editable fields of `GET /sequences/{id}`, with the API's defaults for anything it left out. */
+export function editableSequence(record: Record<string, unknown>): EditableSequence {
+  return {
+    name: str(record.name),
+    description: str(record.description),
+    finish_on_reply: record.finish_on_reply !== false,
+    send_in_same_thread: bool(record.send_in_same_thread),
+    wait_for_new_contacts: bool(record.wait_for_new_contacts),
+  };
+}
+
+/**
+ * Only the fields that differ from what was loaded, for `PATCH /sequences/{id}`. An empty object means nothing to
+ * save. A cleared description is sent as an empty string so it really clears.
+ */
+export function sequenceChanges(loaded: EditableSequence, draft: EditableSequence): Partial<EditableSequence> {
+  const out: Partial<EditableSequence> = {};
+  if (draft.name.trim() !== loaded.name) out.name = draft.name.trim();
+  if (draft.description.trim() !== loaded.description) out.description = draft.description.trim();
+  if (draft.finish_on_reply !== loaded.finish_on_reply) out.finish_on_reply = draft.finish_on_reply;
+  if (draft.send_in_same_thread !== loaded.send_in_same_thread) out.send_in_same_thread = draft.send_in_same_thread;
+  if (draft.wait_for_new_contacts !== loaded.wait_for_new_contacts) out.wait_for_new_contacts = draft.wait_for_new_contacts;
+  return out;
+}
+
+/** What the change does to people, in words, for the confirm dialog. */
+export function changeSummary(changes: Partial<EditableSequence>): string[] {
+  const out: string[] = [];
+  if ("name" in changes) out.push(`Rename to "${changes.name}"`);
+  if ("description" in changes) out.push(changes.description ? "Change the description" : "Clear the description");
+  if ("finish_on_reply" in changes) out.push(changes.finish_on_reply ? "Stop the sequence for a contact once they reply" : "Keep sending after a contact replies");
+  if ("send_in_same_thread" in changes) out.push(changes.send_in_same_thread ? "Send follow-ups in the same email thread" : "Send each email as a new thread");
+  if ("wait_for_new_contacts" in changes) out.push(changes.wait_for_new_contacts ? "Wait for new contacts added to the list" : "Stop picking up new contacts");
+  return out;
+}
+
+// --- Templates -------------------------------------------------------------------------------------------------
+
+export interface SequenceTemplate {
+  id: string;
+  name: string;
+  description: string;
+  archived: boolean;
+  steps: ApiStep[];
+}
+
+export function sequenceTemplates(envelope: unknown): SequenceTemplate[] {
+  const out: SequenceTemplate[] = [];
+  for (const row of templateRows<Record<string, unknown>>(envelope, "templates")) {
+    const id = row?.id == null ? "" : String(row.id);
+    if (!id) continue;
+    const steps = (Array.isArray(row.steps) ? (row.steps as Array<Record<string, unknown>>) : []).map(
+      (s, i): ApiStep => ({
+        id: undefined,
+        name: str(s.name) || undefined,
+        step_order: typeof s.step_order === "number" ? s.step_order : i + 1,
+        step_type: str(s.step_type) || "EMAIL",
+        input_type: str(s.input_type) || "MANUAL_TEMPLATE",
+        time_interval: typeof s.time_interval === "number" ? s.time_interval : 0,
+        step_data: (s.step_data && typeof s.step_data === "object" ? s.step_data : {}) as Record<string, unknown>,
+      }),
+    );
+    out.push({ id, name: str(row.name) || id, description: str(row.description), archived: bool(row.is_archived), steps: steps.sort((a, b) => a.step_order - b.step_order) });
+  }
+  return out;
+}
+
+/** A template's steps as unsaved builder steps (no ids), ready to prefill a new sequence. */
+export function templateToDraftSteps(template: Pick<SequenceTemplate, "steps">): DraftStep[] {
+  return template.steps.map((s) => ({ ...fromApiStep(s), key: newKey(), id: undefined, dirty: true }));
+}
+
+/** The body of `POST /sequencer/templates/sequences` from steps (each template step needs a name: its own when it has one, else "Step N: Kind"). */
+export function templateBodyFromSteps(name: string, description: string, steps: ApiStep[]) {
+  return {
+    name: name.trim(),
+    ...(description.trim() ? { description: description.trim() } : {}),
+    steps: [...steps]
+      .sort((a, b) => a.step_order - b.step_order)
+      .map((s, i) => ({
+        name: s.name || `Step ${i + 1}: ${KIND_LABEL[kindOf(s.step_type)]}`,
+        step_type: s.step_type,
+        step_order: i + 1,
+        input_type: s.input_type ?? "MANUAL_TEMPLATE",
+        time_interval: s.time_interval ?? 0,
+        step_data: s.step_data ?? {},
+      })),
+  };
+}
+
+export interface StepTemplate {
+  id: string;
+  name: string;
+  archived: boolean;
+  step: DraftStep;
+}
+
+/** Step templates from a list answer. `drafts` accepts rows without an id (generated, not saved yet) and numbers them. */
+export function stepTemplates(envelope: unknown, drafts = false): StepTemplate[] {
+  const out: StepTemplate[] = [];
+  templateRows<Record<string, unknown>>(envelope, "templates").forEach((row, i) => {
+    const id = row?.id == null ? (drafts ? `draft-${i}` : "") : String(row.id);
+    if (!id) return;
+    const step: DraftStep = {
+      ...fromApiStep({ step_order: 1, step_type: str(row.step_type) || "EMAIL", input_type: str(row.input_type) || "MANUAL_TEMPLATE", time_interval: 2 * 86400, step_data: (row.step_data ?? {}) as Record<string, unknown> }),
+      key: newKey(),
+      id: undefined,
+      dirty: true,
+    };
+    out.push({ id, name: str(row.name) || id, archived: bool(row.is_archived), step });
+  });
+  return out;
+}
+
+/** Body of `POST /sequencer/templates/steps` for a step being saved as a template. */
+export function stepTemplateBody(name: string, step: DraftStep) {
+  const api = toApiStep(step, 1);
+  return { name: name.trim(), step_type: api.step_type, input_type: api.input_type, step_data: api.step_data };
+}
+
+/** Only what changed on a step template, for `PATCH /sequencer/templates/steps/{id}`. */
+export function stepTemplateChanges(loaded: StepTemplate, name: string, step: DraftStep): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (name.trim() !== loaded.name) out.name = name.trim();
+  const a = toApiStep(step, 1);
+  const b = toApiStep(loaded.step, 1);
+  if (JSON.stringify(a.step_data) !== JSON.stringify(b.step_data)) out.step_data = a.step_data;
+  if (a.step_type !== b.step_type) out.step_type = a.step_type;
+  return out;
+}
+
+export const STEP_TYPES_FOR_TEMPLATES = Object.values(STEP_TYPE);
+
+// --- AI drafting -----------------------------------------------------------------------------------------------
+
+export interface DraftContact {
+  id: number;
+  first_name: string;
+  last_name: string;
+  email: string;
+  label: string;
+  /** JSON of what is known about them; the drafting service writes from it. */
+  lead_info: string;
+}
+
+/** A contact row from `GET /contacts` as drafting input. Null only when there is no usable id; a contact with no email has `email: ""` (an email draft then cannot be requested). */
+export function draftContact(row: Record<string, unknown>): DraftContact | null {
+  const id = typeof row.id === "number" ? row.id : Number(row.id);
+  if (!Number.isFinite(id)) return null;
+  const first = str(row.first_name);
+  const last = str(row.last_name);
+  const full = str(row.full_name) || str(row.name) || `${first} ${last}`.trim();
+  const email = str(row.work_email) || str(row.email);
+  const info: Record<string, unknown> = {};
+  for (const k of ["job_title", "company_name", "company_domain", "company_industry", "city", "country", "seniority", "department"]) if (row[k]) info[k] = row[k];
+  return { id, first_name: first || full.split(" ")[0] || "", last_name: last || full.split(" ").slice(1).join(" "), email, label: [full || email || `Contact ${id}`, str(row.company_name)].filter(Boolean).join(", "), lead_info: JSON.stringify(info) };
+}
+
+/** `{ subject, body }` from a draft answer, or null when the answer has neither. */
+export function readEmailDraft(envelope: unknown): { subject: string; body: string } | null {
+  const data = ((envelope as { data?: unknown } | null)?.data ?? envelope) as Record<string, unknown> | null;
+  const subject = str(data?.subject);
+  const body = str(data?.body);
+  return subject || body ? { subject, body } : null;
+}
+
+/** `{ message, subject }` from a LinkedIn draft answer. */
+export function readLinkedinDraft(envelope: unknown): { message: string; subject: string } | null {
+  const data = ((envelope as { data?: unknown } | null)?.data ?? envelope) as Record<string, unknown> | null;
+  const message = str(data?.message);
+  return message ? { message, subject: str(data?.subject) } : null;
+}
+
+/** The improved instruction from `POST /sequencer/content/instructions/improve` (`{ prompt }`). */
+export function readImprovedInstruction(envelope: unknown): string {
+  const data = ((envelope as { data?: unknown } | null)?.data ?? envelope) as Record<string, unknown> | string | null;
+  if (typeof data === "string") return data;
+  return str(data?.prompt) || str(data?.improved_prompt) || str(data?.instruction) || str(data?.text);
+}
+
+/** Credits from `POST /sequencer/content/email/estimate`; `cached` means the draft is served free. */
+export function readCreditEstimate(envelope: unknown): { credits: number; cached: boolean } | null {
+  const data = ((envelope as { data?: unknown } | null)?.data ?? envelope) as Record<string, unknown> | null;
+  const credits = typeof data?.estimated_credits === "number" ? data.estimated_credits : null;
+  return credits == null ? null : { credits, cached: data?.cached === true };
+}
+
+export interface AgentOption {
+  value: string;
+  label: string;
+}
+
+/** Textual agents from `GET /sequencer/agents/textual` (untyped: names or objects with a name). */
+export function agentOptions(envelope: unknown): AgentOption[] {
+  const out: AgentOption[] = [];
+  for (const row of templateRows<unknown>(envelope, "agents")) {
+    const name = typeof row === "string" ? row : str((row as Record<string, unknown>)?.name) || str((row as Record<string, unknown>)?.agent_name);
+    if (name) out.push({ value: name, label: name });
+  }
+  return out;
+}

package/blocks/sequencer/lib/sequencer-utils.ts

@@ -42,11 +42,15 @@ export interface SequenceRow {
   contact_count?: number | null;
   sequence_kind?: string | null;
   associated_list_id?: number | null;
+  /** The Studio campaign this sequence belongs to, when linked. */
+  campaign_builder_campaign_id?: string | null;
   updated_at?: string | null;
 }
 
 export interface ApiStep {
   id?: string;
+  /** A sequence template step's own name (templates only). */
+  name?: string;
   step_order: number;
   step_type: string;
   input_type?: string;

package/blocks/signals/README.md

@@ -0,0 +1,39 @@
+# signals
+
+Social listening for the intent family: watch X, LinkedIn, Reddit, Instagram and YouTube for posts about your brand,
+competitors and keywords, triage what matched, and keep the spend bounded. Depends on `intent` (and through it `crm`).
+
+## Screens
+
+- **SocialListenersScreen** (`/social-listening`): tabs Listeners, Posts, Top engagers, Sources and Settings, with totals at
+  the top. A listener opens as a deep-linkable detail (`?id=`, `&view=full` for a page) with Overview, Matches and Edit.
+- **RecordSocialTab**: a contact's matched posts, for `ContactsScreen` `extraDetailTabs`.
+
+## Flows
+
+Create a listener (cost estimate, optional generated query, monthly cap), pause or resume, edit changed fields only, delete.
+Triage posts (reviewed or dismissed), save an author as a contact, add an author to a live sequence, turn a post's
+engagers into a list. See the accounts that engage most. Watch every profile on a list. Seed starter listeners from your
+keywords, brand, competitors and buyer profile. Change the org-wide caps and channel ceilings (admin). Test, connect and
+disconnect your own X developer app.
+
+Every billable, external or destructive call is behind `ConfirmSpendDialog`, with quantities taken from the data on screen.
+Nothing connects, sends or spends on its own.
+
+## Prerequisites and scopes
+
+`intent:read` (reads), `intent:run` (create and change listeners, posts, seeds, settings, X), `intent:delete` (delete a
+listener), plus `lists:read` and `sequences:read` for the pickers. Settings changes also need an org admin.
+
+## Defaults
+
+Poll interval and monthly cap are not sent unless typed. Price per language-model pass is 5 credits (backend constant, no
+price endpoint). A person always chooses the sequence an author joins.
+
+## API gaps
+
+- Every response is an open object; shapes follow the app's models and may gain fields.
+- `PATCH /social-listeners/{id}` and `PATCH /settings` both drop nulls (`exclude_none`), so a query, a handle or a number cannot be unset: the form refuses to clear a query rather than report a save that did not happen. Settings PATCH: a channel or capture rule is replaced whole.
+- No price read: the language-model pass price is a constant.
+- No company-level post read; only a contact's posts (`listPostsByContact`).
+- `markPost`, `savePostAuthorAsContact` and `addEngagersToList` are tiered billable but spend no credits (documented by the API).