@graph8/sdk 0.370.0 → 0.374.0

package/blocks/inbox/README.md

@@ -24,6 +24,21 @@ Defaults are unchanged from this release: both are on.
 
 Every detail opens as a full page with `&view=full` (the Open full page button).
 
+**Management (new, on by default; `showManagement={false}` hides the three buttons).** The toolbar gains:
+
+- **New message** (`ComposeMessage`): write a NEW email or text. The sender is never defaulted: you choose a mailbox
+  (from `GET /inbox/mailboxes/paginated`; ones you may not send as are listed disabled with the reason) or an SMS number,
+  and the confirm dialog names it ("from hamza@acme.com to maya@northwind.io, 2 recipients"). Sending is **external**.
+- **Search all** (`InboxSearch`): server-side search of every email thread (across all your mailboxes) or LinkedIn
+  conversation, beyond the page the list loaded; pick a result to open it. SMS has no search route in the API. A LinkedIn result opens by the row's conversation id (`conversation_id`, else `id`); that this equals the unified inbox's LinkedIn thread id has not been checked against a live HeyReach payload, so if a result opens as "Conversation not found", the id differs.
+- **Manage**: the tag library (`TagManager`: create, rename or recolour, delete; built-in tags follow the API's policy) and
+  `BlockedSenders` (block per mailbox, unblock). The tag list it loads also feeds the Tag filter and the tag picker.
+- In an open conversation, **Manage conversation** (`ThreadActions`): mark read (and unread on LinkedIn), remove a tag,
+  unassign a teammate, block the sender.
+
+A conversation this key cannot see (an org key sees shared threads only) or that was removed answers a uniform 404; the
+conversation view says "Conversation not found" instead of showing a generic failure.
+
 ## The flow, in order
 
 1. **List** `GET /inbox?channel=&status=&page=&page_size=` (`InboxList`). Each row has `id` and `channel`.
@@ -52,7 +67,8 @@ IDs passed between steps: `thread.id` + `thread.channel` (list -> view -> draft/
 
 - Connect a mailbox in the graph8 app (Google / Microsoft OAuth exists only there; see the `mailboxes` block).
   Until then the inbox has no email threads. `where: "app"`.
-- Give the proxy's API key `inbox:read`, `inbox:write` and `inbox:run` (and `campaigns:read` for the SMS sender picker).
+- Give the proxy's API key `inbox:read`, `inbox:write` and `inbox:run` (and `campaigns:read` for the SMS sender picker,
+  `inbox:delete` to delete a tag, remove a tag or teammate from a conversation or unblock a sender, `workflows:read` to list tags).
 - Credits for AI drafts (402 when none; there is no balance read, so the confirm dialog shows no estimate).
 
 ## Defaults (the agent does not need to ask)
@@ -62,9 +78,13 @@ IDs passed between steps: `thread.id` + `thread.channel` (list -> view -> draft/
 - A reply leaves from the thread's own mailbox, number or LinkedIn account and goes to the thread's contact.
 - No assignee filter: the API cannot filter by an arbitrary assignee email (an org key owns no threads), so
   filter `thread.assignees` client-side if you need it.
-- Ask the human only about **tags**: there is no list-tags operation. Pass `availableTags` from your own
-  state (collect them from `thread.tags` of loaded rows, or keep a list); tags created in the panel are
-  offered for the session.
+- Tags: `TagManager` lists them (`GET /workflows/inbox-tags`, scope `workflows:read`), so no input is needed. Pass
+  `availableTags` only to seed the pickers before the Manage sheet is opened; tags on loaded threads are always offered.
+- A NEW message is never sent without an explicit sender; the API refuses a compose without `from_mailbox` or
+  `from_number`, and this block does not guess one.
+- Not offered, because the API has no such operation: snooze, archive, mark an email or SMS unread. Not offered by
+  choice (see the PR): composing a NEW LinkedIn message (`/inbox/linkedin/compose` only continues an existing
+  conversation, which `ReplyComposer` already does), starring chats, internal comments, saving compose drafts.
 
 ## Gotchas
 
@@ -88,9 +108,30 @@ IDs passed between steps: `thread.id` + `thread.channel` (list -> view -> draft/
 | `aiInbox.createInboxTag` | POST /inbox/tags | write | TagAndAssign |
 | `inbox.tagReply` | POST /inbox/{reply_id}/tag | external | TagAndAssign |
 | `inbox.assignReply` | POST /inbox/{reply_id}/assign | external | TagAndAssign |
+| `aiInbox.listInboxMailboxesPaginated` | GET /inbox/mailboxes/paginated | read | ComposeMessage, InboxSearch, BlockedSenders |
+| `aiInbox.composeInboxEmail` | POST /inbox/emails/compose | external | ComposeMessage |
+| `aiInbox.composeInboxSms` | POST /inbox/sms/compose | external | ComposeMessage |
+| `inbox.searchInboxEmails` | POST /inbox/emails/search | read | InboxSearch |
+| `aiInbox.searchInboxLinkedinConversations` | POST /inbox/linkedin/conversations/search | read | InboxSearch |
+| `workflows.listInboxTags` | GET /workflows/inbox-tags | read | TagManager |
+| `aiInbox.updateInboxTag` | PUT /inbox/tags/{tag_id} | write | TagManager (changed fields only) |
+| `aiInbox.deleteInboxTag` | DELETE /inbox/tags/{tag_id} | destructive | TagManager |
+| `aiInbox.markInboxEmailRead` | POST /inbox/emails/{email_id}/mark-read | write | ThreadActions |
+| `aiInbox.markInboxSmsRead` | POST /inbox/sms/{thread_id}/mark-read | write | ThreadActions |
+| `aiInbox.markInboxLinkedinConversationRead` / `Unread` | POST /inbox/linkedin/accounts/{account_id}/conversations/{id}/read, /unread | write | ThreadActions |
+| `aiInbox.removeChannelTag` | DELETE /inbox/channels/{channel_id}/tags | destructive | ThreadActions |
+| `aiInbox.unassignChannel` | DELETE /inbox/channels/{channel_id}/assign | destructive | ThreadActions |
+| `aiInbox.blockInboxSender` | POST /inbox/blocked-senders | write | ThreadActions, BlockedSenders |
+| `aiInbox.listInboxBlockedSenders` | GET /inbox/blocked-senders | read | BlockedSenders |
+| `aiInbox.unblockInboxSender` | DELETE /inbox/blocked-senders/{blocked_sender_id} | destructive | BlockedSenders |
 
 ## Recipes (server side)
 
 - `01-triage-and-reply.ts`: list, read, AI draft (billable), send (external).
 - `02-tag-and-assign.ts`: create a tag, apply it, assign a teammate.
 - `03-hot-contacts-digest.ts`: read-only digest of engaging contacts and unowned threads.
+
+## Cross-block glue
+
+
+- `RecordConversationsTab` (`components/record-conversations-tab.tsx`): the email conversations with a contact. The inbox has no filter by contact id, so it matches the contact's email through `searchInboxEmails` (`search_emails`) across the mailboxes from `listInboxMailboxes`, 10 per page with "Load more"; opening a row reads `getReply`, and the API's uniform 404 for a hidden thread shows "not available to you" (no retry). `extraDetailTabs` entry for ContactsScreen.

package/blocks/inbox/block.json

@@ -2,13 +2,17 @@
   "$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.",
+  "summary": "Unified reply inbox for email, SMS and LinkedIn: threads, AI-drafted replies, new messages, search, read state, tag library, 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"
+    "drop-in two-pane InboxScreen",
+    "compose a new email or text from an explicit sender (confirmed)",
+    "server-side search across email and LinkedIn",
+    "tag library (create, rename, delete) and blocked senders",
+    "mark read or unread, remove a tag, unassign, block a sender"
   ],
   "dependsOn": [
     "crm",
@@ -16,15 +20,33 @@
   ],
   "operations": [
     "assign_reply_inbox__reply_id__assign_post",
+    "block_inbox_sender_inbox_blocked_senders_post",
+    "compose_inbox_email_inbox_emails_compose_post",
+    "compose_inbox_sms_inbox_sms_compose_post",
     "create_inbox_tag_inbox_tags_post",
+    "delete_inbox_tag_inbox_tags__tag_id__delete",
     "generate_inbox_draft_inbox_drafts_generate_post",
     "get_reply_inbox__reply_id__get",
+    "list_inbox_blocked_senders_inbox_blocked_senders_get",
     "list_inbox_inbox_get",
     "list_inbox_linkedin_accounts_inbox_linkedin_accounts_get",
+    "list_inbox_mailboxes_inbox_mailboxes_get",
+    "list_inbox_mailboxes_paginated_inbox_mailboxes_paginated_get",
+    "list_inbox_tags_workflows_inbox_tags_get",
     "list_inbox_users_inbox_users_get",
     "list_sms_phone_numbers_sms_phone_numbers_get",
+    "mark_inbox_email_read_inbox_emails__email_id__mark_read_post",
+    "mark_inbox_linkedin_conversation_read_inbox_linkedin_accounts__account_id__conversations__conversation_id__read_post",
+    "mark_inbox_linkedin_conversation_unread_inbox_linkedin_accounts__account_id__conversations__conversation_id__unread_post",
+    "mark_inbox_sms_read_inbox_sms__thread_id__mark_read_post",
+    "remove_channel_tag_inbox_channels__channel_id__tags_delete",
+    "search_inbox_emails_inbox_emails_search_post",
+    "search_inbox_linkedin_conversations_inbox_linkedin_conversations_search_post",
     "send_reply_inbox__reply_id__send_post",
-    "tag_reply_inbox__reply_id__tag_post"
+    "tag_reply_inbox__reply_id__tag_post",
+    "unassign_channel_inbox_channels__channel_id__assign_delete",
+    "unblock_inbox_sender_inbox_blocked_senders__blocked_sender_id__delete",
+    "update_inbox_tag_inbox_tags__tag_id__put"
   ],
   "components": [
     {
@@ -81,10 +103,88 @@
         "external"
       ]
     },
+    {
+      "name": "ComposeMessage",
+      "file": "components/compose-message.tsx",
+      "purpose": "Write a NEW email or text (not a reply): choose a sender you may send as (never defaulted), recipients, subject and body; sending reaches a real person and is confirmed with the sender and recipient count.",
+      "operations": [
+        "compose_inbox_email_inbox_emails_compose_post",
+        "compose_inbox_sms_inbox_sms_compose_post",
+        "list_inbox_mailboxes_paginated_inbox_mailboxes_paginated_get",
+        "list_sms_phone_numbers_sms_phone_numbers_get"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "InboxSearch",
+      "file": "components/inbox-search.tsx",
+      "purpose": "Search every email thread or LinkedIn conversation on the server (not just the loaded page) and open a result.",
+      "operations": [
+        "list_inbox_mailboxes_paginated_inbox_mailboxes_paginated_get",
+        "search_inbox_emails_inbox_emails_search_post",
+        "search_inbox_linkedin_conversations_inbox_linkedin_conversations_search_post"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "TagManager",
+      "file": "components/tag-manager.tsx",
+      "purpose": "The tag library: list, create, rename or recolour (only changed fields are sent) and delete (confirmed) inbox tags; built-in tags follow the API's edit and delete policy.",
+      "operations": [
+        "create_inbox_tag_inbox_tags_post",
+        "delete_inbox_tag_inbox_tags__tag_id__delete",
+        "list_inbox_tags_workflows_inbox_tags_get",
+        "update_inbox_tag_inbox_tags__tag_id__put"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "ThreadActions",
+      "file": "components/thread-actions.tsx",
+      "purpose": "Per-conversation housekeeping: mark read (and unread on LinkedIn), remove a tag or unassign a teammate (confirmed), block the sender.",
+      "operations": [
+        "block_inbox_sender_inbox_blocked_senders_post",
+        "mark_inbox_email_read_inbox_emails__email_id__mark_read_post",
+        "mark_inbox_linkedin_conversation_read_inbox_linkedin_accounts__account_id__conversations__conversation_id__read_post",
+        "mark_inbox_linkedin_conversation_unread_inbox_linkedin_accounts__account_id__conversations__conversation_id__unread_post",
+        "mark_inbox_sms_read_inbox_sms__thread_id__mark_read_post",
+        "remove_channel_tag_inbox_channels__channel_id__tags_delete",
+        "unassign_channel_inbox_channels__channel_id__assign_delete"
+      ],
+      "tiers": [
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "BlockedSenders",
+      "file": "components/blocked-senders.tsx",
+      "purpose": "Blocked senders per mailbox: list, block one, unblock one (confirmed).",
+      "operations": [
+        "block_inbox_sender_inbox_blocked_senders_post",
+        "list_inbox_blocked_senders_inbox_blocked_senders_get",
+        "list_inbox_mailboxes_paginated_inbox_mailboxes_paginated_get",
+        "unblock_inbox_sender_inbox_blocked_senders__blocked_sender_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
     {
       "name": "InboxScreen",
       "file": "components/inbox-screen.tsx",
-      "purpose": "Finished two-pane inbox composing the list, thread view, composer and tag/assign panel.",
+      "purpose": "Finished two-pane inbox composing the list, thread view, composer and tag/assign panel, plus New message, Search all and Manage (tags, blocked senders) and per-conversation housekeeping.",
       "operations": [],
       "tiers": []
     },
@@ -94,6 +194,19 @@
       "purpose": "Small status pill shared by the thread view and tag panel.",
       "operations": [],
       "tiers": []
+    },
+    {
+      "name": "RecordConversationsTab",
+      "file": "components/record-conversations-tab.tsx",
+      "purpose": "The email conversations with one contact (matched by address), with Load more and a calm answer for a thread that 404s; an extraDetailTabs entry for ContactsScreen.",
+      "operations": [
+        "list_inbox_mailboxes_inbox_mailboxes_get",
+        "search_inbox_emails_inbox_emails_search_post",
+        "get_reply_inbox__reply_id__get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [
@@ -112,6 +225,14 @@
       "operations": [
         "get_reply_inbox__reply_id__get"
       ]
+    },
+    {
+      "name": "useInboxMailboxes",
+      "file": "hooks/use-inbox-mailboxes.ts",
+      "purpose": "Every mailbox the caller can see and whether they may send as it, read page by page; reports when the page cap truncated the list.",
+      "operations": [
+        "list_inbox_mailboxes_paginated_inbox_mailboxes_paginated_get"
+      ]
     }
   ],
   "lib": [
@@ -122,6 +243,10 @@
     {
       "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."
+    },
+    {
+      "file": "lib/inbox-manage.ts",
+      "purpose": "Compose validation and HTML conversion, mailbox, tag, blocked-sender and search-result readers, per-channel route helpers and the hidden-thread 404 check."
     }
   ],
   "recipes": [
@@ -163,9 +288,11 @@
   ],
   "scopes": [
     "campaigns:read",
+    "inbox:delete",
     "inbox:read",
     "inbox:run",
-    "inbox:write"
+    "inbox:write",
+    "workflows:read"
   ],
   "defaults": [
     {
@@ -184,9 +311,9 @@
       "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": "Where the tag picker gets its tags",
+      "default": "GET /workflows/inbox-tags through TagManager (the Manage sheet); pass availableTags to seed it before the sheet is opened. Tags on the loaded threads are always included",
+      "askHuman": false
     },
     {
       "decision": "Filter by assignee",
@@ -197,6 +324,16 @@
       "decision": "Which mailbox, number or LinkedIn account a reply is sent from",
       "default": "The thread's own (mailbox / from_number / linkedin_account_id on the thread); an SMS or LinkedIn thread without one shows a sender picker",
       "askHuman": false
+    },
+    {
+      "decision": "Which sender a NEW message goes from",
+      "default": "Never defaulted: the person chooses a mailbox (only ones they may send as are selectable) or an SMS number, and the confirm dialog names it. The API refuses a compose without a sender",
+      "askHuman": false
+    },
+    {
+      "decision": "Snooze and archive",
+      "default": "Not offered: the API has no snooze or archive operation for inbox threads. Use tags and assignment to triage",
+      "askHuman": false
     }
   ],
   "peerDependencies": {

package/blocks/inbox/components/blocked-senders.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+/**
+ * BlockedSenders: the senders whose mail is kept out of a mailbox's inbox. See them, block one, unblock one.
+ *
+ * SDK operations, in order:
+ *   1. GET    /inbox/blocked-senders                (aiInbox.listInboxBlockedSenders)      READ
+ *   2. GET    /inbox/mailboxes/paginated            (aiInbox.listInboxMailboxesPaginated)  READ - which mailbox the block applies to
+ *   3. POST   /inbox/blocked-senders                (aiInbox.blockInboxSender)             write
+ *   4. DELETE /inbox/blocked-senders/{id}           (aiInbox.unblockInboxSender)           DESTRUCTIVE -> ConfirmSpendDialog first
+ * A block is per mailbox, so the form makes you choose the mailbox; nothing is guessed.
+ */
+import { useState } from "react";
+import { Ban, Trash2 } from "lucide-react";
+import { Button, Input, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { FirstNotice } from "@/g8/components/paging-notices";
+import { useAllPages } from "@/g8/hooks/use-all-pages";
+import { hasNextOf } from "@/g8/lib/paging";
+import { useInboxMailboxes } from "../hooks/use-inbox-mailboxes";
+import { blockedSenders, isEmail } from "../lib/inbox-manage";
+import type { BlockedSender } from "../lib/inbox-manage";
+
+export interface BlockedSendersProps {
+  className?: string;
+}
+
+export function BlockedSenders({ className }: BlockedSendersProps) {
+  const [mailbox, setMailbox] = useState("");
+  const [email, setEmail] = useState("");
+  const [reason, setReason] = useState("");
+  const [removing, setRemoving] = useState<BlockedSender | null>(null);
+  const blocked = useAllPages<BlockedSender>(
+    async (page, signal) => {
+      const env = await g8Get("/inbox/blocked-senders", { page, page_size: 100 }, { signal });
+      const rows = blockedSenders(env);
+      return { rows, hasNext: hasNextOf(env, 100, rows.length) };
+    },
+    [],
+    { pageSize: 100 },
+  );
+  const list = { data: blocked.loaded ? blocked.items : undefined, loading: blocked.loading, error: blocked.error, refetch: blocked.refetch };
+  const boxes = useInboxMailboxes();
+  const block = useG8Mutation(async () => {
+    await g8Post("/inbox/blocked-senders", { mailbox, sender_email: email.trim(), ...(reason.trim() ? { reason: reason.trim() } : {}) });
+    setEmail("");
+    setReason("");
+    blocked.refetch();
+  }, { invalidates: ["inbox"] });
+  const unblock = useG8Mutation(async (s: BlockedSender) => {
+    await g8Delete(`/inbox/blocked-senders/${encodeURIComponent(s.id)}`);
+    setRemoving(null);
+    blocked.refetch();
+  }, { invalidates: ["inbox"], onError: () => setRemoving(null) });
+
+  const valid = Boolean(mailbox) && isEmail(email);
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      <h3 className="font-medium">Blocked senders</h3>
+      <form className="space-y-2 rounded-md border border-border p-3" onSubmit={(e) => { e.preventDefault(); if (valid) void block.mutate(undefined); }}>
+        <select aria-label="Mailbox" className="h-9 w-full rounded-md border border-border bg-background px-2 text-sm" value={mailbox} disabled={boxes.loading} onChange={(e) => setMailbox(e.target.value)}>
+          <option value="">{boxes.loading ? "Loading mailboxes..." : "Choose the mailbox to block them in"}</option>
+          {(boxes.data ?? []).map((m) => <option key={m.address} value={m.address}>{m.label}</option>)}
+        </select>
+        {boxes.error ? <ApiError error={boxes.error} title="Could not load your mailboxes" onRetry={() => void boxes.refetch()} /> : null}
+        <Input aria-label="Sender email" placeholder="sender@company.com" value={email} onChange={(e) => setEmail(e.target.value)} />
+        <Input aria-label="Reason" placeholder="Reason (optional)" value={reason} onChange={(e) => setReason(e.target.value)} />
+        {block.error ? <ApiError error={block.error} title="Could not block the sender" /> : null}
+        <div className="flex justify-end"><Button type="submit" size="sm" disabled={!valid || block.loading}><Ban className="mr-1 size-4" aria-hidden />Block sender</Button></div>
+      </form>
+      {list.error ? <ApiError error={list.error} title="Could not load blocked senders" onRetry={() => void list.refetch()} /> : null}
+      {list.loading && !list.data ? <Skeleton className="h-10 w-full" /> : null}
+      {list.data && list.data.length === 0 ? <EmptyState compact title="Nobody is blocked" description="Mail from blocked senders never reaches the inbox." /> : null}
+      {list.data && list.data.length > 0 ? (
+        <ul aria-label="Blocked senders" className="divide-y rounded-md border border-border text-sm">
+          {list.data.map((s) => (
+            <li key={s.id} className="flex items-center gap-2 p-2">
+              <span className="min-w-0 flex-1"><span className="font-medium">{s.email}</span><span className="block truncate text-xs text-muted-foreground">{s.mailbox}{s.reason ? ` - ${s.reason}` : ""}</span></span>
+              <Button size="sm" variant="ghost" aria-label={`Unblock ${s.email}`} onClick={() => setRemoving(s)}><Trash2 className="size-4" aria-hidden /></Button>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      <FirstNotice shown={blocked.items.length} limit={0} force={blocked.truncated} noun="blocked senders" />
+      {unblock.error ? <ApiError error={unblock.error} title="Could not unblock the sender" /> : null}
+      <ConfirmSpendDialog
+        open={removing != null}
+        tier="destructive"
+        title={`Unblock ${removing?.email ?? ""}?`}
+        description="Their mail starts reaching the inbox again. Mail that was held back while they were blocked is not recovered."
+        confirmLabel="Unblock"
+        affected={1}
+        confirming={unblock.loading}
+        onConfirm={() => removing && void unblock.mutate(removing)}
+        onCancel={() => setRemoving(null)}
+      />
+    </div>
+  );
+}

package/blocks/inbox/components/compose-message.tsx

@@ -0,0 +1,193 @@
+"use client";
+
+/**
+ * ComposeMessage: write a NEW message (not a reply) to someone, by email or by text, from a sender you choose.
+ *
+ * SDK operations, in order:
+ *   Email: 1. GET  /inbox/mailboxes/paginated   (aiInbox.listInboxMailboxesPaginated)  READ  - the mailboxes you may send as
+ *             (each row says `can_send`, and why not when it cannot)
+ *          2. POST /inbox/emails/compose         (aiInbox.composeInboxEmail)           EXTERNAL -> ConfirmSpendDialog first
+ *   SMS:   1. GET  /sms/phone-numbers            (channels.listSmsPhoneNumbers)        READ  - the numbers you own
+ *          2. POST /inbox/sms/compose            (aiInbox.composeInboxSms)             EXTERNAL -> ConfirmSpendDialog first
+ *
+ * Sending reaches a real person and cannot be recalled. The sender is NEVER defaulted: the API refuses a compose
+ * without `from_mailbox` / `from_number` (and, for a reply, `from_address`), so this form makes the person choose one
+ * and shows it in the confirm dialog ("from hamza@acme.com to maya@northwind.io"). A mailbox the caller may not send
+ * as is listed but disabled, with the reason. A fixed Idempotency-Key per distinct payload makes a double click or a
+ * retry after a timeout safe; it rotates after a success.
+ *
+ * LinkedIn is not offered: `POST /inbox/linkedin/compose` only continues an EXISTING conversation (it needs the
+ * conversation id), which is what ReplyComposer already does from the thread.
+ */
+import { useState } from "react";
+import { Button, Input, Textarea } 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 { useBrand } from "@/g8/hooks/use-brand";
+import { FirstNotice } from "@/g8/components/paging-notices";
+import { useInboxMailboxes } from "../hooks/use-inbox-mailboxes";
+import { useIdempotencyKey } from "../lib/idempotency";
+import { senderOptions } from "../lib/inbox-types";
+import {
+  emailComposeProblems,
+  normalizePhone,
+  smsComposeProblems,
+  splitAddresses,
+  textToHtml,
+} from "../lib/inbox-manage";
+
+export type ComposeChannel = "email" | "sms";
+
+export interface ComposeMessageProps {
+  defaultChannel?: ComposeChannel;
+  /** Prefill the recipient (an email address, or a phone number for SMS). */
+  defaultTo?: string;
+  defaultSubject?: string;
+  /** Called after the message was accepted by the API. */
+  onSent?: (channel: ComposeChannel) => void;
+  onCancel?: () => void;
+  className?: string;
+}
+
+const SELECT = "h-9 w-full rounded-md border border-border bg-background px-2 text-sm";
+
+export function ComposeMessage({ defaultChannel = "email", defaultTo = "", defaultSubject = "", onSent, onCancel, className }: ComposeMessageProps) {
+  const brand = useBrand();
+  const [channel, setChannel] = useState<ComposeChannel>(defaultChannel);
+  const [from, setFrom] = useState("");
+  const [to, setTo] = useState(defaultTo);
+  const [cc, setCc] = useState("");
+  const [subject, setSubject] = useState(defaultSubject);
+  const [body, setBody] = useState("");
+  const [signature, setSignature] = useState(true);
+  const [confirming, setConfirming] = useState(false);
+  const [sent, setSent] = useState<string | null>(null);
+  const idempotency = useIdempotencyKey(JSON.stringify([channel, from, to, cc, subject, body, signature]));
+
+  const mailboxes = useInboxMailboxes({ enabled: channel === "email" });
+  const numbers = useG8Query(
+    async (signal) => senderOptions("sms", (await g8Get("/sms/phone-numbers", undefined, { signal })).data),
+    [],
+    { enabled: channel === "sms" },
+  );
+
+  const send = useG8Mutation(async () => {
+    // Belt and braces: the form already blocks this, but a send without an explicit sender must never leave.
+    if (!from.trim()) throw new Error("Choose a sender before sending.");
+    const chosen = channel === "email" ? (mailboxes.data ?? []).find((m) => m.address === from) : undefined;
+    if (chosen && !chosen.canSend) throw new Error(`You are not allowed to send as ${chosen.address} (${chosen.reason ?? "not authorised"}).`);
+    const key = { idempotencyKey: idempotency.get() };
+    if (channel === "email") {
+      return g8Post("/inbox/emails/compose", {
+        from_mailbox: from,
+        to: splitAddresses(to),
+        cc: splitAddresses(cc),
+        subject: subject.trim(),
+        content: textToHtml(body),
+        include_signature: signature,
+        save_as_draft: false,
+      }, key);
+    }
+    return g8Post("/inbox/sms/compose", { from_number: from, to_number: normalizePhone(to), body: body.trim(), save_as_draft: false }, key);
+  }, { invalidates: ["inbox"] });
+
+  const problems = channel === "email" ? emailComposeProblems({ from, to, cc, subject, body }) : smsComposeProblems({ from, to, body });
+  const recipients = channel === "email" ? splitAddresses(to) : to.trim() ? [to.trim()] : [];
+  const switchTo = (next: ComposeChannel) => {
+    if (next === channel) return;
+    setChannel(next);
+    setFrom(""); // a sender of one channel is never a sender of the other
+    setTo("");
+    setCc("");
+    setSent(null);
+    send.reset();
+  };
+
+  const confirm = async () => {
+    try {
+      await send.mutateAsync(undefined);
+      idempotency.rotate();
+      setSent(channel === "email" ? "Email sent." : "Text sent.");
+      setBody("");
+      setSubject("");
+      setConfirming(false);
+      onSent?.(channel);
+    } catch {
+      setConfirming(false); // the error renders below; the form keeps what was typed so the person can retry
+    }
+  };
+
+  const sendersLoading = channel === "email" ? mailboxes.loading : numbers.loading;
+  const senderError = channel === "email" ? mailboxes.error : numbers.error;
+  const senderChoices =
+    channel === "email"
+      ? (mailboxes.data ?? []).map((m) => ({ value: m.address, label: m.canSend ? m.label : `${m.label} (${m.reason})`, disabled: !m.canSend }))
+      : (numbers.data ?? []).map((n) => ({ value: n.value, label: n.label, disabled: false }));
+  const noSenders = !sendersLoading && !senderError && senderChoices.length === 0;
+
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      <div role="group" aria-label="Channel" className="flex gap-1">
+        <Button size="sm" variant={channel === "email" ? "default" : "outline"} onClick={() => switchTo("email")}>Email</Button>
+        <Button size="sm" variant={channel === "sms" ? "default" : "outline"} onClick={() => switchTo("sms")}>Text message</Button>
+      </div>
+
+      <label className="block space-y-1 text-sm">
+        <span className="font-medium">{channel === "email" ? "From" : "Send from"}</span>
+        <select aria-label={channel === "email" ? "From mailbox" : "From number"} className={SELECT} value={from} disabled={sendersLoading} onChange={(e) => setFrom(e.target.value)}>
+          <option value="">{sendersLoading ? "Loading senders..." : channel === "email" ? "Choose the mailbox to send from" : "Choose the number to text from"}</option>
+          {senderChoices.map((o) => <option key={o.value} value={o.value} disabled={o.disabled}>{o.label}</option>)}
+        </select>
+      </label>
+      {senderError ? <ApiError error={senderError} title="Could not load your senders" onRetry={() => void (channel === "email" ? mailboxes : numbers).refetch()} /> : null}
+      {channel === "email" ? <FirstNotice shown={mailboxes.items.length} limit={0} force={mailboxes.truncated} noun="mailboxes" /> : null}
+      {noSenders ? <p className="text-sm text-muted-foreground">{channel === "email" ? `No mailbox is connected yet. Connect one in the ${brand.linkLabel} app first.` : "No SMS number on this account yet."}</p> : null}
+
+      <label className="block space-y-1 text-sm">
+        <span className="font-medium">To</span>
+        <Input aria-label="To" placeholder={channel === "email" ? "name@company.com, another@company.com" : "+14155550100"} value={to} onChange={(e) => setTo(e.target.value)} />
+      </label>
+      {channel === "email" ? (
+        <>
+          <Input aria-label="Cc" placeholder="Cc (optional)" value={cc} onChange={(e) => setCc(e.target.value)} />
+          <Input aria-label="Subject" placeholder="Subject" value={subject} onChange={(e) => setSubject(e.target.value)} />
+        </>
+      ) : null}
+      <Textarea aria-label="Message" rows={8} placeholder="Write your message" value={body} onChange={(e) => setBody(e.target.value)} />
+      {channel === "email" ? (
+        <label className="flex items-center gap-2 text-sm">
+          <input type="checkbox" checked={signature} onChange={(e) => setSignature(e.target.checked)} />
+          Add my email signature
+        </label>
+      ) : null}
+
+      {problems.length > 0 && (to || body || from) ? (
+        <ul aria-label="Still needed" className="list-disc pl-5 text-xs text-muted-foreground">{problems.map((p) => <li key={p}>{p}</li>)}</ul>
+      ) : null}
+      {send.error ? <ApiError error={send.error} title="Could not send the message" onRetry={() => setConfirming(true)} /> : null}
+      {sent ? <p role="status" className="text-sm text-positive-foreground">{sent}</p> : null}
+
+      <div className="flex justify-end gap-2">
+        {onCancel ? <Button variant="outline" onClick={onCancel}>Cancel</Button> : null}
+        <Button disabled={problems.length > 0 || send.loading} onClick={() => { setSent(null); setConfirming(true); }}>
+          {channel === "email" ? "Send email" : "Send text"}
+        </Button>
+      </div>
+
+      <ConfirmSpendDialog
+        open={confirming}
+        tier="external"
+        title={`Send this ${channel === "email" ? "email" : "text message"}?`}
+        description={`It goes to ${recipients.join(", ") || "the recipient"} from ${from || "no sender chosen"}. It reaches a real person and cannot be recalled.`}
+        recipients={recipients.length}
+        confirmLabel={channel === "email" ? "Send email" : "Send text"}
+        confirming={send.loading}
+        onConfirm={() => void confirm()}
+        onCancel={() => setConfirming(false)}
+      />
+    </div>
+  );
+}