@graph8/sdk 0.361.0 → 0.370.0

package/blocks/sequencer/components/sequences-screen.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+/**
+ * SequencesScreen: the finished "Sequences" page (the Apollo / Outreach sequencer).
+ *
+ * Composes: SequenceList (status, launch, pause, resume, duplicate, archive), SequenceBuilder (create a draft,
+ * edit steps), SequenceStats (totals, per-step progress, per-contact pause/resume), EnrollDialog, plus the
+ * lists block ListPicker and the crm block ContactTable to choose who to enroll.
+ *
+ * Every record has a complete detail, beside the list or as a full page (`?view=full`): the sequence
+ * (SequenceDetail), each step (`?step=`) and each enrollment (`?enrollment=`).
+ *
+ * User flows:
+ *   - Browse sequences, filter by status, see live/paused/draft counts at a glance.
+ *   - "New sequence" opens a sheet with the builder (sender, audience list, email/LinkedIn/call steps); the new
+ *     draft opens right away. Nothing is sent until it is launched.
+ *   - Launch (after a preview that checks each step's copy and sender; a launch that would 400 is refused with the
+ *     reasons), pause, resume, duplicate, archive from the list (all confirmed).
+ *   - Open a sequence (deep link `?id=`): Results (stats, contacts, pause/resume one), Steps (edit copy), and
+ *     "Enroll contacts": pick a list, tick contacts, confirm the recipient count.
+ *
+ * SDK operations of its own (both read):
+ *   1. listSequences  GET /sequences?limit=100  (counts for the stat strip)
+ *   2. getSequence    GET /sequences/{id}       (header of the open sequence; also gives associated_list_id)
+ * Everything that reaches real people is confirmed in the composed parts.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { ListOrdered, Plus } from "lucide-react";
+import { Button } from "@graph8/sdk/ui";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import type { StatItem } from "@/g8/components/screen/stat-strip";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { listOf, statusGroup } from "../lib/sequencer-utils";
+import type { SequenceRow } from "../lib/sequencer-utils";
+import { SequenceBuilder } from "./sequence-builder";
+import { SequenceDetail } from "./sequence-detail";
+import { SequenceList } from "./sequence-list";
+
+export interface SequencesScreenProps {
+  /** Owner email sent with a new sequence (`user_email`). */
+  ownerEmail?: string;
+  /** Extra buttons in the toolbar. */
+  toolbarActions?: ReactNode;
+  /** Extra buttons in the open sequence's header. */
+  renderDetailActions?: (sequence: SequenceRow) => ReactNode;
+  /** Extra tabs in the open sequence's panel. */
+  extraDetailTabs?: { id: string; label: string; render: (sequence: SequenceRow) => ReactNode }[];
+  className?: string;
+}
+
+const FILTERS = [
+  { value: "", label: "All statuses" },
+  { value: "drafted", label: "Drafts" },
+  { value: "live", label: "Live" },
+  { value: "paused", label: "Paused" },
+];
+const SUMMARY_LIMIT = 100;
+
+/** Counts by status group for the stat strip. Exported for tests. */
+export function sequenceStats(rows: SequenceRow[]): StatItem[] {
+  const n = (g: ReturnType<typeof statusGroup>) => rows.filter((r) => statusGroup(r.status) === g).length;
+  const hint = rows.length >= SUMMARY_LIMIT ? `First ${SUMMARY_LIMIT} sequences` : undefined;
+  const live = rows.filter((r) => statusGroup(r.status) === "live");
+  return [
+    { label: "Live", value: n("live"), tone: "positive", hint },
+    { label: "Paused", value: n("paused"), tone: "warning", hint },
+    { label: "Drafts", value: n("draft"), hint },
+    { label: "Contacts in live", value: live.reduce((a, r) => a + (r.contact_count ?? 0), 0).toLocaleString(), hint },
+  ];
+}
+
+export function SequencesScreen(props: SequencesScreenProps) {
+  const { ownerEmail, toolbarActions, className } = props;
+  const [selectedId, setSelectedId] = useUrlState("id", "");
+  const [detailTab, setDetailTab] = useUrlState("dtab", "");
+  const [view, setView] = useUrlState("view", "");
+  const [stepId, setStepId] = useUrlState("step", "");
+  const [contactId, setContactId] = useUrlState("enrollment", "");
+  const [status, setStatus] = useUrlState("status", "");
+  const [creating, setCreating] = useState(false);
+  const [version, setVersion] = useState(0);
+  const [listKey, setListKey] = useState(0);
+  const summary = useG8Query((signal) => g8Get("/sequences", { limit: SUMMARY_LIMIT }, { signal }), [version], { key: ["sequences", "summary"] });
+  const stats = summary.data ? sequenceStats(listOf<SequenceRow>(summary.data)) : undefined;
+  const bump = () => setVersion((v) => v + 1);
+  const open = (id: string) => { setSelectedId(id); setDetailTab(null); setStepId(null); setContactId(null); };
+  const close = () => { setSelectedId(null); setDetailTab(null); setStepId(null); setContactId(null); setView(null); };
+  const refreshList = () => { setListKey((k) => k + 1); bump(); };
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Sequences"
+      description="Multi-channel outreach that runs on its own: build steps, enroll contacts, watch replies."
+      icon={<ListOrdered className="h-5 w-5" aria-hidden />}
+      actions={
+        <Button onClick={() => setCreating(true)}>
+          <Plus className="mr-1 h-4 w-4" aria-hidden /> New sequence
+        </Button>
+      }
+      stats={stats}
+    >
+      <div className="space-y-3">
+        <Toolbar
+          actions={toolbarActions}
+          filters={
+            <select aria-label="Status" className="h-9 rounded-md border bg-background px-2 text-sm" value={status} onChange={(e) => setStatus(e.target.value || null)}>
+              {FILTERS.map((f) => <option key={f.value} value={f.value}>{f.label}</option>)}
+            </select>
+          }
+        />
+        <SplitView
+          expanded={view === "full"} onExpandedChange={(e) => setView(e ? "full" : null)}
+          detailOpen={Boolean(selectedId)}
+          onCloseDetail={close}
+          list={
+            <SequenceList key={`${listKey}:${status}`} status={status || undefined} onOpen={(s) => open(s.id)} onCreate={() => setCreating(true)} onChanged={bump} />
+          }
+          detail={
+            selectedId ? (
+              <SequenceDetail
+                key={selectedId}
+                sequenceId={selectedId}
+                onExpand={view === "full" ? undefined : () => setView("full")} onCollapse={view === "full" ? () => setView(null) : undefined}
+                tab={detailTab || undefined}
+                onTabChange={(t) => setDetailTab(t === "details" ? null : t)}
+                stepId={stepId || undefined}
+                onStepChange={(v) => setStepId(v)}
+                contactId={contactId || undefined}
+                onContactChange={(v) => setContactId(v)}
+                onClose={close}
+                onChanged={refreshList}
+                refreshKey={version}
+                onOpenSequence={open}
+                renderActions={props.renderDetailActions}
+                extraTabs={props.extraDetailTabs}
+              />
+            ) : null
+          }
+        />
+      </div>
+      <FormSheet open={creating} onOpenChange={setCreating} width="xl" title="New sequence" description="Saved as a draft. Nobody is contacted until you launch it.">
+        {creating ? (
+          <SequenceBuilder
+            ownerEmail={ownerEmail}
+            onSaved={(id) => { setCreating(false); refreshList(); open(id); }}
+          />
+        ) : null}
+      </FormSheet>
+    </ScreenLayout>
+  );
+}

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

@@ -20,6 +20,7 @@ import { g8Get } from "@/g8/lib/g8-client";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { hasBrokenTokens, KIND_LABEL, LINKEDIN_ACTIONS, stepIssues } from "../lib/sequencer-utils";
 import type { DraftStep, InputType } from "../lib/sequencer-utils";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface StepEditorProps {
   step: DraftStep;
@@ -38,6 +39,7 @@ const COPY_KEY: Record<string, string | undefined> = {
 };
 
 function LinkedinReadiness() {
+  const brand = useBrand();
   const conn = useG8Query(
     (signal) =>
       g8Get<{ connected?: boolean; is_token_valid?: boolean; requires_manual_login?: boolean }>(
@@ -53,7 +55,7 @@ function LinkedinReadiness() {
     return <p className="text-xs text-green-700">LinkedIn sender connected.</p>;
   return (
     <p role="alert" className="text-xs text-amber-800">
-      LinkedIn is not ready to send. Reconnect the LinkedIn account in the graph8 app before launching.
+      LinkedIn is not ready to send. Reconnect the LinkedIn account in the {brand.linkLabel} app before launching.
     </p>
   );
 }

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

@@ -10,7 +10,8 @@ export type StepKind = "email" | "linkedin" | "call" | "task";
 
 /** UI step kind -> the API `step_type`. `linkedin` is HeyReach; `task` is a manual dialer task. */
 export const STEP_TYPE: Record<StepKind, string> = { email: "EMAIL", linkedin: "HEYREACH", call: "PHONE", task: "MANUAL_DIALER" };
-export const KIND_LABEL: Record<StepKind, string> = { email: "Email", linkedin: "LinkedIn", call: "Call", task: "Call task" };
+/** `call` is an AI voice-agent call (PHONE); `task` is a call a rep makes from the dialer (MANUAL_DIALER). */
+export const KIND_LABEL: Record<StepKind, string> = { email: "Email", linkedin: "LinkedIn", call: "AI call", task: "Call task" };
 export const KINDS = Object.keys(STEP_TYPE) as StepKind[];
 
 export const LINKEDIN_ACTIONS = ["CONNECTION_REQUEST", "MESSAGE", "INMAIL", "FOLLOW", "VIEW_PROFILE", "LIKE_POST"] as const;
@@ -29,6 +30,8 @@ export interface DraftStep {
   step_data: Record<string, unknown>;
   /** True once changed since it was loaded or saved. */
   dirty?: boolean;
+  /** The API `step_type` a loaded step had (for example NETRION), so saving it never rewrites the provider. */
+  step_type?: string;
 }
 
 export interface SequenceRow {
@@ -77,17 +80,23 @@ export function fromApiStep(s: ApiStep): DraftStep {
     key: s.id ?? newKey(),
     id: s.id,
     kind: kindOf(s.step_type),
+    step_type: s.step_type,
     input_type: (s.input_type as InputType) ?? "MANUAL_TEMPLATE",
     wait_days: (s.time_interval ?? 0) / 86400,
     step_data: { ...(s.step_data ?? {}) },
   };
 }
 
-/** The request shape for create and add-steps. `order` is 1-based. */
-export function toApiStep(step: DraftStep, order: number) {
+/**
+ * The request shape for create, update and add-steps. `order` is 1-based. `linkedinStepType` is the LinkedIn
+ * provider step for NEW LinkedIn steps (`HEYREACH`, or `NETRION`); a loaded step keeps its own `step_type`.
+ */
+export function toApiStep(step: DraftStep, order: number, linkedinStepType?: string) {
+  // A loaded step keeps its own type (a NETRION step stays NETRION) as long as its kind did not change.
+  const own = step.step_type && kindOf(step.step_type) === step.kind ? step.step_type : undefined;
   return {
     step_order: order,
-    step_type: STEP_TYPE[step.kind],
+    step_type: own ?? (step.kind === "linkedin" && linkedinStepType ? linkedinStepType : STEP_TYPE[step.kind]),
     input_type: step.input_type,
     time_interval: Math.max(0, Math.round(step.wait_days * 86400)),
     step_data: step.step_data,
@@ -153,7 +162,96 @@ export function objectOf(envelope: unknown): Record<string, unknown> {
   return data && typeof data === "object" && !Array.isArray(data) ? (data as Record<string, unknown>) : {};
 }
 
-/** Map a mailbox's provider to the sequence channel type the API takes. */
+export type EmailChannelType = "GMAIL" | "INBOXKIT" | "SMTP";
+
+export interface MailboxLike {
+  provider?: string | null;
+  /** inboxkit | manual_google | manual_microsoft | manual_smtp | opensrs | purchased (GET /mailboxes). */
+  source?: string | null;
+}
+
+/**
+ * The sequence channel type for a mailbox, decided by `source` first, as the graph8 app does: an InboxKit mailbox
+ * is INBOXKIT whatever its provider (a Google-backed InboxKit mailbox attached as GMAIL fails at send time),
+ * Google is GMAIL, SMTP is SMTP. `null` = this mailbox cannot send from a sequence (see `mailboxUnsupportedReason`).
+ */
+export function mailboxChannelType(mailbox: MailboxLike): EmailChannelType | null {
+  const source = (mailbox.source ?? "").toLowerCase();
+  const provider = (mailbox.provider ?? "").toLowerCase();
+  if (source === "inboxkit") return "INBOXKIT";
+  if (source === "manual_microsoft" || provider === "microsoft") return null;
+  if (provider === "google_mailbox" || source === "manual_google") return "GMAIL";
+  if (provider === "smtp" || source === "manual_smtp") return "SMTP";
+  // An API without `source` (older graph8): fall back to the provider guess.
+  return source ? null : channelTypeFor(provider);
+}
+
+/** Why a mailbox cannot be picked as a sequence sender, or null when it can. */
+export function mailboxUnsupportedReason(mailbox: MailboxLike): string | null {
+  if (mailboxChannelType(mailbox)) return null;
+  const microsoft = (mailbox.source ?? "").toLowerCase() === "manual_microsoft" || (mailbox.provider ?? "").toLowerCase() === "microsoft";
+  return microsoft
+    ? "Directly connected Microsoft mailboxes cannot send from sequences yet"
+    : "This mailbox type cannot send from sequences yet";
+}
+
+/** The senders a set of steps needs. `call` (AI) needs an AI number, `task` a dialer number. */
+export function requiredSenders(kinds: Iterable<StepKind>): { email: boolean; aiPhone: boolean; dialerPhone: boolean; linkedin: boolean } {
+  const set = new Set(kinds);
+  return { email: set.has("email"), aiPhone: set.has("call"), dialerPhone: set.has("task"), linkedin: set.has("linkedin") };
+}
+
+const EMAIL_TYPES = new Set(["SMTP", "GMAIL", "INBOXKIT"]);
+
+/**
+ * What stops a sequence from launching, read from GET /sequences/{id}/preview (`steps[].step_type` and
+ * `channels[].channel_type`): the API refuses `/run` with 400 when a step type has no sender channel. Checked
+ * client-side so a launch is never offered that can only fail.
+ */
+export function senderGaps(steps: Array<{ step_type?: string | null }>, channels: Array<{ channel_type?: string | null }>): string[] {
+  const types = new Set(steps.map((s) => (s.step_type ?? "").toUpperCase()));
+  const have = new Set(channels.map((c) => (c.channel_type ?? "").toUpperCase()));
+  const gaps: string[] = [];
+  if (types.has("EMAIL") && ![...have].some((t) => EMAIL_TYPES.has(t))) gaps.push("Email steps have no mailbox to send from.");
+  if ((types.has("PHONE") || types.has("MANUAL_DIALER")) && !have.has("PHONE"))
+    gaps.push("Call steps have no phone number to call from.");
+  if (types.has("HEYREACH") && !have.has("LINKEDIN")) gaps.push("LinkedIn steps have no LinkedIn account to send from.");
+  if (types.has("NETRION") && !have.has("LINKEDIN_NETRION")) gaps.push("LinkedIn steps have no LinkedIn account to send from.");
+  if (types.has("SMS") && !have.has("SMS")) gaps.push("SMS steps have no number to text from.");
+  return gaps;
+}
+
+interface PreviewIssue {
+  message?: string;
+  severity?: string;
+}
+
+/**
+ * Launch check from GET /sequences/{id}/preview. The verdict lives on each step: `steps[].rendered.will_send_as_shown`
+ * and `steps[].rendered.content_issues` (a top-level copy is read too, for older APIs). An error-severity issue
+ * makes `/run` answer 400, so it blocks; anything else is a warning. A missing sender also blocks.
+ */
+export function launchCheck(preview: Record<string, unknown>): { warnings: string[]; blockers: string[] } {
+  const steps = (Array.isArray(preview.steps) ? preview.steps : []) as Array<Record<string, unknown>>;
+  const channels = (Array.isArray(preview.channels) ? preview.channels : []) as Array<{ channel_type?: string | null }>;
+  const warnings: string[] = [];
+  const blockers: string[] = [];
+  const read = (verdict: Record<string, unknown> | null | undefined, where: string) => {
+    if (!verdict) return;
+    const issues = (Array.isArray(verdict.content_issues) ? verdict.content_issues : []) as PreviewIssue[];
+    for (const issue of issues) {
+      const text = `${where}${issue.message ?? "The copy will not send as shown."}`;
+      ((issue.severity ?? "").toLowerCase() === "error" ? blockers : warnings).push(text);
+    }
+    if (verdict.will_send_as_shown === false && issues.length === 0) warnings.push(`${where}The copy will not send as shown.`);
+  };
+  steps.forEach((step, i) => read(step.rendered as Record<string, unknown> | undefined, `Step ${Number(step.step_order ?? i + 1)}: `));
+  read(preview, "");
+  blockers.push(...senderGaps(steps as Array<{ step_type?: string | null }>, channels));
+  return { warnings: [...new Set(warnings)], blockers: [...new Set(blockers)] };
+}
+
+/** Map a mailbox's provider to the sequence channel type the API takes. Prefer `mailboxChannelType`, which reads `source`. */
 export function channelTypeFor(provider: string | null | undefined): "GMAIL" | "INBOXKIT" | "SMTP" {
   const p = (provider ?? "").toLowerCase();
   if (p.includes("gmail") || p.includes("google")) return "GMAIL";
@@ -166,3 +264,28 @@ export function newIdempotencyKey(): string {
     ? crypto.randomUUID()
     : `g8-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 }
+
+const HIDDEN_FIELDS = /password|secret|token|credential/i;
+
+/** Every readable field of an open-shaped record as label/value pairs (secrets are never shown). */
+export function fieldItems(obj: Record<string, unknown>): Array<{ label: string; value: string }> {
+  return Object.entries(obj)
+    .filter(([k, v]) => !HIDDEN_FIELDS.test(k) && v !== null && v !== undefined && v !== "")
+    .map(([k, v]) => {
+      const label = k.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+      if (typeof v === "string" && /_at$|date$/.test(k) && !Number.isNaN(new Date(v).getTime()))
+        return { label, value: new Date(v).toLocaleString("en-US", { dateStyle: "medium", timeStyle: "short", timeZone: "UTC" }) + " UTC" };
+      if (typeof v === "boolean") return { label, value: v ? "Yes" : "No" };
+      if (typeof v === "object") return { label, value: JSON.stringify(v) };
+      return { label, value: String(v) };
+    });
+}
+
+/** One line that says what a step does, for lists. */
+export function stepSummary(step: DraftStep): string {
+  const d = step.step_data;
+  const str = (v: unknown) => (typeof v === "string" ? v.trim() : "");
+  if (step.kind === "email") return str(d.subject) || str(d.instructions) || "Email";
+  if (step.kind === "linkedin") return str(d.linkedin_action_type).replace(/_/g, " ").toLowerCase() || "LinkedIn";
+  return KIND_LABEL[step.kind];
+}

package/blocks/sequencer/recipes/create-multichannel-sequence.ts

@@ -1,10 +1,13 @@
 /**
- * @title Create a draft sequence with email, LinkedIn and a call
+ * @title Create a draft sequence with email, LinkedIn and an AI call
  * @when Building outreach. Creating the draft is tier `external` in the contract but contacts nobody; the
- * LAUNCH is what reaches people (see launch-and-enroll.ts). Three rules the API only enforces at send time:
+ * LAUNCH is what reaches people (see launch-and-enroll.ts). Rules the API only enforces at send or launch time:
  * 1) an EMAIL step needs `input_type: "MANUAL_TEMPLATE"` or its subject/body are ignored; 2) a LinkedIn
  * (HEYREACH) step needs `linkedin_action_type` and the action's own copy key, never `body`; 3) `time_interval`
- * is in SECONDS. Attach the sender mailbox as a channel; LinkedIn steps also need a LinkedIn sender (app).
+ * is in SECONDS; 4) EVERY step type needs its own sender channel or POST /sequences/{id}/run answers 400: the
+ * mailbox (channel type from its `source`), a Voice AI number for PHONE (an AI voice-agent call; a rep's call is
+ * MANUAL_DIALER with a dialer number), a LinkedIn account for HEYREACH; 5) `associated_list_id` is required to
+ * launch and cannot be set later.
  */
 import { g8 } from "@graph8/sdk";
 
@@ -12,7 +15,28 @@ g8.init({ apiKey: process.env.G8_API_KEY! });
 
 const DAY = 86400;
 
-export async function createDraftSequence(name: string, listId: number, mailbox: { id: number; email: string }) {
+/** Sequence channel type for a mailbox from GET /mailboxes: by `source` first, as the graph8 app does. */
+function mailboxChannelType(m: { source?: string | null; provider?: string | null }): "INBOXKIT" | "GMAIL" | "SMTP" {
+  if (m.source === "inboxkit") return "INBOXKIT";
+  if (m.source === "manual_microsoft" || m.provider === "microsoft")
+    throw new Error("Directly connected Microsoft mailboxes cannot send from sequences yet: pick another mailbox");
+  if (m.provider === "google_mailbox" || m.source === "manual_google") return "GMAIL";
+  return "SMTP";
+}
+
+export async function createDraftSequence(name: string, listId: number, sender: { id: number; email: string }) {
+  // The senders, one per step type. Rows are open-shaped (no response schema in the contract): read loosely.
+  const mailboxes = (await g8.api.gtmContext.listMailboxes()).data as Array<{ id: string; email: string; source?: string; provider?: string }>;
+  const mailbox = mailboxes.find((m) => Number(m.id) === sender.id);
+  if (!mailbox) throw new Error(`Mailbox ${sender.id} not found`);
+  const mailboxId = sender.id;
+  const phones = (await g8.api.sequences.listSequencerPhoneNumbers()).data as { phone_numbers?: Array<{ id: number; phone_number: string; inbound_type?: string }> };
+  const aiNumber = (phones.phone_numbers ?? []).find((p) => p.inbound_type === "ai");
+  const linkedin = (await g8.api.sequences.listLinkedinAccounts()).data as { linkedin_accounts?: Array<{ id: number; name?: string }>; provider?: string };
+  const account = linkedin.linkedin_accounts?.[0];
+  if (!aiNumber || !account || linkedin.provider !== "HEYREACH")
+    throw new Error("This recipe needs a Voice AI number and a HeyReach LinkedIn account (connect them in the graph8 app)");
+
   const created = await g8.api.sequenceLifecycle.createSequence({
     body: {
       name,
@@ -44,7 +68,11 @@ export async function createDraftSequence(name: string, listId: number, mailbox:
           step_data: { dial_dnc: false, phone_options: ["mobile", "direct"] },
         },
       ],
-      channels: [{ channel_id: mailbox.id, channel_value: mailbox.email, channel_type: "SMTP" }],
+      channels: [
+        { channel_id: mailboxId, channel_value: mailbox.email, channel_type: mailboxChannelType(mailbox) },
+        { channel_id: aiNumber.id, channel_value: aiNumber.phone_number, channel_type: "PHONE" },
+        { channel_id: account.id, channel_value: account.name ?? String(account.id), channel_type: "LINKEDIN" },
+      ],
     },
   });
   return created.data?.id;

package/blocks/sequencer/recipes/launch-and-enroll.ts

@@ -19,9 +19,26 @@ export async function launchAndEnroll(sequenceId: string, listId: number, contac
   if ((verdict.data as { safe_to_send?: boolean } | undefined)?.safe_to_send === false)
     throw new Error("Deliverability says not safe to send right now");
 
+  // The copy verdict is PER STEP (`steps[].rendered`), not on the preview itself. An error-severity issue makes
+  // /run answer 400; anything else is a warning to show the human. Every step type also needs a sender channel.
   const preview = await g8.api.sequenceLifecycle.previewSequence({ path: { sequence_id: sequenceId } });
-  const issues = (preview.data as { content_issues?: unknown[]; will_send_as_shown?: boolean } | undefined)?.content_issues ?? [];
-  if (issues.length) throw new Error(`Fix the copy first: ${JSON.stringify(issues)}`);
+  const steps = preview.data?.steps ?? [];
+  const issues = steps.flatMap((s) =>
+    (s.rendered?.content_issues ?? []).map((i) => ({ step: s.step_order, ...(i as { severity?: string; message?: string }) })),
+  );
+  const errors = issues.filter((i) => (i.severity ?? "").toLowerCase() === "error");
+  if (errors.length) throw new Error(`Fix the copy first: ${errors.map((e) => `step ${e.step}: ${e.message}`).join("; ")}`);
+  if (steps.some((s) => s.rendered?.will_send_as_shown === false))
+    console.warn("Some copy will not send exactly as previewed:", JSON.stringify(issues));
+  const types = new Set(steps.map((s) => s.step_type.toUpperCase()));
+  const senders = new Set((preview.data?.channels ?? []).map((c) => (c.channel_type ?? "").toUpperCase()));
+  const missing = [
+    types.has("EMAIL") && !["SMTP", "GMAIL", "INBOXKIT"].some((t) => senders.has(t)) && "a mailbox",
+    (types.has("PHONE") || types.has("MANUAL_DIALER")) && !senders.has("PHONE") && "a phone number",
+    types.has("HEYREACH") && !senders.has("LINKEDIN") && "a LinkedIn account",
+    types.has("NETRION") && !senders.has("LINKEDIN_NETRION") && "a LinkedIn account",
+  ].filter(Boolean);
+  if (missing.length) throw new Error(`Attach ${missing.join(", ")} first (POST /sequences/{id}/channels): /run refuses it`);
 
   const current = await g8.api.sequences.getSequence({ path: { sequence_id: sequenceId } });
   const status = (current.data as { status?: string } | undefined)?.status;

package/blocks/social-ads/README.md

@@ -5,6 +5,17 @@ Publish to social, watch your ads, make ad creatives and feed ad platforms with
 
 Install: `npx @graph8/sdk add social-ads` (installs `foundation`, `crm` and `lists` first).
 
+## Screens
+
+Two finished pages, each a route you can copy. No props are required.
+
+- `SocialScreen` (`components/social-screen.tsx`): **Posts** by status with per-status counts, publish/cancel/delete (confirmed), and a
+  **New post** side sheet holding the composer (AI drafts, schedule, publish). **Accounts** lists connected accounts and publishing
+  capacity, and links out to graph8 to connect LinkedIn (browser sign-in only).
+- `AdsScreen` (`components/ads-screen.tsx`): **Campaigns** with a 30-day results strip, **Audiences** (with sync run history, a billable read that asks first; sync a list to Meta, LinkedIn, Google or X
+  and launch a campaign; launching moves you to Campaigns), **Creatives** (generate, edit, organize). Ad accounts are connected in graph8.
+- Everything that sends data, spends or deletes keeps its confirmation. Slot: `toolbarActions`; `connectUrl` overrides the link-out.
+
 ## What you get
 
 | Component | Use it for | Props |

package/blocks/social-ads/block.json

@@ -45,7 +45,8 @@
     "trigger_audience_sync_audience_syncs__config_id__trigger_post",
     "update_ad_creative_ad_creatives__creative_id__patch",
     "update_audience_sync_audience_syncs__config_id__patch",
-    "update_social_post_social_posts__post_id__patch"
+    "update_social_post_social_posts__post_id__patch",
+    "get_ad_creative_ad_creatives__creative_id__get"
   ],
   "components": [
     {
@@ -139,6 +140,103 @@
         "external",
         "destructive"
       ]
+    },
+    {
+      "name": "SocialScreen",
+      "file": "components/social-screen.tsx",
+      "purpose": "Finished social page: posts by status with a New post composer sheet, and connected accounts.",
+      "operations": [
+        "list_social_posts_social_posts_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "AdsScreen",
+      "file": "components/ads-screen.tsx",
+      "purpose": "Finished ads page: campaigns with results, audience syncs and launch, and AI creatives.",
+      "operations": [
+        "get_per_campaign_metrics_ad_campaigns_metrics_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "PostDetail",
+      "file": "components/post-detail.tsx",
+      "purpose": "Complete screen for one social post: content, edit, schedule, publish, cancel, delete.",
+      "operations": [
+        "get_social_post_social_posts__post_id__get",
+        "update_social_post_social_posts__post_id__patch",
+        "publish_social_post_social_posts__post_id__publish_post",
+        "cancel_social_post_social_posts__post_id__cancel_post",
+        "delete_social_post_social_posts__post_id__delete",
+        "schedule_social_post_social_posts__post_id__schedule_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CampaignDetail",
+      "file": "components/campaign-detail.tsx",
+      "purpose": "Complete screen for one ad campaign: fields, results, refresh, retry, stop and delete.",
+      "operations": [
+        "list_ad_campaigns_ad_campaigns_get",
+        "get_per_campaign_metrics_ad_campaigns_metrics_get",
+        "refresh_campaign_status_ad_campaigns__campaign_id__status_refresh_post",
+        "retry_campaign_launch_ad_campaigns__campaign_id__retry_post",
+        "delete_ad_campaign_ad_campaigns__campaign_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CreativeDetail",
+      "file": "components/creative-detail.tsx",
+      "purpose": "Complete screen for one ad creative: image, copy, edit, new image, gallery, delete.",
+      "operations": [
+        "get_ad_creative_ad_creatives__creative_id__get",
+        "get_ad_creative_status_ad_creatives__creative_id__status_get",
+        "update_ad_creative_ad_creatives__creative_id__patch",
+        "move_ad_creative_to_gallery_ad_creatives__creative_id__move_to_gallery_post",
+        "regenerate_ad_creative_image_ad_creatives__creative_id__regenerate_image_post",
+        "delete_ad_creative_ad_creatives__creative_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "AudienceSyncDetail",
+      "file": "components/audience-sync-detail.tsx",
+      "purpose": "Complete screen for one audience sync: status, runs, errors, sync now, pause, launch campaign, delete.",
+      "operations": [
+        "list_sync_runs_audience_syncs__config_id__runs_get",
+        "list_audience_syncs_audience_syncs_get",
+        "list_sync_errors_audience_syncs__config_id__errors_get",
+        "launch_ad_campaign_audience_syncs__config_id__launch_post",
+        "trigger_audience_sync_audience_syncs__config_id__trigger_post",
+        "update_audience_sync_audience_syncs__config_id__patch",
+        "delete_audience_sync_audience_syncs__config_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "external",
+        "destructive"
+      ]
     }
   ],
   "hooks": [
@@ -251,6 +349,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400"
   }
 }

package/blocks/social-ads/components/ad-campaign-list.tsx

@@ -27,26 +27,30 @@ import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
 import { AD_PLATFORMS, formatDateOnly, formatMoney, launchOutcome, listOf, metricsFor } from "../lib/social-ads-types";
 import type { AdCampaign, CampaignMetric } from "../lib/social-ads-types";
+import { DEFAULT_BRAND, useBrand } from "@/g8/hooks/use-brand";
 
 export interface AdCampaignListProps {
   /** Change to reload, for example after AudienceSync launched a campaign. */
   refreshKey?: number;
+  /** Called when a person opens a campaign (show a CampaignDetail). */
+  onSelectCampaign?: (campaign: AdCampaign) => void;
   className?: string;
 }
 
 type Pending = { kind: "refresh" | "retry" | "delete"; campaign: AdCampaign } | { kind: "refreshAll" };
 const COLUMNS = 8;
 
-function copyFor(p: Pending | null): { tier: ConfirmTier; title: string; text: string; label: string } {
+function copyFor(p: Pending | null, platform: string = DEFAULT_BRAND.linkLabel): { tier: ConfirmTier; title: string; text: string; label: string } {
   if (!p) return { tier: "external", title: "", text: "", label: "Confirm" };
   if (p.kind === "refreshAll") return { tier: "external", title: "Refresh every campaign's status", text: "Asks each ad platform for the current review state of every campaign. Can take a while; campaigns that did refresh keep their new state if it times out.", label: "Refresh all" };
   const name = p.campaign.name;
   if (p.kind === "refresh") return { tier: "external", title: `Refresh "${name}"`, text: `Asks ${p.campaign.platform} for this campaign's current review state.`, label: "Refresh" };
   if (p.kind === "retry") return { tier: "external", title: `Retry launching "${name}"`, text: `Sends the campaign to ${p.campaign.platform} again. It may start spending on that platform once approved.`, label: "Retry launch" };
-  return { tier: "destructive", title: `Stop and delete "${name}"`, text: `Stops the campaign on ${p.campaign.platform} first, then removes it from graph8 together with its history. This cannot be undone. If ${p.campaign.platform} refuses to stop it, the campaign stays live and keeps spending.`, label: "Stop and delete" };
+  return { tier: "destructive", title: `Stop and delete "${name}"`, text: `Stops the campaign on ${p.campaign.platform} first, then removes it from ${platform} together with its history. This cannot be undone. If ${p.campaign.platform} refuses to stop it, the campaign stays live and keeps spending.`, label: "Stop and delete" };
 }
 
-export function AdCampaignList({ refreshKey = 0, className }: AdCampaignListProps) {
+export function AdCampaignList({ refreshKey = 0, onSelectCampaign, className }: AdCampaignListProps) {
+  const brand = useBrand();
   const [platform, setPlatform] = useState("");
   const [days, setDays] = useState(30);
   const [pending, setPending] = useState<Pending | null>(null);
@@ -84,7 +88,7 @@ export function AdCampaignList({ refreshKey = 0, className }: AdCampaignListProp
     }
   };
 
-  const copy = copyFor(pending);
+  const copy = copyFor(pending, brand.linkLabel);
   return (
     <div className={`flex flex-col gap-3 ${className ?? ""}`}>
       <div className="flex flex-wrap items-center gap-2">
@@ -110,7 +114,7 @@ export function AdCampaignList({ refreshKey = 0, className }: AdCampaignListProp
               const mine = busy === String(c.id);
               return (
                 <TableRow key={c.id} data-testid="campaign">
-                  <TableCell><div className="font-medium">{c.name}</div>{m ? <div className="text-xs text-muted-foreground">{formatMoney(m.spend, m.currency ?? c.currency)} spent</div> : null}</TableCell>
+                  <TableCell>{onSelectCampaign ? <button type="button" className="font-medium hover:underline" onClick={() => onSelectCampaign(c)}>{c.name}</button> : <div className="font-medium">{c.name}</div>}{m ? <div className="text-xs text-muted-foreground">{formatMoney(m.spend, m.currency ?? c.currency)} spent</div> : null}</TableCell>
                   <TableCell>{c.platform}</TableCell>
                   <TableCell>{c.status}</TableCell>
                   <TableCell>{formatMoney(c.daily_budget, c.currency)}</TableCell>