@graph8/sdk 0.308.1 → 0.357.0

package/blocks/inbox/block.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "inbox",
+  "title": "AI inbox",
+  "summary": "Unified reply inbox for email, SMS and LinkedIn: thread list, conversation view, AI-drafted replies, tagging and assignment.",
+  "features": [
+    "one queue across email, SMS and LinkedIn with channel and status filters",
+    "conversation view with unsent drafts flagged",
+    "AI draft (confirmed, billable) and send (confirmed, external) in one composer",
+    "tag and assign teammates",
+    "drop-in two-pane InboxScreen"
+  ],
+  "dependsOn": [
+    "crm",
+    "mailboxes"
+  ],
+  "operations": [
+    "assign_reply_inbox__reply_id__assign_post",
+    "create_inbox_tag_inbox_tags_post",
+    "generate_inbox_draft_inbox_drafts_generate_post",
+    "get_reply_inbox__reply_id__get",
+    "list_inbox_inbox_get",
+    "list_inbox_users_inbox_users_get",
+    "send_reply_inbox__reply_id__send_post",
+    "tag_reply_inbox__reply_id__tag_post"
+  ],
+  "components": [
+    {
+      "name": "InboxList",
+      "file": "components/inbox-list.tsx",
+      "purpose": "Paged table of conversations across email, SMS and LinkedIn with channel and status filters.",
+      "operations": [
+        "list_inbox_inbox_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ThreadView",
+      "file": "components/thread-view.tsx",
+      "purpose": "One conversation with contact, tags, assignees and unsent drafts; renders your controls under the messages.",
+      "operations": [
+        "get_reply_inbox__reply_id__get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ReplyComposer",
+      "file": "components/reply-composer.tsx",
+      "purpose": "Write a reply, draft or reshape it with AI (confirm, billable) and send it on the thread's channel (confirm, external).",
+      "operations": [
+        "generate_inbox_draft_inbox_drafts_generate_post",
+        "send_reply_inbox__reply_id__send_post"
+      ],
+      "tiers": [
+        "billable",
+        "external"
+      ]
+    },
+    {
+      "name": "TagAndAssign",
+      "file": "components/tag-and-assign.tsx",
+      "purpose": "Create and apply tags and assign a teammate, each behind a confirm dialog.",
+      "operations": [
+        "assign_reply_inbox__reply_id__assign_post",
+        "create_inbox_tag_inbox_tags_post",
+        "list_inbox_users_inbox_users_get",
+        "tag_reply_inbox__reply_id__tag_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    },
+    {
+      "name": "InboxScreen",
+      "file": "components/inbox-screen.tsx",
+      "purpose": "Finished two-pane inbox composing the list, thread view, composer and tag/assign panel.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "ThreadBadge",
+      "file": "components/thread-badge.tsx",
+      "purpose": "Small status pill shared by the thread view and tag panel.",
+      "operations": [],
+      "tiers": []
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useInboxThreads",
+      "file": "hooks/use-inbox-threads.ts",
+      "purpose": "One page of the unified inbox, refetched when a filter or the page changes.",
+      "operations": [
+        "list_inbox_inbox_get"
+      ]
+    },
+    {
+      "name": "useInboxThread",
+      "file": "hooks/use-inbox-thread.ts",
+      "purpose": "One conversation with its messages, drafts included.",
+      "operations": [
+        "get_reply_inbox__reply_id__get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/inbox-types.ts",
+      "purpose": "Thread, message, tag and assignee types plus HTML-to-text, label and date helpers."
+    },
+    {
+      "file": "lib/idempotency.ts",
+      "purpose": "useIdempotencyKey: one Idempotency-Key per distinct payload, rotated when the body changes so an edited retry never hits a 409."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/01-triage-and-reply.ts",
+      "title": "Triage the inbox and answer a reply",
+      "when": "A job or agent that reads new replies, drafts with AI (billable) and sends (external) after a human approves."
+    },
+    {
+      "file": "recipes/02-tag-and-assign.ts",
+      "title": "Tag a conversation and assign it",
+      "when": "Routing replies to the right teammate with a tag; both calls are external and need approval."
+    },
+    {
+      "file": "recipes/03-hot-contacts-digest.ts",
+      "title": "Digest of engaging contacts and unowned threads",
+      "when": "A read-only morning summary of who to answer first."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "connected-mailbox",
+      "description": "At least one connected sending mailbox (Google or Microsoft OAuth) so email threads exist and email replies can be sent. The OAuth connect flow is only in the graph8 app.",
+      "where": "app",
+      "verify": "Open app.graph8.com, Settings, Mailboxes: the mailbox shows Connected. Then GET /inbox returns email threads."
+    },
+    {
+      "id": "inbox-scopes",
+      "description": "The proxy's API key needs inbox:read and inbox:write for the screens, inbox:run for AI drafts and sending.",
+      "where": "api",
+      "verify": "`g8.api.me.describeCurrentKey()` lists inbox:read, inbox:write and inbox:run."
+    },
+    {
+      "id": "credits",
+      "description": "AI drafts charge credits (HTTP 402 when the org has none). There is no balance read, so the dialog shows no estimate.",
+      "where": "api",
+      "verify": "POST /inbox/drafts/generate returns 200, not 402."
+    }
+  ],
+  "scopes": [
+    "inbox:read",
+    "inbox:run",
+    "inbox:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Which AI operation the Draft button uses",
+      "default": "generate_from_scratch grounded in the thread; shorten, expand and fix grammar act on the text in the box",
+      "askHuman": false
+    },
+    {
+      "decision": "Whether the person sees every AI draft before it is sent",
+      "default": "Always: a draft is only written into the reply box; sending is a separate confirmed click",
+      "askHuman": false
+    },
+    {
+      "decision": "Default tone and goal of AI drafts",
+      "default": "professional / follow_up",
+      "askHuman": false
+    },
+    {
+      "decision": "Where to get the list of tags the picker offers (no list-tags operation exists)",
+      "default": "Pass availableTags from your own state; tags created in the panel are added for the session",
+      "askHuman": true
+    },
+    {
+      "decision": "Filter by assignee",
+      "default": "Not offered: the API cannot filter by an arbitrary assignee email (an org key owns no threads). Filter thread.assignees client-side",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/inbox/components/inbox-list.tsx

@@ -0,0 +1,156 @@
+"use client";
+
+/**
+ * InboxList: the unified reply queue (email, SMS and LinkedIn) with channel and status filters and paging.
+ *
+ * SDK operations, in order:
+ *   1. GET /inbox?channel=&status=&tag=&page=&page_size=   (inbox.listInbox)   read
+ * Nothing here sends, spends or deletes, so there is no ConfirmSpendDialog.
+ *
+ * Wire it to a detail pane with `onSelect`; the row gives you `thread.id` and `thread.channel`, which are
+ * the two things ThreadView needs.
+ */
+import { useState } from "react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useInboxThreads, type InboxFilters } from "../hooks/use-inbox-threads";
+import {
+  INBOX_CHANNELS,
+  INBOX_STATUSES,
+  contactLabel,
+  formatWhen,
+  latestMessage,
+  previewText,
+  type InboxChannel,
+  type InboxThread,
+} from "../lib/inbox-types";
+
+export interface InboxListProps {
+  onSelect?: (thread: InboxThread) => void;
+  selectedId?: string | null;
+  /** Start with these filters (for example a tag id from the URL). */
+  initialFilters?: InboxFilters;
+  pageSize?: number;
+  /** Fires when a filter changes. The selection no longer matches the list, so clear it (InboxScreen does). */
+  onFiltersChange?: (filters: InboxFilters) => void;
+  className?: string;
+}
+
+function ChannelFilter({ value, onChange }: { value?: InboxChannel; onChange: (next?: InboxChannel) => void }) {
+  return (
+    <div role="group" aria-label="Channel" className="flex gap-1">
+      <Button size="sm" variant={value ? "outline" : "default"} onClick={() => onChange(undefined)}>
+        All
+      </Button>
+      {INBOX_CHANNELS.map((c) => (
+        <Button key={c.value} size="sm" variant={value === c.value ? "default" : "outline"} onClick={() => onChange(c.value)}>
+          {c.label}
+        </Button>
+      ))}
+    </div>
+  );
+}
+
+function LoadingRows() {
+  return (
+    <div className="space-y-2 p-3" aria-busy="true" aria-label="Loading threads">
+      {Array.from({ length: 6 }, (_, i) => (
+        <Skeleton key={i} className="h-10 w-full" />
+      ))}
+    </div>
+  );
+}
+
+export function InboxList({ onSelect, selectedId, initialFilters, pageSize = 25, onFiltersChange, className }: InboxListProps) {
+  const [filters, setFilters] = useState<InboxFilters>(initialFilters ?? {});
+  const [page, setPage] = useState(1);
+  const { threads, loading, error, hasNext, total, refetch } = useInboxThreads(filters, page, pageSize);
+
+  const update = (patch: Partial<InboxFilters>) => {
+    const next = { ...filters, ...patch };
+    setFilters(next);
+    setPage(1);
+    onFiltersChange?.(next);
+  };
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <ChannelFilter value={filters.channel} onChange={(channel) => update({ channel })} />
+        <div className="flex items-center gap-2">
+          <select
+            aria-label="Status"
+            className="h-8 rounded-md border bg-background px-2 text-sm"
+            value={filters.status ?? ""}
+            onChange={(e) => update({ status: e.target.value || undefined })}
+          >
+            <option value="">Any status</option>
+            {INBOX_STATUSES.map((s) => (
+              <option key={s} value={s}>
+                {s.replace("_", " ").toLowerCase()}
+              </option>
+            ))}
+          </select>
+          <Button size="sm" variant="ghost" onClick={() => void refetch()}>
+            Refresh
+          </Button>
+        </div>
+      </div>
+
+      {error ? (
+        <ApiError error={error} title="Could not load the inbox" onRetry={() => void refetch()} />
+      ) : loading && threads.length === 0 ? (
+        <LoadingRows />
+      ) : threads.length === 0 ? (
+        <EmptyState
+          title="No conversations match"
+          description="Replies from sequences, SMS and LinkedIn land here. Clear the filters, or enroll contacts in a sequence to get replies."
+        />
+      ) : (
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Contact</TableHead>
+              <TableHead>Latest message</TableHead>
+              <TableHead>Channel</TableHead>
+              <TableHead>Updated</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {threads.map((thread) => (
+              <TableRow
+                key={`${thread.channel}:${thread.id}`}
+                data-state={selectedId === thread.id ? "selected" : undefined}
+                className="cursor-pointer"
+                onClick={() => onSelect?.(thread)}
+              >
+                <TableCell className="max-w-48 truncate font-medium">{contactLabel(thread)}</TableCell>
+                <TableCell className="max-w-80 truncate text-muted-foreground">
+                  {thread.subject ? <span className="text-foreground">{thread.subject} </span> : null}
+                  {previewText(thread)}
+                </TableCell>
+                <TableCell className="capitalize">{thread.channel}</TableCell>
+                <TableCell className="whitespace-nowrap text-muted-foreground">
+                  {formatWhen(thread.updated_at ?? latestMessage(thread)?.date)}
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
+        <span>{total != null ? `${total.toLocaleString()} conversations` : `Page ${page}`}</span>
+        <div className="flex gap-2">
+          <Button size="sm" variant="outline" disabled={page <= 1 || loading} onClick={() => setPage((p) => p - 1)}>
+            Previous
+          </Button>
+          <Button size="sm" variant="outline" disabled={!hasNext || loading} onClick={() => setPage((p) => p + 1)}>
+            Next
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/blocks/inbox/components/inbox-screen.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+/**
+ * InboxScreen: the finished two-pane inbox. List on the left; on the right the open conversation with its
+ * reply composer and tag/assign panel. Copy it as the page, or take the four parts it composes.
+ *
+ * SDK operations: none of its own. It composes InboxList (read), ThreadView (read), ReplyComposer
+ * (billable draft, external send) and TagAndAssign (external). The dialogs live in those parts.
+ */
+import { useMemo, useState } from "react";
+import { EmptyState } from "@/g8/components/empty-state";
+import type { InboxFilters } from "../hooks/use-inbox-threads";
+import type { InboxTag, InboxThread } from "../lib/inbox-types";
+import { InboxList } from "./inbox-list";
+import { ReplyComposer } from "./reply-composer";
+import { TagAndAssign } from "./tag-and-assign";
+import { ThreadView } from "./thread-view";
+
+export interface InboxScreenProps {
+  initialFilters?: InboxFilters;
+  /** Tags the person can apply. There is no list-tags operation; keep this list in your app. */
+  availableTags?: InboxTag[];
+  className?: string;
+}
+
+export function InboxScreen({ initialFilters, availableTags, className }: InboxScreenProps) {
+  const [open, setOpen] = useState<InboxThread | null>(null);
+  const tags = useMemo(() => availableTags ?? [], [availableTags]);
+
+  return (
+    <div className={`grid gap-4 lg:grid-cols-[minmax(0,2fr)_minmax(0,3fr)] ${className ?? ""}`}>
+      <InboxList onFiltersChange={() => setOpen(null)} initialFilters={initialFilters} selectedId={open?.id} onSelect={setOpen} />
+      <div className="min-w-0">
+        {open ? (
+          <ThreadView key={`${open.channel}:${open.id}`} thread={open}>
+            {(thread, reload) => (
+              <div className="space-y-3">
+                <ReplyComposer thread={thread} onSent={reload} />
+                <TagAndAssign thread={thread} availableTags={tags} onChanged={reload} />
+              </div>
+            )}
+          </ThreadView>
+        ) : (
+          <EmptyState title="Select a conversation" description="Pick a reply on the left to read it and respond." />
+        )}
+      </div>
+    </div>
+  );
+}

package/blocks/inbox/components/reply-composer.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+/**
+ * ReplyComposer: write a reply, optionally with AI, and send it on the thread's own channel.
+ *
+ * SDK operations, in order:
+ *   1. POST /inbox/drafts/generate   (aiInbox.generateInboxDraft)   BILLABLE  -> ConfirmSpendDialog first
+ *      generate_from_scratch grounded in the thread, or shorten / expand / fix_grammar_spelling on your text.
+ *      Returns { content (HTML), plain_content }; it delivers NOTHING.
+ *   2. POST /inbox/{reply_id}/send   (inbox.sendReply)   EXTERNAL   -> ConfirmSpendDialog first
+ *      Reaches a real person and cannot be recalled. A fixed Idempotency-Key per compose makes a double
+ *      click or a retry safe.
+ *
+ * Both calls are gated by tier: nothing is billed or sent until the person clicks the dialog's button.
+ */
+import { useEffect, useRef, useState } from "react";
+import { useIdempotencyKey } from "../lib/idempotency";
+import { Button, Input, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { replyRecipient, stripHtml, type InboxThread } from "../lib/inbox-types";
+
+type DraftOperation = "generate_from_scratch" | "shorten" | "expand" | "fix_grammar_spelling";
+type Pending = { kind: "draft"; operation: DraftOperation } | { kind: "send" } | null;
+
+export interface ReplyComposerProps {
+  thread: InboxThread;
+  /** Called after the send succeeds; reload the thread here. */
+  onSent?: (result: { message_id?: string | null; status: string }) => void;
+  className?: string;
+}
+
+const TONES = ["professional", "friendly", "casual", "assertive", "empathetic"] as const;
+const OBJECTIVES = ["follow_up", "book_meeting", "handle_objection", "provide_value", "close_deal"] as const;
+const DRAFT_LABEL: Record<DraftOperation, string> = {
+  generate_from_scratch: "Draft with AI",
+  shorten: "Shorten",
+  expand: "Expand",
+  fix_grammar_spelling: "Fix grammar",
+};
+
+/** The API only drafts for these two channel types; LinkedIn drafts use the account-based flow. */
+function draftChannel(channel: string): "email" | "sms" | undefined {
+  return channel === "email" || channel === "sms" ? channel : undefined;
+}
+
+export function ReplyComposer({ thread, onSent, className }: ReplyComposerProps) {
+  const channel = String(thread.channel);
+  const [body, setBody] = useState("");
+  const [subject, setSubject] = useState(thread.subject ? (/^re:/i.test(thread.subject) ? thread.subject : `Re: ${thread.subject}`) : "");
+  const [to, setTo] = useState(replyRecipient(thread));
+  const [tone, setTone] = useState<(typeof TONES)[number]>("professional");
+  const [objective, setObjective] = useState<(typeof OBJECTIVES)[number]>("follow_up");
+  const [pending, setPending] = useState<Pending>(null);
+  const idempotency = useIdempotencyKey(JSON.stringify([thread.channel, thread.id, body, to, channel === "email" ? subject : null]));
+  const threadKey = `${thread.channel}:${thread.id}`;
+  const currentThread = useRef(threadKey);
+  currentThread.current = threadKey;
+
+  // Stale context: a different conversation starts with a clean composer and a fresh idempotency key.
+  useEffect(() => {
+    setBody("");
+    setSubject(thread.subject ? (/^re:/i.test(thread.subject) ? thread.subject : `Re: ${thread.subject}`) : "");
+    setTo(replyRecipient(thread));
+    setPending(null);
+    draft.reset();
+    send.reset();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [thread.id, thread.channel]);
+
+  const draft = useG8Mutation(async (operation: DraftOperation) => {
+    const env = await g8Post<{ content?: string; plain_content?: string }>("/inbox/drafts/generate", {
+      operation,
+      conversation_id: thread.id,
+      channel_type: draftChannel(channel),
+      message_html: operation === "generate_from_scratch" ? "" : body,
+      tone,
+      objective: operation === "generate_from_scratch" ? objective : undefined,
+    });
+    return env.data;
+  });
+
+  const send = useG8Mutation(async () => {
+    const env = await g8Post<{ message_id?: string | null; status: string }>(
+      `/inbox/${encodeURIComponent(thread.id)}/send`,
+      { body, channel, subject: channel === "email" ? subject : undefined, to: to || undefined },
+      { idempotencyKey: idempotency.get() },
+    );
+    return env.data;
+  });
+
+  const confirm = async () => {
+    const current = pending;
+    if (!current) return;
+    const startedFor = threadKey; // a result that arrives after the person switched conversation is dropped
+    try {
+      if (current.kind === "draft") {
+        const result = await draft.mutateAsync(current.operation);
+        if (currentThread.current === startedFor) setBody(result.plain_content ?? stripHtml(result.content));
+      } else {
+        const result = await send.mutateAsync(undefined);
+        idempotency.rotate();
+        if (currentThread.current === startedFor) setBody("");
+        onSent?.(result);
+      }
+      if (currentThread.current === startedFor) setPending(null);
+    } catch {
+      if (currentThread.current === startedFor) setPending(null); // the error renders below; the person can retry
+    }
+  };
+
+  const busy = draft.loading || send.loading;
+  const canSend = body.trim().length > 0 && (channel === "linkedin" || to.trim().length > 0) && !busy;
+  const canTransform = body.trim().length > 0 && !busy;
+  const canDraft = Boolean(draftChannel(channel));
+
+  return (
+    <div className={`space-y-2 rounded-lg border p-3 ${className ?? ""}`}>
+      {channel === "email" ? (
+        <Input aria-label="Subject" placeholder="Subject" value={subject} onChange={(e) => setSubject(e.target.value)} />
+      ) : null}
+      <Input aria-label="To" placeholder={channel === "sms" ? "Phone number" : "Recipient"} value={to} onChange={(e) => setTo(e.target.value)} />
+      <Textarea aria-label="Reply" rows={6} placeholder="Write your reply" value={body} onChange={(e) => setBody(e.target.value)} />
+
+      {canDraft ? (
+        <div className="flex flex-wrap items-center gap-2 text-sm">
+          <select aria-label="Tone" className="h-8 rounded-md border bg-background px-2" value={tone} onChange={(e) => setTone(e.target.value as (typeof TONES)[number])}>
+            {TONES.map((t) => (
+              <option key={t}>{t}</option>
+            ))}
+          </select>
+          <select aria-label="Goal" className="h-8 rounded-md border bg-background px-2" value={objective} onChange={(e) => setObjective(e.target.value as (typeof OBJECTIVES)[number])}>
+            {OBJECTIVES.map((o) => (
+              <option key={o} value={o}>
+                {o.replace("_", " ")}
+              </option>
+            ))}
+          </select>
+          <Button size="sm" variant="outline" disabled={busy} onClick={() => setPending({ kind: "draft", operation: "generate_from_scratch" })}>
+            {DRAFT_LABEL.generate_from_scratch}
+          </Button>
+          {(["shorten", "expand", "fix_grammar_spelling"] as const).map((op) => (
+            <Button key={op} size="sm" variant="ghost" disabled={!canTransform} onClick={() => setPending({ kind: "draft", operation: op })}>
+              {DRAFT_LABEL[op]}
+            </Button>
+          ))}
+        </div>
+      ) : null}
+
+      {draft.error ? <ApiError error={draft.error} title="Could not write the draft" /> : null}
+      {send.error ? <ApiError error={send.error} title="Could not send the reply" onRetry={() => setPending({ kind: "send" })} /> : null}
+
+      <div className="flex justify-end">
+        <Button disabled={!canSend} onClick={() => setPending({ kind: "send" })}>
+          Send reply
+        </Button>
+      </div>
+
+      <ConfirmSpendDialog
+        open={pending?.kind === "draft"}
+        tier="billable"
+        title={pending?.kind === "draft" ? `${DRAFT_LABEL[pending.operation]} (AI)` : ""}
+        description="The draft is written into the box above. Nothing is sent. Each AI draft charges credits; you will not be charged for editing it."
+        confirmLabel="Write draft"
+        confirming={draft.loading}
+        onConfirm={() => void confirm()}
+        onCancel={() => setPending(null)}
+      />
+      <ConfirmSpendDialog
+        open={pending?.kind === "send"}
+        tier="external"
+        title={`Send this ${channel} reply?`}
+        description={`It goes to ${to || "the contact"} from your connected ${channel === "email" ? "mailbox" : channel} account.`}
+        recipients={1}
+        confirming={send.loading}
+        onConfirm={() => void confirm()}
+        onCancel={() => setPending(null)}
+      />
+    </div>
+  );
+}