@graph8/sdk 0.308.1 → 0.357.0

package/blocks/dialer/README.md

@@ -0,0 +1,114 @@
+# dialer: outbound calling
+
+Run a calling session for a rep: pick a list, dial batch by batch, watch the queue, take the calls in the
+browser, record outcomes, and review transcripts. Copy `DialerWorkspace` for the whole screen, or compose
+`CallQueue`, `Softphone`, `DispositionPanel`, `CallLog` and `TranscriptViewer` yourself. Install with
+`npx @graph8/sdk add dialer` (depends on `lists`).
+
+> Dialing reaches real people on real phones and spends credits. Nothing in this block dials, leaves a
+> voicemail, or mints a softphone credential without a confirm dialog first, and the block never auto-advances to
+> the next batch.
+
+## How it works (read this before building)
+
+- graph8 places the calls **from its servers** into a conference. The rep's browser only **joins that
+  conference** with audio. So the Softphone does not dial; "Dial next batch" does.
+- The API has **no live event stream**: no WebSocket or SSE for sessions, call state or transcripts. The block
+  **polls** (`useDialerSession`, every 5 seconds, via `useJobPoll`). `queue-stats` is the cheap poll; the
+  session read carries the live call list.
+- The browser audio client is **not part of the API**. The Softphone talks to a `SoftphoneTransport`
+  (`lib/softphone-transport.ts`). `lib/twilio-transport.ts` implements it with `@twilio/voice-sdk` (graph8's
+  dialer runs on Twilio conferences). Another vendor (LiveKit, your own SIP stack) = write a transport and pass
+  it as `transport`; delete `twilio-transport.ts` and the peer dependency if you do.
+
+## The flow, in order
+
+1. **Caller ID**: `GET /voice/dialer/numbers` (`SessionStartForm`). Use the `number` field.
+2. **Draft** (write, dials nobody): `POST /dialer/sessions/draft` with `{ user_id, list_id, dialing_mode,
+   parallel_count, from_phone }` -> `session_id`. An organisation API key has no user of its own, so you pass
+   the rep's `user_id` (and `user_email`). The same list returns the existing live session.
+3. **Watch** (read, polled): `GET /dialer/sessions/{session_id}/queue-stats` -> `{ status, batch_status,
+   current_batch_id, queue_remaining }` and `GET /dialer/sessions/{session_id}` -> `live_state.calls`.
+   `batch_status` is `in_flight`, `complete_awaiting_disposition` or `complete_auto_advance_eligible`.
+4. **Enable audio** (`Softphone`, **external**, confirm first): `GET /dialer/sessions/token?user_id=` returns a
+   one-hour bearer credential `{ token, identity }`. Treat it as a secret (the block keeps it in memory and
+   renders nothing).
+5. **Dial** (`CallQueue`, **external**, confirm first): `POST /dialer/sessions/{id}/next-batch` with
+   `{ previous_batch_id: current_batch_id, dialing_mode, parallel_count, from_phone }`. The response has
+   `conference_name`, `queue_remaining`, `queue_exhausted`, `all_dials_failed` and `error_message`. Hand
+   `conference_name` to the Softphone (`DialerWorkspace` does this) so the rep's audio joins.
+6. **Work the calls**: hang up (`POST /dialer/sessions/calls/hangup`), mute (`.../calls/mute`), drop a voicemail
+   (`.../calls/drop-voicemail`, **external**, confirm first), skip a contact (`.../{id}/calls/skip-contact`).
+7. **Outcome** (`DispositionPanel`, write): `GET /voice/dispositions` for the accepted values, then
+   `PATCH /dialer/parallel-calls/calls/{room_name}/disposition` with `{ disposition, notes?, callback_at? }`.
+   `room_name` is the call's `call_id`. Setting `callback_at` schedules a follow-up; it does not place the call.
+8. **Review** (`CallLog`, `TranscriptViewer`): `GET /voice/dialer/calls?contact_id=|user_email=|
+   parallel_session_id=` (one of the three is required), then `.../calls/{room_name}/transcript` and
+   `.../grading` (status `empty` / `pending` until ready), and the recording through your proxy at
+   `/voice/calls/{call_id}/recording` (425 while it finalises).
+9. **Stop** (`pause` / `stop`, write): both hang up live calls. Pause, then `next-batch` again to continue.
+
+IDs passed between steps: `session_id` (draft -> poll -> next-batch/pause/stop/skip/hangup), `current_batch_id`
+(queue-stats -> next-batch's `previous_batch_id`, makes a retry idempotent), `conference_name` (next-batch ->
+Softphone), `call_id` = `room_name` (live call -> disposition -> transcript -> recording), `contact_id`.
+
+## Prerequisites a human must do
+
+- A phone number for the org (`where: "app"`): buying, porting or verifying a caller ID is a decision made in
+  the graph8 app. `GET /voice/dialer/numbers` must return one.
+- Telephony active and credits available (HTTP 402 otherwise).
+- `npm i @twilio/voice-sdk` if you keep the Twilio adapter, and the browser must grant microphone access.
+- Key scopes: `voice:read`, `voice:write`, `voice:run`.
+
+## Defaults (the agent does not need to ask)
+
+- Power mode (one call at a time); parallel is opt-in (2 to 10 at once).
+- Each batch is confirmed separately. Do not add auto-advance without asking the human.
+- Poll every 5 seconds.
+- Attribute calls to the signed-in rep: pass `userId` / `userEmail` from your own session.
+- Ask the human only about the **audio vendor** (Twilio adapter by default).
+
+## Stack nav pages
+
+`CallQueue` and `CallLog` render with no props (a stack uses them as pages): the start form asks for the rep's user id
+and the call log for a rep email. Pass `userId` / `userEmail` from your session to skip those fields.
+
+## Gotchas
+
+- Parallel dialing: the rep joins the conference **muted** (the server unmutes when someone answers). The
+  workspace passes `joinMuted` when the batch has more than one call.
+- `all_dials_failed` pauses the session (bad caller ID, no telephony). Show `error_message`.
+- Voicemail drop plays the rep's cloned voice to a stranger's phone. The confirm dialog names the contact.
+- Another tenant's session id is a 404, the same as a missing one.
+- Manual dial (`POST /dialer/parallel-calls/manual-dial`, external) needs a PAUSED or COMPLETED session and can
+  create a contact; it is a server recipe here, not a component.
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `voice.listDialerNumbers` | GET /voice/dialer/numbers | read | SessionStartForm |
+| `dialer.createSessionDraft` | POST /dialer/sessions/draft | write | SessionStartForm |
+| `dialer.readQueueStats` | GET /dialer/sessions/{id}/queue-stats | read | useDialerSession |
+| `voice.getDialerSession` | GET /dialer/sessions/{id} | read | useDialerSession |
+| `dialer.readSessionGrid` | POST /dialer/sessions/{id}/grid | read | CallQueue |
+| `dialer.dialNextBatch` | POST /dialer/sessions/{id}/next-batch | external | CallQueue |
+| `voice.pauseDialerSession` | POST /dialer/sessions/{id}/pause | write | CallQueue |
+| `voice.stopDialerSession` | POST /dialer/sessions/{id}/stop | write | CallQueue |
+| `dialer.skipContact` | POST /dialer/sessions/{id}/calls/skip-contact | write | CallQueue |
+| `dialer.hangupSessionCall` | POST /dialer/sessions/calls/hangup | write | LiveCallsTable |
+| `dialer.muteCall` | POST /dialer/sessions/calls/mute | write | LiveCallsTable |
+| `dialer.dropSessionVoicemail` | POST /dialer/sessions/calls/drop-voicemail | external | LiveCallsTable |
+| `dialer.mintSoftphoneToken` | GET /dialer/sessions/token | external | Softphone |
+| `voice.listVoiceDispositions` | GET /voice/dispositions | read | DispositionPanel |
+| `dialer.setCallDisposition` | PATCH /dialer/parallel-calls/calls/{room}/disposition | write | DispositionPanel |
+| `voice.listCallsForContact` | GET /voice/dialer/calls | read | CallLog |
+| `voice.getCallTranscript` | GET /voice/dialer/calls/{room}/transcript | read | TranscriptViewer |
+| `voice.getCallGrading` | GET /voice/dialer/calls/{room}/grading | read | TranscriptViewer |
+| `voice.downloadCallRecording` | GET /voice/calls/{id}/recording | read | TranscriptViewer |
+
+## Recipes (server side)
+
+- `01-create-session-and-dial.ts`: draft, one confirmed batch, poll queue-stats.
+- `02-disposition-calls.ts`: record outcomes from the org's accepted list.
+- `03-review-a-call.ts`: transcript, AI grade, rep performance (`dialerAnalytics`).

package/blocks/dialer/block.json

@@ -0,0 +1,260 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "dialer",
+  "title": "Dialer",
+  "summary": "Outbound calling: dialing sessions with a polled queue, a pluggable browser softphone, outcomes, call log and transcripts.",
+  "features": [
+    "draft a session from a list, then dial batch by batch (each batch confirmed)",
+    "queue, live calls and counters by polling (the API has no event stream)",
+    "softphone on a pluggable audio transport with a ready Twilio adapter",
+    "dispositions with callback scheduling",
+    "call log, transcript, AI grading and recording per call"
+  ],
+  "dependsOn": [
+    "lists"
+  ],
+  "operations": [
+    "create_session_draft_dialer_sessions_draft_post",
+    "dial_next_batch_dialer_sessions__session_id__next_batch_post",
+    "download_call_recording_voice_calls__call_id__recording_get",
+    "drop_session_voicemail_dialer_sessions_calls_drop_voicemail_post",
+    "get_call_grading_voice_dialer_calls__room_name__grading_get",
+    "get_call_transcript_voice_dialer_calls__room_name__transcript_get",
+    "get_dialer_session_dialer_sessions__session_id__get",
+    "hangup_session_call_dialer_sessions_calls_hangup_post",
+    "list_calls_for_contact_voice_dialer_calls_get",
+    "list_dialer_numbers_voice_dialer_numbers_get",
+    "list_voice_dispositions_voice_dispositions_get",
+    "mint_softphone_token_dialer_sessions_token_get",
+    "mute_call_dialer_sessions_calls_mute_post",
+    "pause_dialer_session_dialer_sessions__session_id__pause_post",
+    "read_queue_stats_dialer_sessions__session_id__queue_stats_get",
+    "read_session_grid_dialer_sessions__session_id__grid_post",
+    "set_call_disposition_dialer_parallel_calls_calls__livekit_room_name__disposition_patch",
+    "skip_contact_dialer_sessions__session_id__calls_skip_contact_post",
+    "stop_dialer_session_dialer_sessions__session_id__stop_post"
+  ],
+  "components": [
+    {
+      "name": "CallQueue",
+      "file": "components/call-queue.tsx",
+      "purpose": "Run one dialing session: polled counters, calls in flight, waiting contacts, and confirmed Dial next batch, pause, stop and skip.",
+      "operations": [
+        "dial_next_batch_dialer_sessions__session_id__next_batch_post",
+        "get_dialer_session_dialer_sessions__session_id__get",
+        "pause_dialer_session_dialer_sessions__session_id__pause_post",
+        "read_queue_stats_dialer_sessions__session_id__queue_stats_get",
+        "read_session_grid_dialer_sessions__session_id__grid_post",
+        "skip_contact_dialer_sessions__session_id__calls_skip_contact_post",
+        "stop_dialer_session_dialer_sessions__session_id__stop_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    },
+    {
+      "name": "SessionStartForm",
+      "file": "components/session-start-form.tsx",
+      "purpose": "Create a draft session (dials nobody) for a list, caller ID and mode.",
+      "operations": [
+        "create_session_draft_dialer_sessions_draft_post",
+        "list_dialer_numbers_voice_dialer_numbers_get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "LiveCallsTable",
+      "file": "components/live-calls-table.tsx",
+      "purpose": "Calls in the session with hang up, mute and a confirmed voicemail drop.",
+      "operations": [
+        "drop_session_voicemail_dialer_sessions_calls_drop_voicemail_post",
+        "hangup_session_call_dialer_sessions_calls_hangup_post",
+        "mute_call_dialer_sessions_calls_mute_post"
+      ],
+      "tiers": [
+        "write",
+        "external"
+      ]
+    },
+    {
+      "name": "Softphone",
+      "file": "components/softphone.tsx",
+      "purpose": "The rep's browser audio endpoint on a pluggable transport; mints the softphone credential behind a confirm dialog.",
+      "operations": [
+        "mint_softphone_token_dialer_sessions_token_get"
+      ],
+      "tiers": [
+        "external"
+      ]
+    },
+    {
+      "name": "DispositionPanel",
+      "file": "components/disposition-panel.tsx",
+      "purpose": "Record the outcome of a finished call, with notes and a scheduled callback.",
+      "operations": [
+        "list_voice_dispositions_voice_dispositions_get",
+        "set_call_disposition_dialer_parallel_calls_calls__livekit_room_name__disposition_patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "CallLog",
+      "file": "components/call-log.tsx",
+      "purpose": "Recent calls for a contact, rep or session with outcome, length and summary.",
+      "operations": [
+        "list_calls_for_contact_voice_dialer_calls_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "TranscriptViewer",
+      "file": "components/transcript-viewer.tsx",
+      "purpose": "Speaker-segmented transcript, summary, AI grading and recording for one call.",
+      "operations": [
+        "download_call_recording_voice_calls__call_id__recording_get",
+        "get_call_grading_voice_dialer_calls__room_name__grading_get",
+        "get_call_transcript_voice_dialer_calls__room_name__transcript_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "DialerWorkspace",
+      "file": "components/dialer-workspace.tsx",
+      "purpose": "The whole rep screen wiring queue, softphone, outcome panel and transcript together.",
+      "operations": [],
+      "tiers": []
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useDialerSession",
+      "file": "hooks/use-dialer-session.ts",
+      "purpose": "Poll a session's queue-stats and live call list every 5 seconds until it is over.",
+      "operations": [
+        "get_dialer_session_dialer_sessions__session_id__get",
+        "read_queue_stats_dialer_sessions__session_id__queue_stats_get"
+      ]
+    },
+    {
+      "name": "useDispositions",
+      "file": "hooks/use-dispositions.ts",
+      "purpose": "The call outcomes this org accepts (system and custom).",
+      "operations": [
+        "list_voice_dispositions_voice_dispositions_get"
+      ]
+    },
+    {
+      "name": "useDialerNumbers",
+      "file": "hooks/use-dialer-numbers.ts",
+      "purpose": "Caller IDs available to the dialer with today's usage.",
+      "operations": [
+        "list_dialer_numbers_voice_dialer_numbers_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/dialer-types.ts",
+      "purpose": "Session, call, queue and disposition types plus status helpers for the voice service's JSON."
+    },
+    {
+      "file": "lib/softphone-transport.ts",
+      "purpose": "The SoftphoneTransport interface (the vendor seam) and a no-op transport."
+    },
+    {
+      "file": "lib/twilio-transport.ts",
+      "purpose": "Ready Twilio adapter for the transport interface, using the optional peer @twilio/voice-sdk."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/01-create-session-and-dial.ts",
+      "title": "Create a session, dial a batch and poll it",
+      "when": "An agent or job running calls for a rep; the dial step reaches real people and needs approval."
+    },
+    {
+      "file": "recipes/02-disposition-calls.ts",
+      "title": "Record outcomes for a session's finished calls",
+      "when": "After a batch completes; uses the org's accepted disposition list."
+    },
+    {
+      "file": "recipes/03-review-a-call.ts",
+      "title": "Pull a call's transcript, AI grade and rep performance",
+      "when": "Coaching and QA; read-only."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "phone-number",
+      "description": "At least one dialer phone number for the org (provisioned or verified caller ID). Buying or porting a number is a human decision in the graph8 app.",
+      "where": "app",
+      "verify": "GET /voice/dialer/numbers returns at least one number with is_valid true."
+    },
+    {
+      "id": "telephony-and-credits",
+      "description": "Telephony active for the org and credits available: every dial attempt reserves credits and connected minutes charge more (402 when none).",
+      "where": "api",
+      "verify": "A power-mode next-batch on a one-contact test list returns no error_code."
+    },
+    {
+      "id": "voice-scopes",
+      "description": "Key scopes voice:read and voice:write for the screens, voice:run for dialing, the softphone credential and voicemail drop, analytics:read for rep performance. The softphone credential is a bearer secret.",
+      "where": "api",
+      "verify": "`g8.api.me.describeCurrentKey()` lists voice:read, voice:write and voice:run."
+    },
+    {
+      "id": "audio-client",
+      "description": "A browser audio client package for the Softphone: the default adapter needs `npm i @twilio/voice-sdk`. Microphone permission must be granted in the browser.",
+      "where": "app",
+      "verify": "`import(\"@twilio/voice-sdk\")` resolves and the browser prompts for the microphone."
+    }
+  ],
+  "scopes": [
+    "voice:read",
+    "voice:run",
+    "voice:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Dialing mode",
+      "default": "power (one call at a time); parallel is opt-in with 2 to 10 calls at once",
+      "askHuman": false
+    },
+    {
+      "decision": "Does the next batch dial automatically after a batch ends",
+      "default": "No. Every batch needs its own confirmation; auto-advance is never enabled by the block",
+      "askHuman": false
+    },
+    {
+      "decision": "How session state reaches the screen",
+      "default": "Polling queue-stats and the session every 5 seconds (the API has no event stream)",
+      "askHuman": false
+    },
+    {
+      "decision": "Which rep the calls are attributed to (an organisation API key has no user)",
+      "default": "The signed-in user of your app: pass userId (and userEmail) from your session",
+      "askHuman": false
+    },
+    {
+      "decision": "Browser audio vendor for the Softphone",
+      "default": "Twilio via lib/twilio-transport.ts; graph8's dialer runs on Twilio conferences. For another vendor write a SoftphoneTransport and delete twilio-transport.ts",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "@twilio/voice-sdk": "^2.18.5"
+  }
+}

package/blocks/dialer/components/call-log.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+/**
+ * CallLog: recent dialer calls for one contact, one rep, or one session, with outcome, length and summary.
+ *
+ * SDK operations: GET /voice/dialer/calls?contact_id=|user_email=|parallel_session_id=&limit=   (voice.listCallsForContact)   read
+ * The API REQUIRES at least one of contact_id, user_email or parallel_session_id (org alone would dump the whole
+ * history) and returns summaries without transcripts; open one in TranscriptViewer via `onSelect`.
+ * Org-wide history across all reps: use POST /voice/call-results/search (voice.searchCallResults) from a server recipe.
+ */
+import { useState } from "react";
+import { Input, 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 { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { dataOf, formatDuration, type CallSummary } from "../lib/dialer-types";
+
+export interface CallLogProps {
+  contactId?: string;
+  userEmail?: string;
+  sessionId?: string;
+  limit?: number;
+  onSelect?: (call: CallSummary) => void;
+  className?: string;
+}
+
+function when(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleString(undefined, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+}
+
+export function CallLog({ contactId, userEmail, sessionId, limit = 25, onSelect, className }: CallLogProps) {
+  const [typedEmail, setTypedEmail] = useState("");
+  const repEmail = userEmail || typedEmail.trim();
+  const scoped = Boolean(contactId || repEmail || sessionId);
+  const q = useG8Query(
+    async (signal) => {
+      const env = await g8Get("/voice/dialer/calls", { contact_id: contactId, user_email: repEmail || undefined, parallel_session_id: sessionId, limit }, { signal });
+      return dataOf<{ calls?: CallSummary[] }>(env).calls ?? [];
+    },
+    [contactId, repEmail, sessionId, limit],
+    { enabled: scoped },
+  );
+
+  if (!scoped) {
+    return (
+      <div className={`space-y-3 ${className ?? ""}`}>
+        <EmptyState title="Choose whose calls to show" description="Pass a contactId, userEmail or sessionId, or type a rep's email. The API will not list the whole organisation's calls at once." />
+        <Input aria-label="Rep email" type="email" placeholder="rep@company.com" value={typedEmail} onChange={(e) => setTypedEmail(e.target.value)} />
+      </div>
+    );
+  }
+  if (q.error) return <ApiError error={q.error} title="Could not load calls" onRetry={() => void q.refetch()} />;
+  if (q.loading && !q.data) return <Skeleton className="h-32 w-full" aria-label="Loading calls" />;
+  const calls = q.data ?? [];
+  if (calls.length === 0) return <EmptyState className={className} title="No calls yet" description="Calls appear here after the dialer places them." />;
+
+  return (
+    <Table className={className} aria-label="Call log">
+      <TableHeader>
+        <TableRow><TableHead>When</TableHead><TableHead>Number</TableHead><TableHead>Outcome</TableHead><TableHead>Length</TableHead><TableHead>Summary</TableHead></TableRow>
+      </TableHeader>
+      <TableBody>
+        {calls.map((c) => (
+          <TableRow key={c.room_name} className={onSelect ? "cursor-pointer" : undefined} onClick={() => onSelect?.(c)}>
+            <TableCell className="whitespace-nowrap">{when(c.created_at)}</TableCell>
+            <TableCell>{c.to}</TableCell>
+            <TableCell className="capitalize">{c.disposition?.replace(/_/g, " ") ?? "none"}</TableCell>
+            <TableCell>{formatDuration(c.call_duration)}</TableCell>
+            <TableCell className="max-w-72 truncate text-muted-foreground">{c.summary ?? (c.has_transcript ? "Transcript available" : "")}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}

package/blocks/dialer/components/call-queue.tsx

@@ -0,0 +1,188 @@
+"use client";
+
+/**
+ * CallQueue: run one dialing session. Live counters, the calls in flight, the contacts still waiting, and the
+ * controls that start, pause and stop dialing. It POLLS (no event stream exists), see useDialerSession.
+ *
+ * SDK operations, in order:
+ *   1. (no session yet) SessionStartForm: GET /voice/dialer/numbers, POST /dialer/sessions/draft   write, dials no one
+ *   2. every 5s: GET /dialer/sessions/{id}/queue-stats + GET /dialer/sessions/{id}                  read
+ *   3. POST /dialer/sessions/{id}/grid                      (dialer.readSessionGrid)        read   - the waiting contacts
+ *   4. POST /dialer/sessions/{id}/next-batch                (dialer.dialNextBatch)          EXTERNAL -> ConfirmSpendDialog first
+ *        CALLS REAL PEOPLE and reserves credits. Returns { conference_name, twilio_token, ... }: pass them to
+ *        <Softphone/> through `onBatch` so the rep's browser can join the conference.
+ *   5. POST /dialer/sessions/{id}/pause, /stop              (voice.pauseDialerSession / stopDialerSession)  write - hang up live calls
+ *   6. POST /dialer/sessions/{id}/calls/skip-contact        (dialer.skipContact)            write  - reversible
+ *
+ * Each batch needs its own confirmation by design: dialing is never automatic.
+ */
+import { useEffect, useState } from "react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } 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 { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useDialerSession } from "../hooks/use-dialer-session";
+import { contactName, dataOf, firstPhone, isLiveCall, isSessionOver, normalizeStatus, type DialerMode, type LiveCall, type NextBatchResult, type QueueRow } from "../lib/dialer-types";
+import { LiveCallsTable } from "./live-calls-table";
+import { SessionStartForm } from "./session-start-form";
+
+export interface CallQueueProps {
+  /** Resume an existing session; omit to show the start form. */
+  sessionId?: string;
+  /** Optional: when omitted the start form asks for it, so CallQueue renders as a stack nav page with no props. */
+  userId?: string;
+  userEmail?: string;
+  listId?: string;
+  listTitle?: string;
+  /** Fires after each confirmed "Dial next batch" with the conference the rep must join. */
+  onBatch?: (batch: NextBatchResult) => void;
+  onSessionCreated?: (sessionId: string) => void;
+  /** A finished call was clicked: open DispositionPanel for it. */
+  onSelectCall?: (call: LiveCall) => void;
+  /** Called with every poll result, for sibling components. */
+  onCalls?: (calls: LiveCall[]) => void;
+  className?: string;
+}
+
+function Stat({ label, value }: { label: string; value: string | number }) {
+  return (
+    <div className="rounded-lg border p-3">
+      <div className="text-xs uppercase text-muted-foreground">{label}</div>
+      <div className="text-lg font-semibold capitalize">{value}</div>
+    </div>
+  );
+}
+
+function WaitingContacts({ sessionId, version, onSkipped }: { sessionId: string; version: number; onSkipped: () => void }) {
+  const grid = useG8Query(
+    async (signal) => {
+      const env = await g8Post(`/dialer/sessions/${encodeURIComponent(sessionId)}/grid`, { limit: 10, offset: 0, include_contact_data: true }, { signal });
+      const data = dataOf<{ items?: QueueRow[]; rows?: QueueRow[] }>(env);
+      return data.items ?? data.rows ?? [];
+    },
+    [sessionId, version],
+  );
+  const [skipping, setSkipping] = useState<string | null>(null);
+  const skip = useG8Mutation(async (row: QueueRow) => { setSkipping(row.contact_id); try { return await g8Post(`/dialer/sessions/${encodeURIComponent(sessionId)}/calls/skip-contact`, { contact_id: row.contact_id }); } finally { setSkipping(null); } }, { onSuccess: onSkipped });
+  if (grid.error) return <ApiError error={grid.error} title="Could not load the queue" onRetry={() => void grid.refetch()} />;
+  if (grid.loading && !grid.data) return <Skeleton className="h-24 w-full" aria-label="Loading queue" />;
+  const rows = (grid.data ?? []).filter((r) => !r.callresult?.disposition);
+  return (
+    <div className="space-y-2">
+      <h3 className="text-sm font-semibold">Up next</h3>
+      {skip.error ? <ApiError error={skip.error} title="Could not skip that contact" /> : null}
+      <Table aria-label="Contacts waiting">
+        <TableHeader>
+          <TableRow><TableHead>Contact</TableHead><TableHead>Company</TableHead><TableHead>Number</TableHead><TableHead /></TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.map((r) => (
+            <TableRow key={r.contact_id}>
+              <TableCell className="font-medium">{contactName(r)}{r.is_next_to_dial ? " (next)" : ""}</TableCell>
+              <TableCell>{r.company}</TableCell>
+              <TableCell>{firstPhone(r) || (r.blocked_reason ? `blocked: ${r.blocked_reason}` : "no number")}</TableCell>
+              <TableCell className="text-right"><Button size="sm" variant="ghost" disabled={skipping === r.contact_id} onClick={() => void skip.mutate(r)}>Skip</Button></TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}
+
+export function CallQueue({ sessionId: initialId, userId, userEmail, listId, listTitle, onBatch, onSessionCreated, onSelectCall, onCalls, className }: CallQueueProps) {
+  const [sessionId, setSessionId] = useState(initialId);
+  useEffect(() => { setSessionId(initialId); }, [initialId]); // follow the prop when the caller switches sessions
+  const [stopping, setStopping] = useState(false);
+  const [dial, setDial] = useState({ mode: "power" as DialerMode, parallelCount: 1, fromPhone: "" });
+  const [confirming, setConfirming] = useState(false);
+  const [version, setVersion] = useState(0);
+  const session = useDialerSession(sessionId);
+  const bump = () => { setVersion((v) => v + 1); session.refresh(); };
+  const mode = session.detail?.dialing_mode ?? dial.mode;
+  const parallelCount = mode === "parallel" ? (session.detail?.parallel_count ?? dial.parallelCount) : 1;
+  useEffect(() => { onCalls?.(session.calls); }, [session.calls]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const nextBatch = useG8Mutation(
+    async () => {
+      const env = await g8Post(`/dialer/sessions/${encodeURIComponent(sessionId as string)}/next-batch`, {
+        previous_batch_id: session.stats?.current_batch_id ?? null,
+        from_phone: dial.fromPhone || session.detail?.from_phone || undefined,
+        dialing_mode: mode,
+        parallel_count: parallelCount,
+        user_email: userEmail,
+      });
+      return dataOf<NextBatchResult>(env);
+    },
+    { onSuccess: (batch) => { setConfirming(false); onBatch?.(batch); bump(); }, onError: () => setConfirming(false) },
+  );
+  const pause = useG8Mutation(() => g8Post(`/dialer/sessions/${encodeURIComponent(sessionId as string)}/pause`, undefined, { query: { user_email: userEmail } }), { onSuccess: bump });
+  const stop = useG8Mutation(() => g8Post(`/dialer/sessions/${encodeURIComponent(sessionId as string)}/stop`), { onSuccess: () => { setStopping(false); bump(); }, onError: () => setStopping(false) });
+
+  if (!sessionId) {
+    return (
+      <SessionStartForm
+        className={className}
+        userId={userId}
+        userEmail={userEmail}
+        listId={listId}
+        listTitle={listTitle}
+        onCreated={(s) => { setDial({ mode: s.mode, parallelCount: s.parallelCount, fromPhone: s.fromPhone }); setSessionId(s.sessionId); onSessionCreated?.(s.sessionId); }}
+      />
+    );
+  }
+  const stats = session.stats;
+  const over = isSessionOver(stats?.status);
+  const batchResult = nextBatch.data;
+  const failure = nextBatch.error ?? pause.error ?? stop.error ?? session.error;
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      <header className="flex flex-wrap items-center justify-between gap-2">
+        <h2 className="text-base font-semibold">{session.detail?.name ?? "Dialing session"}</h2>
+        <div className="flex gap-2">
+          <Button disabled={!stats || over || nextBatch.loading} onClick={() => setConfirming(true)}>Dial next batch</Button>
+          <Button variant="outline" disabled={!stats || over} onClick={() => void pause.mutate(undefined)}>Pause</Button>
+          <Button variant="outline" disabled={!stats || over} onClick={() => setStopping(true)}>Stop</Button>
+        </div>
+      </header>
+      {failure ? <ApiError error={failure} title="Session problem" onRetry={() => session.refresh()} /> : null}
+      {batchResult?.all_dials_failed ? <p role="alert" className="text-sm text-destructive">{batchResult.error_message ?? "Every call in that batch failed to connect. The session was paused."}</p> : null}
+      {batchResult?.queue_exhausted ? <p className="text-sm text-muted-foreground">The queue is empty. Everyone on the list has been called.</p> : null}
+      {!stats ? <Skeleton className="h-20 w-full" aria-label="Loading session" /> : (
+        <div className="grid grid-cols-2 gap-3 sm:grid-cols-4">
+          <Stat label="Status" value={normalizeStatus(stats.status)} />
+          <Stat label="Batch" value={(stats.batch_status ?? "idle").replace(/_/g, " ")} />
+          <Stat label="Left in queue" value={stats.queue_remaining} />
+          <Stat label="Retries pending" value={stats.retry_pending ?? 0} />
+        </div>
+      )}
+      <LiveCallsTable sessionId={sessionId} calls={session.calls} onChanged={bump} onSelect={onSelectCall} />
+      <WaitingContacts sessionId={sessionId} version={version} onSkipped={bump} />
+      <ConfirmSpendDialog
+        open={stopping}
+        tier="destructive"
+        title="Stop this session?"
+        description="Every live call is hung up and the session is completed. It cannot be resumed; start a new session to keep calling."
+        confirmLabel="Stop session"
+        affected={session.calls.filter((c) => isLiveCall(c)).length}
+        confirming={stop.loading}
+        onConfirm={() => void stop.mutate(undefined)}
+        onCancel={() => setStopping(false)}
+      />
+      <ConfirmSpendDialog
+        open={confirming}
+        tier="external"
+        title={mode === "parallel" ? `Dial the next ${parallelCount} contacts at once?` : "Dial the next contact?"}
+        description="This places real phone calls to people on your list and reserves credits for each attempt. Connected minutes charge more."
+        confirmLabel="Dial now"
+        recipients={parallelCount}
+        confirming={nextBatch.loading}
+        onConfirm={() => void nextBatch.mutate(undefined)}
+        onCancel={() => setConfirming(false)}
+      />
+    </div>
+  );
+}