@graph8/sdk 0.303.0 → 0.357.0

package/blocks/inbox/components/tag-and-assign.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+/**
+ * TagAndAssign: apply tags to a conversation and hand it to a teammate.
+ *
+ * SDK operations, in order:
+ *   1. GET  /inbox/users                        (aiInbox.listInboxUsers)   read   - teammates you can assign to
+ *   2. POST /inbox/tags                         (aiInbox.createInboxTag)   write  - only when you type a new tag
+ *   3. POST /inbox/{reply_id}/tag?channel=      (inbox.tagReply)           EXTERNAL -> ConfirmSpendDialog first
+ *   4. POST /inbox/{reply_id}/assign?channel=   (inbox.assignReply)        EXTERNAL -> ConfirmSpendDialog first
+ * Tagging and assigning are classified `external` because they can fire tag automations and notify the
+ * assignee, so they are confirmed like a send.
+ *
+ * There is no "list tags" operation: pass `availableTags` (collect them from InboxList rows, or keep your
+ * own list) and newly created tags are added to the picker for the session.
+ */
+import { useEffect, useMemo, useState } from "react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import type { InboxTag, InboxThread } from "../lib/inbox-types";
+import { ThreadBadge } from "./thread-badge";
+
+type Pending = { kind: "tag"; ids: string[] } | { kind: "assign"; email: string } | null;
+interface TeamUser {
+  email: string;
+  name?: string | null;
+}
+
+export interface TagAndAssignProps {
+  thread: InboxThread;
+  availableTags?: InboxTag[];
+  /** Called after a tag or assignment succeeded; reload the thread here. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+function usersFrom(data: unknown): TeamUser[] {
+  const raw = Array.isArray(data) ? data : ((data as { items?: unknown[] } | null)?.items ?? []);
+  return (raw as TeamUser[]).filter((u) => typeof u?.email === "string");
+}
+
+export function TagAndAssign({ thread, availableTags = [], onChanged, className }: TagAndAssignProps) {
+  const [created, setCreated] = useState<InboxTag[]>([]);
+  const [selected, setSelected] = useState<string[]>([]);
+  const [newTag, setNewTag] = useState("");
+  const [assignee, setAssignee] = useState("");
+  const [pending, setPending] = useState<Pending>(null);
+  // Stale context: picks made for one conversation never carry over to the next.
+  useEffect(() => { setSelected([]); setAssignee(""); setNewTag(""); setPending(null); }, [thread.id, thread.channel]);
+  const channelQuery = { channel: String(thread.channel) };
+
+  const users = useG8Query(async (signal) => usersFrom((await g8Get("/inbox/users", undefined, { signal })).data), []);
+
+  const applied = new Set(thread.tags.map((t) => t.id));
+  const options = useMemo(() => {
+    const seen = new Map<string, InboxTag>();
+    for (const t of [...availableTags, ...created]) if (t.id && !applied.has(t.id)) seen.set(t.id, t);
+    return [...seen.values()];
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [availableTags, created, thread.tags]);
+
+  const createTag = useG8Mutation(async (name: string) => {
+    const env = await g8Post<{ id?: string; name?: string }>("/inbox/tags", { name });
+    return { id: String(env.data.id ?? ""), name: env.data.name ?? name } satisfies InboxTag;
+  });
+  const tag = useG8Mutation(async (ids: string[]) => {
+    // Only the NEW ids: association can fire tag automations, so already-applied tags are not re-sent.
+    return g8Post(`/inbox/${encodeURIComponent(thread.id)}/tag`, { tag_ids: ids.filter((id) => !applied.has(id)) }, { query: channelQuery });
+  });
+  const assign = useG8Mutation(async (email: string) =>
+    g8Post(`/inbox/${encodeURIComponent(thread.id)}/assign`, { assignee_email: email }, { query: channelQuery }),
+  );
+
+  const addTag = async () => {
+    const name = newTag.trim();
+    if (!name) return;
+    const made = await createTag.mutate(name);
+    if (made?.id) {
+      setCreated((prev) => [...prev, made]);
+      setSelected((prev) => [...prev, made.id as string]);
+      setNewTag("");
+    }
+  };
+
+  const confirm = async () => {
+    const current = pending;
+    if (!current) return;
+    try {
+      if (current.kind === "tag") {
+        await tag.mutateAsync(current.ids);
+        setSelected([]);
+      } else {
+        await assign.mutateAsync(current.email);
+        setAssignee("");
+      }
+      onChanged?.();
+    } catch {
+      /* surfaced by the ApiError below */
+    }
+    setPending(null);
+  };
+
+  const toggle = (id: string) => setSelected((prev) => (prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id]));
+  const team = users.data ?? [];
+
+  return (
+    <div className={`space-y-4 rounded-lg border p-3 text-sm ${className ?? ""}`}>
+      <section aria-label="Tags" className="space-y-2">
+        <h3 className="font-medium">Tags</h3>
+        <div className="flex flex-wrap gap-1">
+          {thread.tags.length === 0 ? <span className="text-muted-foreground">No tags yet</span> : null}
+          {thread.tags.map((t) => (
+            <ThreadBadge key={t.id ?? t.name}>{t.name ?? t.id}</ThreadBadge>
+          ))}
+        </div>
+        <div className="flex flex-wrap gap-2">
+          {options.map((t) => (
+            <label key={t.id} className="flex items-center gap-1">
+              <input type="checkbox" checked={selected.includes(t.id as string)} onChange={() => toggle(t.id as string)} />
+              {t.name}
+            </label>
+          ))}
+        </div>
+        <div className="flex gap-2">
+          <Input aria-label="New tag" placeholder="New tag name" value={newTag} onChange={(e) => setNewTag(e.target.value)} />
+          <Button size="sm" variant="outline" disabled={!newTag.trim() || createTag.loading} onClick={() => void addTag()}>
+            Create
+          </Button>
+        </div>
+        <Button size="sm" disabled={selected.length === 0 || tag.loading} onClick={() => setPending({ kind: "tag", ids: selected })}>
+          Apply {selected.length > 0 ? `${selected.length} ` : ""}tag{selected.length === 1 ? "" : "s"}
+        </Button>
+        {createTag.error ? <ApiError error={createTag.error} title="Could not create the tag" /> : null}
+        {tag.error ? <ApiError error={tag.error} title="Could not apply the tags" /> : null}
+      </section>
+
+      <section aria-label="Assignee" className="space-y-2">
+        <h3 className="font-medium">Assign to</h3>
+        {users.error ? <ApiError error={users.error} title="Could not load teammates" onRetry={() => void users.refetch()} /> : null}
+        <div className="flex gap-2">
+          <select
+            aria-label="Teammate"
+            className="h-9 flex-1 rounded-md border bg-background px-2"
+            value={assignee}
+            disabled={users.loading}
+            onChange={(e) => setAssignee(e.target.value)}
+          >
+            <option value="">{users.loading ? "Loading teammates..." : "Choose a teammate"}</option>
+            {team.map((u) => (
+              <option key={u.email} value={u.email}>
+                {u.name ? `${u.name} (${u.email})` : u.email}
+              </option>
+            ))}
+          </select>
+          <Button size="sm" disabled={!assignee || assign.loading} onClick={() => setPending({ kind: "assign", email: assignee })}>
+            Assign
+          </Button>
+        </div>
+        {assign.error ? <ApiError error={assign.error} title="Could not assign the conversation" /> : null}
+      </section>
+
+      <ConfirmSpendDialog
+        open={pending?.kind === "tag"}
+        tier="external"
+        title="Apply tags to this conversation?"
+        description="Tags can trigger inbox automations and notifications."
+        confirmLabel="Apply tags"
+        confirming={tag.loading}
+        onConfirm={() => void confirm()}
+        onCancel={() => setPending(null)}
+      />
+      <ConfirmSpendDialog
+        open={pending?.kind === "assign"}
+        tier="external"
+        title={`Assign to ${pending?.kind === "assign" ? pending.email : ""}?`}
+        description="They are notified that the conversation is theirs."
+        confirmLabel="Assign"
+        recipients={1}
+        confirming={assign.loading}
+        onConfirm={() => void confirm()}
+        onCancel={() => setPending(null)}
+      />
+    </div>
+  );
+}

package/blocks/inbox/components/thread-badge.tsx

@@ -0,0 +1,17 @@
+"use client";
+
+/**
+ * ThreadBadge: the small status pill ThreadView and TagAndAssign share. (The kit has no badge primitive; this is
+ * plain markup you can restyle.) No SDK operations.
+ */
+import type { ReactNode } from "react";
+
+const TONES = {
+  neutral: "bg-muted text-foreground",
+  info: "bg-blue-100 text-blue-900 dark:bg-blue-950 dark:text-blue-100",
+  warn: "bg-amber-100 text-amber-900 dark:bg-amber-950 dark:text-amber-100",
+} as const;
+
+export function ThreadBadge({ children, tone = "neutral" }: { children: ReactNode; tone?: keyof typeof TONES }) {
+  return <span className={`inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium ${TONES[tone]}`}>{children}</span>;
+}

package/blocks/inbox/components/thread-view.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+/**
+ * ThreadView: one conversation, oldest message first, with the contact, tags, assignees and any unsent
+ * drafts clearly marked. It owns no write: replying is ReplyComposer, tagging and assigning is TagAndAssign.
+ *
+ * SDK operations, in order:
+ *   1. GET /inbox/{reply_id}?channel=   (inbox.getReply)   read
+ * Never use GET /inbox/{reply_id}/draft to "preview" a draft: it is classified read but CHARGES CREDITS.
+ * AI drafting lives in ReplyComposer behind a confirm dialog (POST /inbox/drafts/generate, billable).
+ *
+ * Compose it: <ThreadView thread={t}>{(thread) => <ReplyComposer thread={thread} />}</ThreadView>
+ */
+import type { ReactNode } from "react";
+import { ThreadBadge } from "./thread-badge";
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useInboxThread } from "../hooks/use-inbox-thread";
+import { contactLabel, formatWhen, stripHtml, type InboxMessage, type InboxThread } from "../lib/inbox-types";
+
+export interface ThreadViewProps {
+  /** A row from InboxList. Only `id` and `channel` are required; the rest is loaded fresh. */
+  thread: Pick<InboxThread, "id" | "channel"> & Partial<InboxThread>;
+  /** Render controls under the messages; receives the freshly loaded thread and a reload function. */
+  children?: (thread: InboxThread, reload: () => void) => ReactNode;
+  className?: string;
+}
+
+function MessageBubble({ message, outbound }: { message: InboxMessage; outbound: boolean }) {
+  const text = stripHtml(message.content);
+  return (
+    <li
+      data-draft={message.is_draft ? "true" : undefined}
+      className={`max-w-[85%] rounded-lg border p-3 text-sm ${outbound ? "ml-auto bg-muted" : "bg-background"} ${
+        message.is_draft ? "border-dashed" : ""
+      }`}
+    >
+      <div className="mb-1 flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+        <span className="font-medium text-foreground">{message.from_address ?? "Unknown sender"}</span>
+        {message.responder ? <span>via {message.responder}</span> : null}
+        {message.date ? <span>{formatWhen(message.date)}</span> : null}
+        {message.is_draft ? <ThreadBadge tone="warn">Unsent draft</ThreadBadge> : null}
+      </div>
+      <p className="whitespace-pre-wrap">{text || "(no content)"}</p>
+    </li>
+  );
+}
+
+function ThreadHeader({ thread }: { thread: InboxThread }) {
+  return (
+    <header className="space-y-1 border-b pb-3">
+      <h2 className="text-base font-semibold">{thread.subject || contactLabel(thread)}</h2>
+      <p className="text-sm text-muted-foreground">
+        {contactLabel(thread)}
+        {thread.contact?.company ? ` at ${thread.contact.company}` : ""} · <span className="capitalize">{thread.channel}</span>
+        {thread.status ? ` · ${thread.status.toLowerCase().replace("_", " ")}` : ""}
+      </p>
+      <div className="flex flex-wrap gap-1">
+        {thread.tags.map((t) => (
+          <ThreadBadge key={t.id ?? t.name}>{t.name ?? t.id}</ThreadBadge>
+        ))}
+        {thread.assignees.map((a) => (
+          <ThreadBadge key={a.email} tone="info">
+            {a.name || a.email}
+          </ThreadBadge>
+        ))}
+      </div>
+    </header>
+  );
+}
+
+export function ThreadView({ thread: row, children, className }: ThreadViewProps) {
+  const { data, loading, error, refetch } = useInboxThread(row.id, row.channel);
+
+  if (error) return <ApiError error={error} title="Could not load this conversation" onRetry={() => void refetch()} />;
+  if (loading && !data) {
+    return (
+      <div className="space-y-2" aria-busy="true" aria-label="Loading conversation">
+        <Skeleton className="h-6 w-1/2" />
+        <Skeleton className="h-20 w-full" />
+        <Skeleton className="h-20 w-3/4" />
+      </div>
+    );
+  }
+  if (!data) return <EmptyState title="Conversation not found" description="It may have been removed or moved to another channel." />;
+
+  const contactAddress = (data.contact?.email ?? data.contact?.phone ?? "").toLowerCase();
+  return (
+    <section className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <ThreadHeader thread={data} />
+      {data.messages.length === 0 ? (
+        <EmptyState title="No messages yet" description="The first message appears here once the sequence or channel sends it." />
+      ) : (
+        <ol className="flex flex-col gap-2" aria-label="Messages">
+          {data.messages.map((m, i) => (
+            <MessageBubble
+              key={m.message_id ?? i}
+              message={m}
+              outbound={Boolean(m.from_address) && m.from_address?.toLowerCase() !== contactAddress}
+            />
+          ))}
+        </ol>
+      )}
+      {children?.(data, () => void refetch())}
+    </section>
+  );
+}

package/blocks/inbox/hooks/use-inbox-thread.ts

@@ -0,0 +1,24 @@
+"use client";
+
+/**
+ * useInboxThread: one conversation with all of its messages (drafts included, flagged `is_draft`).
+ *
+ * SDK operations: GET /inbox/{reply_id}?channel= (inbox.getReply), read tier.
+ *
+ * The `channel` is required by the API to disambiguate ids across email, SMS and LinkedIn; take it from
+ * the list row you opened.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import type { InboxThread } from "../lib/inbox-types";
+
+export function useInboxThread(threadId: string | null | undefined, channel: string | null | undefined) {
+  return useG8Query(
+    async (signal) => {
+      const env = await g8Get<InboxThread>(`/inbox/${encodeURIComponent(threadId as string)}`, { channel }, { signal });
+      return env.data;
+    },
+    [threadId, channel],
+    { enabled: Boolean(threadId) },
+  );
+}

package/blocks/inbox/hooks/use-inbox-threads.ts

@@ -0,0 +1,40 @@
+"use client";
+
+/**
+ * useInboxThreads: one page of the unified inbox, re-fetched when a filter or the page changes.
+ *
+ * SDK operations: GET /inbox (aiInbox / inbox.listInbox), read tier.
+ *
+ * Pagination here is page-number based (`page`, `page_size`, response `pagination.has_next`), unlike the
+ * cursor lists elsewhere in the API, so this hook wraps useG8Query rather than usePaginated.
+ *
+ * Caveat: the API cannot filter by an arbitrary assignee email, and an organisation API key owns no
+ * threads, so `assignee` is intentionally not exposed. Filter assignees client-side from `thread.assignees`.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import type { InboxChannel, InboxThread } from "../lib/inbox-types";
+
+export interface InboxFilters {
+  channel?: InboxChannel;
+  /** SENT, AI_RESPONDED or DRAFT. */
+  status?: string;
+  /** Tag id. */
+  tag?: string;
+  sequenceId?: string;
+}
+
+export function useInboxThreads(filters: InboxFilters, page = 1, pageSize = 25) {
+  const query = useG8Query(
+    async (signal) => {
+      const env = await g8Get<InboxThread[]>(
+        "/inbox",
+        { channel: filters.channel, status: filters.status, tag: filters.tag, sequence_id: filters.sequenceId, page, page_size: pageSize },
+        { signal },
+      );
+      return { threads: env.data ?? [], hasNext: Boolean(env.pagination?.has_next), total: (env.pagination as { total?: number } | undefined)?.total };
+    },
+    [filters.channel, filters.status, filters.tag, filters.sequenceId, page, pageSize],
+  );
+  return { ...query, threads: query.data?.threads ?? [], hasNext: query.data?.hasNext ?? false, total: query.data?.total };
+}

package/blocks/inbox/lib/idempotency.ts

@@ -0,0 +1,30 @@
+"use client";
+
+/**
+ * useIdempotencyKey: one Idempotency-Key per distinct payload.
+ *
+ * The API remembers a key together with a fingerprint of the request body. Replaying the SAME body under the same
+ * key is a safe retry (a double click, a timeout). Reusing the key with a DIFFERENT body is a 409 for as long as
+ * the server holds it, and after a 5xx on a send/booking it holds the failure under the key for minutes. So the
+ * key must follow the payload: pass a string that changes whenever anything in the request body changes.
+ *
+ *   const key = useIdempotencyKey(JSON.stringify([thread.id, body, to, subject]));
+ *   g8Post(path, payload, { idempotencyKey: key.get() });
+ *   // after a success: key.rotate()
+ */
+import { useRef } from "react";
+
+export function useIdempotencyKey(fingerprint: string) {
+  const ref = useRef({ fingerprint, key: crypto.randomUUID() });
+  return {
+    /** The key for the current payload; a new one as soon as the payload differs from the last call's. */
+    get(): string {
+      if (ref.current.fingerprint !== fingerprint) ref.current = { fingerprint, key: crypto.randomUUID() };
+      return ref.current.key;
+    },
+    /** Start a new logical request (call after a success so the next identical payload is a new action). */
+    rotate(): void {
+      ref.current = { fingerprint, key: crypto.randomUUID() };
+    },
+  };
+}

package/blocks/inbox/lib/inbox-types.ts

@@ -0,0 +1,100 @@
+"use client";
+
+/**
+ * Shapes and small helpers shared by the inbox components. The unified inbox (`GET /inbox`) returns one
+ * thread shape for email, SMS and LinkedIn; the field names below are the API's, not ours.
+ */
+
+export type InboxChannel = "email" | "sms" | "linkedin";
+export const INBOX_CHANNELS: ReadonlyArray<{ value: InboxChannel; label: string }> = [
+  { value: "email", label: "Email" },
+  { value: "sms", label: "SMS" },
+  { value: "linkedin", label: "LinkedIn" },
+];
+
+export interface InboxMessage {
+  message_id?: string | null;
+  content?: string | null;
+  date?: string | null;
+  from_address?: string | null;
+  to_addresses?: string[];
+  /** true for an unsent AI/human draft that lives in the thread. */
+  is_draft: boolean;
+  /** Who wrote it, when the API knows (a teammate or an agent). */
+  responder?: string | null;
+}
+
+export interface InboxTag {
+  id: string | null;
+  name: string | null;
+}
+
+export interface InboxAssignee {
+  email: string;
+  name?: string | null;
+}
+
+export interface InboxThread {
+  id: string;
+  channel: InboxChannel | string;
+  subject?: string | null;
+  /** Contact snapshot: name, email, company (and a phone or LinkedIn id for those channels). */
+  contact?: { name?: string | null; email?: string | null; company?: string | null; phone?: string | null } | null;
+  messages: InboxMessage[];
+  status?: string | null;
+  tags: InboxTag[];
+  assignees: InboxAssignee[];
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+
+/** Statuses `GET /inbox?status=` accepts (case-insensitive). Anything else is a 422. */
+export const INBOX_STATUSES = ["SENT", "AI_RESPONDED", "DRAFT"] as const;
+
+/** Plain text from the API's HTML message bodies. Good enough for previews and for the reply textarea. */
+export function stripHtml(html: string | null | undefined): string {
+  if (!html) return "";
+  return html
+    .replace(/<\s*br\s*\/?>/gi, "\n")
+    .replace(/<\/(p|div|li|h[1-6])>/gi, "\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export function contactLabel(thread: InboxThread): string {
+  const c = thread.contact;
+  return c?.name || c?.email || c?.phone || "Unknown contact";
+}
+
+/** The newest message that is not a draft, falling back to the newest of any kind. */
+export function latestMessage(thread: InboxThread): InboxMessage | undefined {
+  const real = thread.messages.filter((m) => !m.is_draft);
+  const list = real.length > 0 ? real : thread.messages;
+  return list[list.length - 1];
+}
+
+export function previewText(thread: InboxThread, max = 120): string {
+  const text = stripHtml(latestMessage(thread)?.content).replace(/\s+/g, " ");
+  return text.length > max ? `${text.slice(0, max - 1)}...` : text;
+}
+
+export function formatWhen(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toLocaleString(undefined, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+}
+
+/** Default recipient for a reply: the contact's address on the thread's channel. */
+export function replyRecipient(thread: InboxThread): string {
+  const c = thread.contact;
+  if (thread.channel === "sms") return c?.phone ?? "";
+  return c?.email ?? "";
+}

package/blocks/inbox/recipes/01-triage-and-reply.ts

@@ -0,0 +1,43 @@
+/**
+ * @title Triage the inbox and answer a reply (draft with AI, then send)
+ * @when A server job or agent that reads new replies and responds. Drafting CHARGES CREDITS (billable) and
+ * sending reaches a real person (external): ask a human before running steps 3 and 4. Never call
+ * GET /inbox/{id}/draft for a preview; it is classified read but spends credits too.
+ */
+import { randomUUID } from "node:crypto";
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+// 1. The newest email conversations. `data` is an array; `pagination.has_next` says if there is another page.
+const inbox = await g8.api.inbox.listInbox({ query: { channel: "email", page: 1, page_size: 20 } });
+const thread = inbox.data[0];
+if (!thread) throw new Error("The inbox is empty");
+
+// 2. The full conversation. `channel` is required because ids are only unique per channel.
+const full = await g8.api.inbox.getReply({ path: { reply_id: thread.id }, query: { channel: "email" } });
+const lastInbound = [...(full.data.messages ?? [])].reverse().find((m) => !m.is_draft);
+console.log(full.data.subject, "-", lastInbound?.content);
+
+// 3. BILLABLE: an AI draft grounded in the thread. It returns text and delivers nothing.
+const draft = await g8.api.aiInbox.generateInboxDraft({
+  body: {
+    operation: "generate_from_scratch",
+    conversation_id: thread.id,
+    channel_type: "email",
+    objective: "follow_up",
+    tone: "professional",
+    message_html: "",
+  },
+});
+const html = (draft.data as { content?: string }).content ?? "";
+
+// 4. EXTERNAL: send. Reuse the same idempotency key if you retry this exact call.
+const sent = await g8.api.inbox.sendReply(
+  {
+    path: { reply_id: thread.id },
+    body: { channel: "email", body: html, subject: full.data.subject ? `Re: ${full.data.subject}` : null },
+  },
+  { idempotencyKey: randomUUID() },
+);
+console.log(sent.data.status, sent.data.message_id);

package/blocks/inbox/recipes/02-tag-and-assign.ts

@@ -0,0 +1,31 @@
+/**
+ * @title Tag a conversation and assign it to a teammate
+ * @when Routing replies: create (or reuse) a tag, apply it, hand the thread to the right person. Tagging
+ * and assigning are tier `external` (they can fire automations and notify the assignee), so confirm with a
+ * human. There is no list-tags operation: remember the tag id from `createInboxTag`.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const threadId = process.argv[2];
+if (!threadId) throw new Error("usage: tsx 02-tag-and-assign.ts <thread id>");
+
+// Teammates you can assign to.
+const users = await g8.api.aiInbox.listInboxUsers();
+const teammate = (users.data.items as Array<{ email: string }>)[0];
+if (!teammate) throw new Error("No teammates found");
+
+// Create the tag once and keep its id. (A second create with the same name may conflict.)
+const created = await g8.api.aiInbox.createInboxTag({ body: { name: "Interested", ai_can_apply: false } });
+const tagId = String((created.data as { id?: string }).id);
+
+// Send the FULL set of tag ids the thread should carry: existing ids plus the new one.
+const thread = await g8.api.inbox.getReply({ path: { reply_id: threadId }, query: { channel: "email" } });
+const tagIds = [...(thread.data.tags ?? []).map((t) => String((t as { id?: string }).id)), tagId];
+await g8.api.inbox.tagReply({ path: { reply_id: threadId }, query: { channel: "email" }, body: { tag_ids: tagIds } });
+await g8.api.inbox.assignReply({
+  path: { reply_id: threadId },
+  query: { channel: "email" },
+  body: { assignee_email: teammate.email },
+});

package/blocks/inbox/recipes/03-hot-contacts-digest.ts

@@ -0,0 +1,16 @@
+/**
+ * @title Daily digest of the contacts who are engaging right now
+ * @when A morning job that tells a rep who to answer first. Read-only: it sends nothing and spends nothing.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const hot = await g8.api.inbox.hotContacts({ query: { days: 7, limit: 25 } });
+console.log(`Hot contacts in the last ${hot.data.days} days:`);
+for (const contact of hot.data.contacts ?? []) console.log(JSON.stringify(contact));
+
+// Open threads that nobody has taken yet: the ones to assign first.
+const inbox = await g8.api.inbox.listInbox({ query: { page_size: 50 } });
+const unowned = inbox.data.filter((t) => (t.assignees ?? []).length === 0);
+console.log(`${unowned.length} of ${inbox.data.length} conversations have no owner`);