@graph8/sdk 0.308.1 → 0.357.0

package/blocks/nurture/README.md

@@ -0,0 +1,110 @@
+# nurture
+
+Lifecycle email series for people who **agreed to hear from you** (welcome, onboarding, re-engagement). A nurture
+is a sequence of kind `nurture`: a few emails sent from **one pinned mailbox** to an audience **list**, stopping per
+contact when they reply. It is not cold outreach (use the `sequencer` block for that). Going live reaches real people,
+so launch is tier `external` and is confirmed with the audience size.
+
+## Install
+
+```
+npx @graph8/sdk add nurture
+```
+
+Installs `foundation`, `crm` and `lists` first if missing. Everything lands under `g8/nurture/`.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| graph8 | Nurture is controlled by a platform-wide switch (`ENABLE_NURTURE`), which is **on** in graph8 production. If it is ever switched off, every `/nurtures` call answers `404 "Nurture is not enabled"`; the components show a "not enabled" panel instead of an error. Nothing to request per workspace. | `GET /api/v1/nurtures` returns 200. |
+| graph8 app | A **connected mailbox**. Google and Microsoft sign-in only works inside the app, never through the API. | `GET /api/v1/mailboxes/my` lists a non-archived mailbox. |
+| The business | A **consented audience**: a list of people who opted in. A person ticks the consent box before Go live. | The owner can say where and when each contact opted in. |
+| graph8 key | `sequences:run` to launch (separate from `sequences:write`). | `g8.api.me.describeCurrentKey()` |
+| Your app | `allowedPrefixes` must include `nurtures`, `mailboxes`, `lists`, `analytics`. | The route file lists them. |
+
+## The flow, in order (IDs passed between steps)
+
+1. **Sender**: `listMyMailboxes` -> pick one -> **`mailbox.id`**, `mailbox.email`, `mailbox.channel_type`.
+2. **Audience**: a list id (`listLists`, or create one with the `lists` block) -> **`list.id`**.
+3. **Create**: `createNurture({ name, pinned_mailbox_id: mailbox.id, associated_list_id: list.id, steps, channels })` -> **`nurture.id`** (a string).
+   - `steps[]`: `{ step_order, step_type: "EMAIL", input_type: "MANUAL_TEMPLATE", time_interval: <seconds before the step>, step_data: { subject, body, email_type: "plain" } }`. Step 1 has `time_interval: 0`.
+   - `channels[]`: exactly the pinned mailbox: `{ channel_id: mailbox.id, channel_value: mailbox.email, channel_type: mailbox.channel_type }`. Any other email channel is rejected.
+   - The result is a **draft**. The mailbox and the steps cannot be changed afterwards through this API; to change them, `duplicateNurture` and rebuild.
+4. **Audience membership**: "enrolling" a contact = `addContactsToList(list.id, { contact_ids })`. `updateNurture({ associated_list_id })` re-points the nurture at another list (drafts only in the UI).
+5. **Launch**: `NurtureEnroll` shows the audience size (`contact_count`), requires the consent box, then `launchNurture(nurture.id)` behind `ConfirmSpendDialog`.
+   It runs the same enrollment, schedule and consent checks as the app's Go Live button.
+6. **Run**: `pauseNurture` (immediate), `resumeNurture` (confirmed here, because sending restarts), `duplicateNurture`, `deleteNurture` (archives; a live one is wound down first).
+7. **Results**: `NurtureStats` reads `getNurture`, the audience size, and `getSequencePerformanceById` (contacts, emails sent, replies, meetings; cached about 5 minutes).
+
+```tsx
+// app/nurtures/page.tsx
+"use client";
+import { useState } from "react";
+import { NurtureBuilder } from "@/g8/nurture/components/nurture-builder";
+import { NurtureEnroll } from "@/g8/nurture/components/nurture-enroll";
+import { NurtureStats } from "@/g8/nurture/components/nurture-stats";
+
+export default function Page() {
+  const [id, setId] = useState<string | null>(null);
+  return (
+    <>
+      <NurtureBuilder onSelectNurture={(n) => setId(n.id)} />
+      {id ? (<><NurtureEnroll nurtureId={id} /><NurtureStats nurtureId={id} /></>) : null}
+    </>
+  );
+}
+```
+
+## Default decisions (do not ask the human unless marked)
+
+| Decision | Default | Ask? |
+|---|---|---|
+| Reply behaviour | Stop a contact's series when they reply | no |
+| Opt-out line | Always on (`include_unsubscribe_cta: true`); never turn it off | no |
+| Wait between emails | 3 days (the API takes seconds: days x 86400) | no |
+| Which mailbox sends | The first connected mailbox of the key's owner | **yes** |
+| Launching | Never without the audience size confirmed and the consent box ticked | no |
+
+## Things that surprise people
+
+- **`pinned_mailbox_id` is required and immutable.** A nurture without one is rejected; an email channel on another mailbox is rejected.
+- **There is no nurture analytics endpoint and no enroll endpoint.** Enrollment is list membership; results come from the outbound sequence report (an empty report is "no sends yet", not an error).
+- **`createNurture`, `updateNurture`, `pauseNurture`, `resumeNurture`, `duplicateNurture` are tier `write`; only `launchNurture` is `external`.** The block still confirms resume, because it restarts real sending.
+- **`is_shared: true` is a 403 for API keys today** (org-wide sharing needs an Admin role the API key path does not carry). Nurtures made through the API are personal.
+- **Status names**: a new nurture is `drafted`; running ones read as live/paused; finished ones as completed/terminated. The helpers match loosely (`isDrafted`, `isLiveLike`).
+
+## Recipes (server-side, `recipes/`)
+
+- `create-a-nurture.ts`: mailbox, audience list, drafted nurture with two emails.
+- `enroll-contacts-and-launch.ts`: add consented contacts; launch only with explicit approval.
+- `nurture-health-check.ts`: status and recent results for every nurture.
+
+## What is in the block
+
+| Component | File | What it is |
+|---|---|---|
+| `NurtureBuilder` | `components/nurture-builder.tsx` | List your nurtures; create, edit, pause, resume, duplicate and archive them. |
+| `NurtureForm` | `components/nurture-form.tsx` | Create a nurture (name, sender mailbox, audience, email steps) or edit its settings. |
+| `NurtureEnroll` | `components/nurture-enroll.tsx` | Choose the audience list, attest consent, optionally add selected contacts, and launch with the audience size confirmed. |
+| `NurtureStats` | `components/nurture-stats.tsx` | Nurture status, audience size and reply/meeting results from the outbound sequence report. |
+
+## Operations
+
+Tiers: `read` and `write` need no confirmation; `external` (launch) and `destructive` (archive) always open `ConfirmSpendDialog` first.
+
+| Operation | Method and path | Tier | Scope | Used by |
+|---|---|---|---|---|
+| `sequences.listNurtures` | `GET /api/v1/nurtures` | read | `sequences:read` | NurtureBuilder |
+| `sequences.pauseNurture` | `POST /api/v1/nurtures/{nurture_id}/pause` | write | `sequences:write` | NurtureBuilder |
+| `sequences.resumeNurture` | `POST /api/v1/nurtures/{nurture_id}/resume` | write | `sequences:write` | NurtureBuilder |
+| `sequences.duplicateNurture` | `POST /api/v1/nurtures/{nurture_id}/duplicate` | write | `sequences:write` | NurtureBuilder |
+| `sequences.deleteNurture` | `DELETE /api/v1/nurtures/{nurture_id}` | destructive | `sequences:delete` | NurtureBuilder |
+| `mailboxes.listMyMailboxes` | `GET /api/v1/mailboxes/my` | read | `campaigns:read` | NurtureForm |
+| `lists.listLists` | `GET /api/v1/lists` | read | `lists:read` | NurtureForm, NurtureEnroll, NurtureStats |
+| `sequences.createNurture` | `POST /api/v1/nurtures` | write | `sequences:write` | NurtureForm |
+| `sequences.updateNurture` | `PATCH /api/v1/nurtures/{nurture_id}` | write | `sequences:write` | NurtureForm, NurtureEnroll |
+| `sequences.getNurture` | `GET /api/v1/nurtures/{nurture_id}` | read | `sequences:read` | NurtureEnroll, NurtureStats |
+| `lists.addContactsToList` | `POST /api/v1/lists/{list_id}/contacts` | write | `lists:write` | NurtureEnroll |
+| `sequences.launchNurture` | `POST /api/v1/nurtures/{nurture_id}/launch` | external | `sequences:run` | NurtureEnroll |
+| `analytics.getSequencePerformanceById` | `GET /api/v1/analytics/outbound/sequence-performance/{sequence_id}` | read | `analytics:read` | NurtureStats |

package/blocks/nurture/block.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "nurture",
+  "title": "Nurture",
+  "summary": "Build email nurtures for consented audiences: create, choose the audience, launch with confirmation, pause, resume, copy and read results.",
+  "features": [
+    "create a nurture with emails and one pinned mailbox",
+    "audience list and consent attestation before launch",
+    "launch confirmed with the audience size",
+    "pause, resume, duplicate, archive",
+    "status, audience and reply results"
+  ],
+  "dependsOn": [
+    "lists"
+  ],
+  "operations": [
+    "list_nurtures_nurtures_get",
+    "pause_nurture_nurtures__nurture_id__pause_post",
+    "resume_nurture_nurtures__nurture_id__resume_post",
+    "duplicate_nurture_nurtures__nurture_id__duplicate_post",
+    "delete_nurture_nurtures__nurture_id__delete",
+    "list_my_mailboxes_mailboxes_my_get",
+    "list_lists_lists_get",
+    "create_nurture_nurtures_post",
+    "update_nurture_nurtures__nurture_id__patch",
+    "get_nurture_nurtures__nurture_id__get",
+    "add_contacts_to_list_lists__list_id__contacts_post",
+    "launch_nurture_nurtures__nurture_id__launch_post",
+    "get_sequence_performance_by_id_analytics_outbound_sequence_performance__sequence_id__get"
+  ],
+  "components": [
+    {
+      "name": "NurtureBuilder",
+      "file": "components/nurture-builder.tsx",
+      "purpose": "List your nurtures; create, edit, pause, resume, duplicate and archive them.",
+      "operations": [
+        "list_nurtures_nurtures_get",
+        "pause_nurture_nurtures__nurture_id__pause_post",
+        "resume_nurture_nurtures__nurture_id__resume_post",
+        "duplicate_nurture_nurtures__nurture_id__duplicate_post",
+        "delete_nurture_nurtures__nurture_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "NurtureForm",
+      "file": "components/nurture-form.tsx",
+      "purpose": "Create a nurture (name, sender mailbox, audience, email steps) or edit its settings.",
+      "operations": [
+        "list_my_mailboxes_mailboxes_my_get",
+        "list_lists_lists_get",
+        "create_nurture_nurtures_post",
+        "update_nurture_nurtures__nurture_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "NurtureEnroll",
+      "file": "components/nurture-enroll.tsx",
+      "purpose": "Choose the audience list, attest consent, optionally add selected contacts, and launch with the audience size confirmed.",
+      "operations": [
+        "get_nurture_nurtures__nurture_id__get",
+        "list_lists_lists_get",
+        "update_nurture_nurtures__nurture_id__patch",
+        "add_contacts_to_list_lists__list_id__contacts_post",
+        "launch_nurture_nurtures__nurture_id__launch_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    },
+    {
+      "name": "NurtureStats",
+      "file": "components/nurture-stats.tsx",
+      "purpose": "Nurture status, audience size and reply/meeting results from the outbound sequence report.",
+      "operations": [
+        "get_nurture_nurtures__nurture_id__get",
+        "list_lists_lists_get",
+        "get_sequence_performance_by_id_analytics_outbound_sequence_performance__sequence_id__get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/nurture-types.ts",
+      "purpose": "Nurture/mailbox/list types, status predicates, and the step and channel payload builders."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/create-a-nurture.ts",
+      "title": "Create a drafted nurture with its emails, pinned to one mailbox",
+      "when": "Setting up a lifecycle series for consented contacts."
+    },
+    {
+      "file": "recipes/enroll-contacts-and-launch.ts",
+      "title": "Add consented contacts to the audience and, with approval, launch",
+      "when": "A contact opted in and should start the series; launching needs a person's yes."
+    },
+    {
+      "file": "recipes/nurture-health-check.ts",
+      "title": "Check every nurture's status and recent results",
+      "when": "A daily check or dashboard backend."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "nurture-enabled",
+      "description": "Nurture is behind a feature flag: every nurtures call answers 404 \"Nurture is not enabled\" until graph8 turns it on for the workspace. Components show an explanation instead of an error.",
+      "where": "api",
+      "verify": "GET /api/v1/nurtures returns 200."
+    },
+    {
+      "id": "connected-mailbox",
+      "description": "At least one mailbox connected in the graph8 app. A nurture is pinned to ONE mailbox. Google and Microsoft sign-in can only be done in the app.",
+      "where": "api",
+      "verify": "GET /api/v1/mailboxes/my lists a non-archived mailbox."
+    },
+    {
+      "id": "consented-audience",
+      "description": "A list of people who agreed to hear from you. A nurture is for consented audiences, not cold outreach (use the sequencer for that). A human confirms consent before launch.",
+      "where": "app",
+      "verify": "The owner confirmed where and when each contact opted in."
+    },
+    {
+      "id": "launch-scope",
+      "description": "Launching needs the sequences:run scope (an external operation), separate from sequences:write.",
+      "where": "api",
+      "verify": "g8.api.me.describeCurrentKey() lists sequences:run."
+    },
+    {
+      "id": "proxy-allowlist",
+      "description": "Add \"nurtures\", \"mailboxes\", \"lists\" and \"analytics\" to allowedPrefixes in app/api/g8/[...path]/route.ts.",
+      "where": "app",
+      "verify": "The route file's allowedPrefixes contains them."
+    }
+  ],
+  "scopes": [
+    "analytics:read",
+    "campaigns:read",
+    "lists:read",
+    "lists:write",
+    "sequences:delete",
+    "sequences:read",
+    "sequences:run",
+    "sequences:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Reply behaviour",
+      "default": "Stop nurturing a contact when they reply (finish_on_reply true)",
+      "askHuman": false
+    },
+    {
+      "decision": "Opt-out line",
+      "default": "Append the opt-out line to every email (include_unsubscribe_cta true); never turn it off",
+      "askHuman": false
+    },
+    {
+      "decision": "Wait between emails",
+      "default": "3 days (the API takes seconds: days x 86400)",
+      "askHuman": false
+    },
+    {
+      "decision": "Which mailbox sends",
+      "default": "The first connected mailbox of the key's owner",
+      "askHuman": true
+    },
+    {
+      "decision": "Launching",
+      "default": "Never launch without the person confirming the audience size and the consent box",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/nurture/components/nurture-builder.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+/**
+ * NurtureBuilder: your nurtures, create a new one, edit, pause, resume, copy and archive.
+ *
+ * SDK operations, in order:
+ *   1. listNurtures (GET /nurtures?page&limit)               read         (your own plus org-shared)
+ *   2. NurtureForm: listMyMailboxes, listLists, createNurture, updateNurture   (see that file)
+ *   3. pauseNurture (POST /nurtures/{id}/pause)              write        (stops further sends)
+ *   4. resumeNurture (POST /nurtures/{id}/resume)            write       -> confirmed anyway: sending restarts to real people
+ *   5. duplicateNurture (POST /nurtures/{id}/duplicate)      write        (a drafted copy owned by you, no channels)
+ *   6. deleteNurture (DELETE /nurtures/{id})                 destructive  -> ConfirmSpendDialog (archives; a live one is wound down first)
+ * Going live is NOT here: NurtureEnroll launches (external) after the audience and consent are confirmed.
+ * The API is behind a feature flag and answers 404 "Nurture is not enabled" until it is on.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, 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 { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { isFinished, isLiveLike, isNurtureOff, isPaused, statusOf } from "../lib/nurture-types";
+import type { Nurture } from "../lib/nurture-types";
+import { NurtureForm } from "./nurture-form";
+
+export interface NurtureBuilderProps {
+  /** Called when a nurture is chosen for launch/enrollment (render NurtureEnroll with its id). */
+  onSelectNurture?: (nurture: Nurture) => void;
+  pageSize?: number;
+}
+
+type Action = { kind: "pause" | "duplicate"; nurture: Nurture };
+
+export function NurtureBuilder({ onSelectNurture, pageSize = 50 }: NurtureBuilderProps) {
+  const [form, setForm] = useState<{ nurture?: Nurture } | null>(null);
+  const [toArchive, setToArchive] = useState<Nurture | null>(null);
+  const [toResume, setToResume] = useState<Nurture | null>(null);
+  const list = useG8Query((signal) => g8Get<{ nurtures?: Nurture[] }>("/nurtures", { page: 1, limit: pageSize }, { signal }).then((r) => r.data?.nurtures ?? []), [pageSize]);
+  const [busy, setBusy] = useState<string | null>(null);
+  const act = useG8Mutation((a: Action) => g8Post(`/nurtures/${encodeURIComponent(a.nurture.id)}/${a.kind}`, a.kind === "duplicate" ? {} : undefined), { onSuccess: () => void list.refetch() });
+  const run = async (a: Action): Promise<void> => {
+    setBusy(a.nurture.id);
+    await act.mutate(a);
+    setBusy(null);
+  };
+  const resume = useG8Mutation((n: Nurture) => g8Post(`/nurtures/${encodeURIComponent(n.id)}/resume`), { onSuccess: () => { setToResume(null); void list.refetch(); } });
+  const archive = useG8Mutation((n: Nurture) => g8Delete(`/nurtures/${encodeURIComponent(n.id)}`), { onSuccess: () => { setToArchive(null); void list.refetch(); } });
+
+  if (isNurtureOff(list.error)) return <EmptyState title="Nurture is not enabled" description="Nurture is behind a feature flag for this workspace. Ask graph8 to turn it on, then reload." />;
+  if (list.error) return <ApiError error={list.error} title="Could not load nurtures" onRetry={() => void list.refetch()} />;
+  if (form) {
+    return (
+      <Card>
+        <CardHeader><CardTitle>{form.nurture ? `Edit ${form.nurture.name}` : "New nurture"}</CardTitle></CardHeader>
+        <CardContent><NurtureForm nurture={form.nurture} onCancel={() => setForm(null)} onSaved={() => { setForm(null); void list.refetch(); }} /></CardContent>
+      </Card>
+    );
+  }
+  const nurtures = list.data ?? [];
+  return (
+    <div className="grid gap-3">
+      <div className="flex items-center justify-between">
+        <h2 className="text-lg font-semibold">Nurtures</h2>
+        <Button onClick={() => setForm({})}>New nurture</Button>
+      </div>
+      {act.error ? <ApiError error={act.error} title="That did not work" /> : null}
+      {list.loading && !list.data ? <div aria-busy="true" className="grid gap-2"><Skeleton className="h-14 w-full" /><Skeleton className="h-14 w-full" /></div> : nurtures.length === 0 ? (
+        <EmptyState title="No nurtures yet" description="A nurture sends a short series of emails to people who agreed to hear from you." action={<Button onClick={() => setForm({})}>New nurture</Button>} />
+      ) : (
+        <ul className="grid gap-2">
+          {nurtures.map((n) => (
+            <li key={n.id} className="flex flex-wrap items-center justify-between gap-2 rounded-md border p-3">
+              <div>
+                <p className="font-medium">{n.name}</p>
+                <p className="text-muted-foreground text-xs">{statusOf(n)}{n.is_shared ? " · shared" : ""}</p>
+              </div>
+              <div className="flex flex-wrap gap-1">
+                {onSelectNurture ? <Button size="sm" variant="outline" onClick={() => onSelectNurture(n)}>Audience and launch</Button> : null}
+                {isLiveLike(n) ? <Button size="sm" variant="ghost" loading={busy === n.id} disabled={busy !== null} onClick={() => void run({ kind: "pause", nurture: n })}>Pause</Button> : null}
+                {isPaused(n) ? <Button size="sm" variant="ghost" onClick={() => setToResume(n)}>Resume</Button> : null}
+                {!isFinished(n) ? <Button size="sm" variant="ghost" onClick={() => setForm({ nurture: n })}>Edit</Button> : null}
+                <Button size="sm" variant="ghost" disabled={busy !== null} onClick={() => void run({ kind: "duplicate", nurture: n })}>Duplicate</Button>
+                {!isFinished(n) ? <Button size="sm" variant="ghost" onClick={() => setToArchive(n)}>Archive</Button> : null}
+              </div>
+            </li>
+          ))}
+        </ul>
+      )}
+      <ConfirmSpendDialog
+        open={toResume !== null}
+        tier="external"
+        title={`Resume ${toResume?.name ?? "this nurture"}?`}
+        description={<><p>Emails start going out again to the contacts who have not finished it.</p>{resume.error ? <ApiError error={resume.error} title="Could not resume" /> : null}</>}
+        confirmLabel="Resume"
+        confirming={resume.loading}
+        onCancel={() => setToResume(null)}
+        onConfirm={() => { if (toResume) void resume.mutate(toResume); }}
+      />
+      <ConfirmSpendDialog
+        open={toArchive !== null}
+        tier="destructive"
+        title={`Archive ${toArchive?.name ?? "this nurture"}?`}
+        description={<><p>{toArchive && isLiveLike(toArchive) ? "It is paused and wound down first, then archived. Contacts stop receiving its emails." : "It is archived and no longer runs."}</p>{archive.error ? <ApiError error={archive.error} title="Could not archive" /> : null}</>}
+        confirmLabel="Archive"
+        confirming={archive.loading}
+        onCancel={() => setToArchive(null)}
+        onConfirm={() => { if (toArchive) void archive.mutate(toArchive); }}
+      />
+    </div>
+  );
+}

package/blocks/nurture/components/nurture-enroll.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+/**
+ * NurtureEnroll: choose who a nurture engages, confirm they consented, and take it live.
+ *
+ * SDK operations, in order:
+ *   1. getNurture (GET /nurtures/{id})                                   read
+ *   2. listLists (GET /lists)                                            read      (the audience; its contact_count is the recipient count)
+ *   3. updateNurture (PATCH /nurtures/{id}, associated_list_id)          write     (point the nurture at a list)
+ *   4. addContactsToList (POST /lists/{list_id}/contacts)                write     (optional: add specific contacts to the audience)
+ *   5. launchNurture (POST /nurtures/{id}/launch)                        external  -> ConfirmSpendDialog with the audience size
+ * "Enrolling" a contact means putting them in the nurture's audience list; the nurture engages that list once launched.
+ * Launch runs the same enrollment, schedule and consent checks as the app's Go Live button. The consent box is a
+ * human attestation in YOUR UI (the API does not take one): keep it, it is what keeps this a nurture and not spam.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, 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 { 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 { isDrafted, isNurtureMissing, isNurtureOff, statusOf } from "../lib/nurture-types";
+import type { ListOption, Nurture } from "../lib/nurture-types";
+
+export interface NurtureEnrollProps {
+  nurtureId: string;
+  /** Contact ids (for example selected in a contacts table) to add to the audience list. */
+  contactIds?: readonly number[];
+  onLaunched?: () => void;
+}
+
+export function NurtureEnroll({ nurtureId, contactIds = [], onLaunched }: NurtureEnrollProps) {
+  const base = `/nurtures/${encodeURIComponent(nurtureId)}`;
+  const nurture = useG8Query((signal) => g8Get<Nurture>(base, {}, { signal }).then((r) => r.data), [base]);
+  const lists = useG8Query((signal) => g8Get<ListOption[]>("/lists", { limit: 200 }, { signal }).then((r) => r.data ?? []), []);
+  const [listId, setListId] = useState("");
+  const [consent, setConsent] = useState(false);
+  const [confirming, setConfirming] = useState(false);
+
+  // Consent and a half-chosen list belong to ONE nurture.
+  useEffect(() => {
+    setConsent(false);
+    setConfirming(false);
+    setListId("");
+  }, [nurtureId]);
+
+  useEffect(() => {
+    if (nurture.data?.associated_list_id) setListId(String(nurture.data.associated_list_id));
+  }, [nurture.data?.associated_list_id]);
+
+  const setAudience = useG8Mutation((id: number) => g8Patch<Nurture>(base, { associated_list_id: id }), { onSuccess: () => void nurture.refetch() });
+  const addContacts = useG8Mutation((id: number) => g8Post(`/lists/${id}/contacts`, { contact_ids: [...contactIds] }), { onSuccess: () => void lists.refetch() });
+  const launch = useG8Mutation(() => g8Post(`${base}/launch`), { onSuccess: () => { setConfirming(false); void nurture.refetch(); onLaunched?.(); } });
+
+  if (isNurtureOff(nurture.error)) return <EmptyState title="Nurture is not enabled" description="Nurture is behind a feature flag for this workspace. Ask graph8 to turn it on." />;
+  if (isNurtureMissing(nurture.error)) return <EmptyState title="This nurture no longer exists" description="It may have been deleted, or it is not yours to see. Pick another nurture." />;
+  if (nurture.error) return <ApiError error={nurture.error} title="Could not load the nurture" onRetry={() => void nurture.refetch()} />;
+  if (!nurture.data) return <Skeleton className="h-40 w-full" aria-busy="true" />;
+
+  const list = (lists.data ?? []).find((l) => String(l.id) === listId);
+  const attached = nurture.data.associated_list_id ? String(nurture.data.associated_list_id) === listId : false;
+  const audience = list?.contact_count ?? 0;
+  const canLaunch = isDrafted(nurture.data) && attached && audience > 0 && consent;
+  return (
+    <Card>
+      <CardHeader><CardTitle>{nurture.data.name} <span className="text-muted-foreground text-sm font-normal">{statusOf(nurture.data)}</span></CardTitle></CardHeader>
+      <CardContent className="grid gap-4">
+        <div className="grid max-w-md gap-1">
+          <label htmlFor="g8-nurture-audience" className="text-sm font-medium">Audience list</label>
+          <select id="g8-nurture-audience" className="border-input bg-background h-9 rounded-md border px-2 text-sm" value={listId} disabled={!isDrafted(nurture.data)} onChange={(e) => setListId(e.target.value)}>
+            <option value="">Choose a list</option>
+            {(lists.data ?? []).map((l) => <option key={l.id} value={l.id}>{l.title} ({(l.contact_count ?? 0).toLocaleString()})</option>)}
+          </select>
+          <div className="flex gap-2">
+            <Button size="sm" variant="outline" loading={setAudience.loading} disabled={!listId || attached || !isDrafted(nurture.data)} onClick={() => void setAudience.mutate(Number(listId))}>Use this list</Button>
+            {contactIds.length > 0 ? <Button size="sm" variant="outline" loading={addContacts.loading} disabled={!attached} onClick={() => void addContacts.mutate(Number(listId))}>Add {contactIds.length} selected {contactIds.length === 1 ? "contact" : "contacts"}</Button> : null}
+          </div>
+          {attached ? <p className="text-sm">This nurture will engage <strong>{audience.toLocaleString()}</strong> {audience === 1 ? "contact" : "contacts"}.</p> : null}
+        </div>
+        {[setAudience.error, addContacts.error].filter(Boolean).map((e, i) => <ApiError key={i} error={e} title="That did not work" />)}
+        {isDrafted(nurture.data) ? (
+          <div className="grid gap-3">
+            <label className="flex items-start gap-2 text-sm">
+              <input type="checkbox" className="mt-1" checked={consent} onChange={(e) => setConsent(e.target.checked)} />
+              <span>Everyone in this list agreed to hear from us. I can show where and when.</span>
+            </label>
+            <div><Button disabled={!canLaunch} onClick={() => setConfirming(true)}>Go live</Button></div>
+          </div>
+        ) : <p className="text-sm">This nurture is {statusOf(nurture.data)}. Use the Nurtures list to pause or resume it.</p>}
+        <ConfirmSpendDialog
+          open={confirming}
+          tier="external"
+          title={`Launch "${nurture.data.name}" to ${audience.toLocaleString()} contacts?`}
+          recipients={audience}
+          description={<><p>The first email goes out to real people as soon as the schedule allows, and follow-ups continue until each contact replies or finishes.</p>{launch.error ? <ApiError error={launch.error} title="Could not launch" /> : null}</>}
+          confirmLabel="Launch"
+          confirming={launch.loading}
+          onCancel={() => setConfirming(false)}
+          onConfirm={() => void launch.mutate(undefined)}
+        />
+      </CardContent>
+    </Card>
+  );
+}

package/blocks/nurture/components/nurture-form.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+/**
+ * NurtureForm: create a nurture (name, sender mailbox, audience, email steps) or edit its settings.
+ *
+ * SDK operations, in order:
+ *   1. listMyMailboxes (GET /mailboxes/my)              read    (a nurture is pinned to ONE mailbox, chosen at creation, immutable)
+ *   2. listLists (GET /lists)                           read    (the consented audience)
+ *   3. createNurture (POST /nurtures)                   write   (a DRAFT: nothing is sent until launch)
+ *   4. updateNurture (PATCH /nurtures/{id})             write   (name, description, audience, reply/threading/unsubscribe flags)
+ * The steps and the sender cannot be changed after creation through this API: to change them, duplicate and recreate.
+ * Launching is NurtureEnroll's job, behind a confirmation with the audience size.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+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 { channelPayload, stepsPayload } from "../lib/nurture-types";
+import type { ListOption, MailboxOption, Nurture, StepDraft } from "../lib/nurture-types";
+
+export interface NurtureFormProps {
+  /** Edit this nurture; omit to create a new one. */
+  nurture?: Nurture;
+  onSaved: (nurture: Nurture) => void;
+  onCancel?: () => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm disabled:opacity-50";
+
+export function NurtureForm({ nurture, onSaved, onCancel }: NurtureFormProps) {
+  const editing = Boolean(nurture);
+  const [name, setName] = useState(nurture?.name ?? "");
+  const [description, setDescription] = useState(nurture?.description ?? "");
+  const [mailboxId, setMailboxId] = useState<string>(nurture?.pinned_mailbox_id ? String(nurture.pinned_mailbox_id) : "");
+  const [listId, setListId] = useState<string>(nurture?.associated_list_id ? String(nurture.associated_list_id) : "");
+  const [finishOnReply, setFinishOnReply] = useState(nurture?.finish_on_reply ?? true);
+  const [sameThread, setSameThread] = useState(nurture?.send_in_same_thread ?? true);
+  const [unsubscribe, setUnsubscribe] = useState(nurture?.include_unsubscribe_cta ?? true);
+  const [steps, setSteps] = useState<StepDraft[]>([{ waitDays: 0, subject: "", body: "" }]);
+  const mailboxes = useG8Query((signal) => g8Get<{ mailboxes?: MailboxOption[] }>("/mailboxes/my", {}, { signal }).then((r) => (r.data?.mailboxes ?? []).filter((m) => !m.is_archived)), []);
+  const lists = useG8Query((signal) => g8Get<ListOption[]>("/lists", { limit: 200 }, { signal }).then((r) => r.data ?? []), []);
+
+  const mailbox = (mailboxes.data ?? []).find((m) => String(m.id) === mailboxId);
+  const stepsOk = steps.length > 0 && steps.every((s) => s.subject.trim() && s.body.trim());
+  const valid = name.trim() !== "" && (editing || (Boolean(mailbox) && stepsOk));
+
+  const save = useG8Mutation(async () => {
+    const flags = { finish_on_reply: finishOnReply, send_in_same_thread: sameThread, include_unsubscribe_cta: unsubscribe };
+    if (nurture) {
+      return (await g8Patch<Nurture>(`/nurtures/${encodeURIComponent(nurture.id)}`, { name: name.trim(), description: description.trim() || null, associated_list_id: listId ? Number(listId) : null, ...flags })).data;
+    }
+    return (await g8Post<Nurture>("/nurtures", {
+      name: name.trim(),
+      description: description.trim() || undefined,
+      pinned_mailbox_id: mailbox!.id,
+      associated_list_id: listId ? Number(listId) : undefined,
+      ...flags,
+      steps: stepsPayload(steps),
+      channels: channelPayload(mailbox!),
+    })).data;
+  }, { onSuccess: onSaved });
+
+  const setStep = (i: number, patch: Partial<StepDraft>): void => setSteps((prev) => prev.map((s, at) => (at === i ? { ...s, ...patch } : s)));
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (valid) void save.mutate(undefined); }}>
+      <div><Label htmlFor="g8-nurture-name" className="mb-1">Name</Label><Input id="g8-nurture-name" value={name} onChange={(e) => setName(e.target.value)} /></div>
+      <div><Label htmlFor="g8-nurture-desc" className="mb-1">Description</Label><Textarea id="g8-nurture-desc" rows={2} value={description} onChange={(e) => setDescription(e.target.value)} /></div>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div>
+          <Label htmlFor="g8-nurture-mailbox" className="mb-1">Send from (one mailbox)</Label>
+          <select id="g8-nurture-mailbox" className={SELECT} value={mailboxId} disabled={editing} onChange={(e) => setMailboxId(e.target.value)}>
+            <option value="">{mailboxes.loading ? "Loading..." : "Choose a mailbox"}</option>
+            {(mailboxes.data ?? []).map((m) => <option key={m.id} value={m.id}>{m.email}</option>)}
+          </select>
+          {!editing && !mailboxes.loading && (mailboxes.data ?? []).length === 0 ? <p className="mt-1 text-xs text-amber-700">No mailbox is connected. Connect one in graph8 first (Google and Microsoft sign-in happens in the app).</p> : null}
+        </div>
+        <div>
+          <Label htmlFor="g8-nurture-list" className="mb-1">Audience list (consented contacts)</Label>
+          <select id="g8-nurture-list" className={SELECT} value={listId} onChange={(e) => setListId(e.target.value)}>
+            <option value="">Choose later</option>
+            {(lists.data ?? []).map((l) => <option key={l.id} value={l.id}>{l.title}</option>)}
+          </select>
+        </div>
+      </div>
+      <fieldset className="flex flex-wrap gap-4 text-sm">
+        <legend className="sr-only">Behaviour</legend>
+        <label className="flex items-center gap-2"><input type="checkbox" checked={finishOnReply} onChange={(e) => setFinishOnReply(e.target.checked)} />Stop for a contact when they reply</label>
+        <label className="flex items-center gap-2"><input type="checkbox" checked={sameThread} onChange={(e) => setSameThread(e.target.checked)} />Keep follow-ups in one thread</label>
+        <label className="flex items-center gap-2"><input type="checkbox" checked={unsubscribe} onChange={(e) => setUnsubscribe(e.target.checked)} />Add an opt-out line to every email</label>
+      </fieldset>
+      {editing ? <p className="text-muted-foreground text-sm">The emails and the sender are fixed once created. To change them, duplicate this nurture and build the copy.</p> : (
+        <div className="grid gap-3">
+          <h3 className="text-sm font-semibold">Emails</h3>
+          {steps.map((s, i) => (
+            <div key={i} className="grid gap-2 rounded-md border p-3">
+              <div className="flex items-end gap-2">
+                <span className="text-sm font-medium">Email {i + 1}</span>
+                {i > 0 ? (
+                  <div className="w-40"><Label htmlFor={`g8-step-wait-${i}`} className="mb-1">Wait (days)</Label><Input id={`g8-step-wait-${i}`} type="number" min={0} value={s.waitDays} onChange={(e) => setStep(i, { waitDays: Number(e.target.value) })} /></div>
+                ) : <span className="text-muted-foreground text-xs">Sent first, when you launch</span>}
+                {steps.length > 1 ? <Button type="button" size="sm" variant="ghost" onClick={() => setSteps((prev) => prev.filter((_, at) => at !== i))}>Remove</Button> : null}
+              </div>
+              <Input aria-label={`Subject ${i + 1}`} placeholder="Subject" value={s.subject} onChange={(e) => setStep(i, { subject: e.target.value })} />
+              <Textarea aria-label={`Body ${i + 1}`} rows={4} placeholder="Message" value={s.body} onChange={(e) => setStep(i, { body: e.target.value })} />
+            </div>
+          ))}
+          <div><Button type="button" size="sm" variant="outline" onClick={() => setSteps((prev) => [...prev, { waitDays: 3, subject: "", body: "" }])}>Add an email</Button></div>
+        </div>
+      )}
+      {save.error ? <ApiError error={save.error} title="Could not save the nurture" /> : null}
+      <div className="flex gap-2">
+        <Button type="submit" loading={save.loading} disabled={!valid}>{editing ? "Save changes" : "Create nurture"}</Button>
+        {onCancel ? <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+    </form>
+  );
+}