@graph8/sdk 0.303.0 → 0.357.0

package/blocks/coach/block.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "coach",
+  "title": "Sales coach",
+  "summary": "Graded practice-call scorecards (stages, verdicts, strengths, recording, transcript) and a coaching feed with a leaderboard.",
+  "features": [
+    "scorecard with overall score, stage results and checklist verdicts",
+    "summary, strengths and what to improve",
+    "on-demand signed recording and the transcript",
+    "coaching feed: newest graded calls with the first thing to work on",
+    "leaderboard ranked by total score",
+    "optional real dialer calls tab",
+    "delete (owner or manager) behind a confirmation"
+  ],
+  "dependsOn": [
+    "dialer"
+  ],
+  "operations": [
+    "create_call_sales_coach_calls_post",
+    "delete_call_sales_coach_calls__call_id__delete",
+    "get_call_audio_url_sales_coach_calls__call_id__audio_url_get",
+    "get_call_sales_coach_calls__call_id__get",
+    "get_call_transcript_sales_coach_calls__call_id__transcript_get",
+    "get_sales_coach_leaderboard_sales_coach_leaderboard_get",
+    "list_calls_for_contact_voice_dialer_calls_get",
+    "list_calls_sales_coach_calls_get"
+  ],
+  "components": [
+    {
+      "name": "CallScorecard",
+      "file": "components/call-scorecard.tsx",
+      "purpose": "One graded practice call: overall score, stages with checklist verdicts, strengths and improvements, recording on demand, transcript, delete (confirmed).",
+      "operations": [
+        "get_call_sales_coach_calls__call_id__get",
+        "get_call_transcript_sales_coach_calls__call_id__transcript_get",
+        "get_call_audio_url_sales_coach_calls__call_id__audio_url_get",
+        "delete_call_sales_coach_calls__call_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CoachingFeed",
+      "file": "components/coaching-feed.tsx",
+      "purpose": "Practice calls newest first with the first tip, a leaderboard tab, optional real dialer calls tab and a create-row form.",
+      "operations": [
+        "list_calls_sales_coach_calls_get",
+        "get_sales_coach_leaderboard_sales_coach_leaderboard_get",
+        "create_call_sales_coach_calls_post",
+        "list_calls_for_contact_voice_dialer_calls_get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/coach-types.ts",
+      "purpose": "Call, segment and leaderboard shapes, and scorecardOf(), which reads checklist-stage and legacy three-category evaluations into one Scorecard."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/read-a-scorecard.ts",
+      "title": "Read a call's score, stages and transcript",
+      "when": "Building a report or alert from graded practice calls."
+    },
+    {
+      "file": "recipes/weekly-coaching-digest.ts",
+      "title": "Weekly digest of the weakest areas per rep",
+      "when": "A manager wants one message per rep with what to work on."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "dialer-installed",
+      "description": "The dialer block is installed (CoachingFeed's Real calls tab uses its CallLog).",
+      "where": "app",
+      "verify": "components/g8/dialer/components/call-log.tsx exists (the CLI installs it)."
+    },
+    {
+      "id": "manager-key",
+      "description": "To read other reps' calls the key must belong to an org admin or sales manager; a rep's key sees only its own.",
+      "where": "api",
+      "verify": "GET /sales-coach/calls?email=<another rep> answers 200, not 403."
+    },
+    {
+      "id": "practice-in-app",
+      "description": "The live practice conversation itself runs in the graph8 app; the API exposes the resulting calls, scores and transcripts.",
+      "where": "app",
+      "verify": "A rep has completed at least one practice call in graph8."
+    }
+  ],
+  "scopes": [
+    "team:delete",
+    "team:read",
+    "team:write",
+    "voice:read"
+  ],
+  "defaults": [
+    {
+      "decision": "Whose calls the feed shows",
+      "default": "the key owner's own",
+      "askHuman": false
+    },
+    {
+      "decision": "Show delete and the create-row form",
+      "default": "delete on (turn it off for reps with allowDelete), create form off",
+      "askHuman": false
+    },
+    {
+      "decision": "Who may read other reps' calls",
+      "default": "managers only; enforced by graph8, 403 otherwise",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/coach/components/call-scorecard.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+/**
+ * CallScorecard: one graded practice call. Overall score, each stage's result with its checklist lines
+ * (met / partial / missed), the summary, strengths and improvements, the recording, and the transcript.
+ *
+ * SDK operations, in order:
+ *   1. getCall            GET    /sales-coach/calls/{call_id}               (read)  row + scores + inline segments
+ *   2. getCallTranscript  GET    /sales-coach/calls/{call_id}/transcript    (read)  ordered segments (owner or manager)
+ *   3. getCallAudioUrl    GET    /sales-coach/calls/{call_id}/audio-url     (read)  signed URL, fetched only on "Load recording"
+ *   4. deleteCall         DELETE /sales-coach/calls/{call_id}               (destructive, ConfirmSpendDialog)
+ *
+ * Reading another rep's call needs a manager key (403 otherwise; the error is shown as-is). Deleting a call
+ * removes its transcript and scores, so a score that was on the leaderboard disappears.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, 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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import { bodyOf, clock, listOf, scorecardOf } from "../lib/coach-types";
+import type { CoachCall, CoachSegment } from "../lib/coach-types";
+
+export interface CallScorecardProps {
+  callId: string;
+  /** Called after the call was deleted. */
+  onDeleted?: (callId: string) => void;
+  /** Hide the delete button (reps usually should not see it). */
+  allowDelete?: boolean;
+  className?: string;
+}
+
+const VERDICT_STYLE: Record<string, string> = { met: "text-green-700", partial: "text-amber-600", missed: "text-destructive" };
+
+export function CallScorecard({ callId, onDeleted, allowDelete = true, className }: CallScorecardProps) {
+  const [audio, setAudio] = useState<{ callId: string; url: string } | null>(null);
+  const [deleting, setDeleting] = useState(false);
+
+  // A different call is a different context: drop the recording and any open confirmation.
+  useEffect(() => { setAudio(null); setDeleting(false); loadAudio.reset(); remove.reset(); }, [callId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const call = useG8Query((signal) => g8Get(`/sales-coach/calls/${callId}`, undefined, { signal }), [callId]);
+  const transcript = useG8Query((signal) => g8Get(`/sales-coach/calls/${callId}/transcript`, undefined, { signal }), [callId]);
+  const loadAudio = useG8Mutation(async (id: string) => {
+    const res = bodyOf<{ signedUrl?: string; signed_url?: string }>(await g8Get(`/sales-coach/calls/${id}/audio-url`));
+    return { callId: id, url: res.signedUrl ?? res.signed_url ?? "" };
+  }, { onSuccess: (a) => setAudio(a) });
+  const remove = useG8Mutation((id: string) => g8Delete(`/sales-coach/calls/${id}`), { onSuccess: (_r, id) => { setDeleting(false); onDeleted?.(id); } });
+
+  const loadedRow = bodyOf<CoachCall>(call.data);
+  // Stale data from the previous call stays in the query while the new one loads: never show it next to this call's Delete.
+  const showingOther = Boolean(call.data) && loadedRow.id !== callId;
+  if (call.error) return <ApiError error={call.error} title="Could not load the call" onRetry={() => void call.refetch()} />;
+  if ((call.loading && !call.data) || showingOther) return <Skeleton className="h-48 w-full" aria-label="Loading call" />;
+
+  const row = loadedRow;
+  const card = scorecardOf(row);
+  const fetched = transcript.loading ? [] : listOf<CoachSegment>(transcript.data, "items");
+  const segments = fetched.length ? fetched : (row.transcript_segments ?? []);
+  const shownAudio = audio?.callId === callId ? audio.url : "";
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <header className="flex flex-wrap items-start justify-between gap-3">
+        <div>
+          <h2 className="text-lg font-semibold">{row.prospect_name || "Practice call"}{row.prospect_company ? ` at ${row.prospect_company}` : ""}</h2>
+          <p className="text-sm text-muted-foreground">
+            {[row.user_email, row.call_mode, row.call_status, row.duration_ms ? clock(row.duration_ms) : null, row.date_of_call ? new Date(row.date_of_call).toLocaleDateString() : null].filter(Boolean).join(" - ")}
+          </p>
+        </div>
+        <div className="text-right">
+          <div data-testid="overall-score" className="text-3xl font-semibold">{card?.scorePct != null ? `${Math.round(card.scorePct)}%` : "-"}</div>
+          <div className="text-xs text-muted-foreground">{card ? "overall" : "not graded yet"}</div>
+        </div>
+      </header>
+
+      {!card ? <EmptyState title="Not graded yet" description="The score appears here once the call finishes and is graded." /> : (
+        <>
+          {card.summary ? <p className="text-sm">{card.summary}</p> : null}
+          <ul className="flex flex-col gap-3" data-testid="stages">
+            {card.stages.map((s) => (
+              <li key={s.label} className="rounded-md border p-3">
+                <div className="flex items-center justify-between"><span className="font-medium">{s.label}</span><span className="text-sm">{s.pct != null ? `${s.pct}%` : "n/a"}</span></div>
+                <ul className="mt-2 flex flex-col gap-1 text-sm">
+                  {s.criteria.map((c, i) => (
+                    <li key={i} className="flex gap-2"><span className={`w-16 shrink-0 text-xs font-medium uppercase ${VERDICT_STYLE[c.verdict] ?? ""}`}>{c.verdict || "-"}</span><span>{c.label}{c.evidence ? <span className="block text-xs text-muted-foreground">&quot;{c.evidence}&quot;</span> : null}</span></li>
+                  ))}
+                </ul>
+              </li>
+            ))}
+          </ul>
+          <div className="grid gap-3 sm:grid-cols-2">
+            <div><h3 className="mb-1 text-sm font-semibold">Strengths</h3><ul className="list-disc pl-5 text-sm">{card.strengths.map((t, i) => <li key={i}>{t}</li>)}</ul></div>
+            <div><h3 className="mb-1 text-sm font-semibold">To improve</h3><ul className="list-disc pl-5 text-sm">{card.improvements.map((t, i) => <li key={i}>{t}</li>)}</ul></div>
+          </div>
+        </>
+      )}
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-sm font-semibold">Recording</h3>
+        {row.audio_url ? (shownAudio ? <audio controls src={shownAudio} className="w-full" /> : <div><Button size="sm" variant="outline" loading={loadAudio.loading} onClick={() => void loadAudio.mutate(callId)}>Load recording</Button></div>) : <p className="text-sm text-muted-foreground">No recording.</p>}
+        {loadAudio.error ? <ApiError error={loadAudio.error} title="Could not load the recording" /> : null}
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <h3 className="text-sm font-semibold">Transcript</h3>
+        {transcript.error ? <ApiError error={transcript.error} title="Could not load the transcript" onRetry={() => void transcript.refetch()} /> : null}
+        <ul className="flex max-h-96 flex-col gap-1 overflow-y-auto" data-testid="transcript">
+          {segments.map((s, i) => (
+            <li key={s.id ?? i} className="text-sm"><span className="mr-2 text-xs text-muted-foreground">{clock(s.in_call_timestamp)}</span><span className="mr-2 font-medium">{s.speaker}</span>{s.content}</li>
+          ))}
+        </ul>
+        {!transcript.loading && !transcript.error && segments.length === 0 ? <p className="text-sm text-muted-foreground">No transcript.</p> : null}
+      </div>
+
+      {allowDelete ? <div><Button size="sm" variant="ghost" onClick={() => setDeleting(true)}>Delete call</Button></div> : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the call" /> : null}
+      <ConfirmSpendDialog open={deleting} tier="destructive" title="Delete this call" description="Its transcript, scores and recording link are removed, and its score leaves the leaderboard." affected={1}
+        confirming={remove.loading} onConfirm={() => void remove.mutate(callId)} onCancel={() => setDeleting(false)} />
+    </div>
+  );
+}

package/blocks/coach/components/coaching-feed.tsx

@@ -0,0 +1,140 @@
+"use client";
+
+/**
+ * CoachingFeed: a rep's (or, with a manager key, anyone's) practice calls as a coaching feed, newest first:
+ * each graded call shows its score and the first thing to work on. Click one to open its CallScorecard.
+ * A Leaderboard tab ranks the floor; an optional "Real calls" tab lists the rep's dialer calls (dialer block).
+ *
+ * SDK operations, in order:
+ *   1. listCalls                      GET  /sales-coach/calls?email=            (read)  scores and segments inline; another rep's email is manager-only
+ *   2. getSalesCoachLeaderboard       GET  /sales-coach/leaderboard             (read)  completed calls, grouped by rep
+ *   3. createCall                     POST /sales-coach/calls { call_mode, prospect_name, prospect_company, persona_type }  (write)
+ *   4. getCall, getCallTranscript, getCallAudioUrl, deleteCall   via CallScorecard (see its header)
+ *   5. listCallsForContact            GET  /voice/dialer/calls?user_email=      (read)  via the dialer block's CallLog, "Real calls" tab only
+ *
+ * The create form and the Real calls tab need to know whose calls they are: the form is hidden when `userEmail` names another rep
+ * (it would create a call for the key owner), and the Real calls tab only shows when `userEmail` is set (the dialer API needs a rep).
+ * `createCall` only creates the call ROW. Running the practice conversation itself happens in the graph8 app
+ * (the live audio session is not part of the public API), so `allowCreate` is off by default.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input, Label, 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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { CallLog } from "@/g8/dialer/components/call-log";
+import { avgOf, listOf, scorecardOf } from "../lib/coach-types";
+import type { CoachCall, LeaderboardRow } from "../lib/coach-types";
+import { CallScorecard } from "./call-scorecard";
+
+export interface CoachingFeedProps {
+  /** Whose practice calls. Omit for the key owner's own. Another rep's needs a manager key. */
+  userEmail?: string;
+  /** Called with a call id instead of opening the scorecard inline. */
+  onOpenCall?: (callId: string) => void;
+  /** Show the "New practice call" form (creates the row only). Default false. */
+  allowCreate?: boolean;
+  /** Add a "Real calls" tab with the rep's dialer calls. Default false. */
+  showDialerCalls?: boolean;
+  allowDelete?: boolean;
+  /** Rows shown before "Show more". Default 15. */
+  pageSize?: number;
+  className?: string;
+}
+
+type Tab = "feed" | "board" | "real";
+
+export function CoachingFeed({ userEmail, onOpenCall, allowCreate = false, showDialerCalls = false, allowDelete, pageSize = 15, className }: CoachingFeedProps) {
+  const [tab, setTab] = useState<Tab>("feed");
+  const [open, setOpen] = useState<string | null>(null);
+  const [shown, setShown] = useState(pageSize);
+  const [form, setForm] = useState<{ call_mode: "assisted" | "compete"; prospect_name: string; prospect_company: string; persona_type: string } | null>(null);
+
+  // Another rep's calls are a different list: forget the selection and paging.
+  useEffect(() => { setOpen(null); setShown(pageSize); }, [userEmail, pageSize]);
+
+  const calls = useG8Query((signal) => g8Get("/sales-coach/calls", { email: userEmail }, { signal }), [userEmail]);
+  const board = useG8Query((signal) => g8Get("/sales-coach/leaderboard", undefined, { signal }), [], { enabled: tab === "board" });
+  const create = useG8Mutation(() => g8Post("/sales-coach/calls", { call_mode: form?.call_mode, prospect_name: form?.prospect_name.trim() || undefined, prospect_company: form?.prospect_company.trim() || undefined, persona_type: form?.persona_type.trim() || undefined }), {
+    onSuccess: () => { setForm(null); void calls.refetch(); },
+  });
+
+  const rows = listOf<CoachCall>(calls.data, "items");
+  const ranked = [...listOf<LeaderboardRow>(board.data, "items")].sort((a, b) => b.score - a.score);
+  const select = (id: string) => (onOpenCall ? onOpenCall(id) : setOpen(id));
+  const tabs: Array<[Tab, string]> = [["feed", "Practice calls"], ["board", "Leaderboard"], ...(showDialerCalls && userEmail ? [["real", "Real calls"] as [Tab, string]] : [])];
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <div className="flex items-center justify-between border-b">
+        <div role="tablist" className="flex gap-1">
+          {tabs.map(([id, label]) => (
+            <button key={id} role="tab" type="button" aria-selected={tab === id} onClick={() => setTab(id)} className={`px-3 py-2 text-sm ${tab === id ? "border-b-2 border-primary font-medium" : "text-muted-foreground"}`}>{label}</button>
+          ))}
+        </div>
+        {allowCreate && !userEmail && tab === "feed" ? <Button size="sm" onClick={() => setForm({ call_mode: "assisted", prospect_name: "", prospect_company: "", persona_type: "" })}>New practice call</Button> : null}
+      </div>
+
+      {tab === "feed" ? (
+        <>
+          {form ? (
+            <div className="flex flex-col gap-2 rounded-md border p-3">
+              <div className="grid gap-2 sm:grid-cols-2">
+                <div className="flex flex-col gap-1"><Label htmlFor="pc-name">Prospect</Label><Input id="pc-name" value={form.prospect_name} onChange={(e) => setForm({ ...form, prospect_name: e.target.value })} /></div>
+                <div className="flex flex-col gap-1"><Label htmlFor="pc-company">Company</Label><Input id="pc-company" value={form.prospect_company} onChange={(e) => setForm({ ...form, prospect_company: e.target.value })} /></div>
+                <div className="flex flex-col gap-1"><Label htmlFor="pc-persona">Persona</Label><Input id="pc-persona" value={form.persona_type} onChange={(e) => setForm({ ...form, persona_type: e.target.value })} /></div>
+                <div className="flex flex-col gap-1"><Label htmlFor="pc-mode">Mode</Label>
+                  <select id="pc-mode" className="h-9 rounded-md border bg-background px-2 text-sm" value={form.call_mode} onChange={(e) => setForm({ ...form, call_mode: e.target.value as "assisted" | "compete" })}><option value="assisted">Training</option><option value="compete">Compete</option></select></div>
+              </div>
+              {create.error ? <ApiError error={create.error} title="Could not create the call" /> : null}
+              <div className="flex justify-end gap-2"><Button variant="ghost" onClick={() => setForm(null)}>Cancel</Button><Button loading={create.loading} onClick={() => void create.mutate(undefined)}>Create call</Button></div>
+            </div>
+          ) : null}
+          {calls.error ? <ApiError error={calls.error} title="Could not load practice calls" onRetry={() => void calls.refetch()} /> : null}
+          {calls.loading && rows.length === 0 ? Array.from({ length: 3 }, (_, i) => <Skeleton key={i} className="h-16 w-full" />) : null}
+          <ul className="flex flex-col gap-2" data-testid="feed">
+            {rows.slice(0, shown).map((c) => {
+              const card = scorecardOf(c);
+              const tip = card?.improvements[0];
+              return (
+                <li key={c.id}>
+                  <button type="button" data-testid={`call-${c.id}`} onClick={() => select(c.id)} className={`w-full rounded-md border p-3 text-left ${open === c.id ? "bg-accent" : ""}`}>
+                    <span className="flex items-center justify-between"><span className="font-medium">{c.prospect_name || "Practice call"}{c.prospect_company ? ` at ${c.prospect_company}` : ""}</span><span className="text-sm">{card?.scorePct != null ? `${Math.round(card.scorePct)}%` : c.call_status ?? ""}</span></span>
+                    <span className="block text-xs text-muted-foreground">{c.date_of_call ? new Date(c.date_of_call).toLocaleDateString() : ""} {c.call_mode ?? ""}</span>
+                    {tip ? <span className="mt-1 block text-sm">Work on: {tip}</span> : null}
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+          {!calls.loading && !calls.error && rows.length === 0 ? <EmptyState title="No practice calls yet" description="Graded practice calls and what to work on next show up here." /> : null}
+          {rows.length > shown ? <Button variant="outline" size="sm" onClick={() => setShown(shown + pageSize)}>Show more</Button> : null}
+          {open && !onOpenCall ? <CallScorecard key={open} callId={open} allowDelete={allowDelete} onDeleted={() => { setOpen(null); void calls.refetch(); void board.refetch(); }} /> : null}
+        </>
+      ) : null}
+
+      {tab === "board" ? (
+        <>
+          {board.error ? <ApiError error={board.error} title="Could not load the leaderboard" onRetry={() => void board.refetch()} /> : null}
+          <div className="rounded-md border">
+            <Table>
+              <TableHeader><TableRow><TableHead className="w-12">#</TableHead><TableHead>Rep</TableHead><TableHead className="text-right">Calls</TableHead><TableHead className="text-right">Avg</TableHead><TableHead className="text-right">Total</TableHead></TableRow></TableHeader>
+              <TableBody>
+                {board.loading && ranked.length === 0 ? Array.from({ length: 3 }, (_, i) => <TableRow key={i}><TableCell colSpan={5}><Skeleton className="h-5 w-full" /></TableCell></TableRow>) : null}
+                {ranked.map((r, i) => (
+                  <TableRow key={r.email} data-testid={`rank-${r.email}`}><TableCell>{i + 1}</TableCell><TableCell>{r.name}<span className="ml-2 text-xs text-muted-foreground">{r.email}</span></TableCell><TableCell className="text-right">{r.calls}</TableCell><TableCell className="text-right">{avgOf(r)}</TableCell><TableCell className="text-right">{r.score}</TableCell></TableRow>
+                ))}
+              </TableBody>
+            </Table>
+            {!board.loading && !board.error && ranked.length === 0 ? <EmptyState title="Nobody on the board yet" description="Completed practice calls rank here." /> : null}
+          </div>
+        </>
+      ) : null}
+
+      {tab === "real" ? <CallLog userEmail={userEmail} limit={25} /> : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,116 @@
+"use client";
+
+/**
+ * Shapes of the sales-coach routes and the reader that turns a call's stored evaluation into a scorecard.
+ *
+ * A practice call row carries `scores[0].evaluation_data` (sometimes a JSON string, sometimes an object,
+ * snake_case or camelCase depending on the route). Checklist-graded calls have `stages[].criteria[]` with a
+ * `verdict` of met / partial / missed; older calls have `evaluatorResult.{opening,pattern_interrupt,
+ * value_proposition}.score` out of 10. Both are turned into the same `Scorecard`.
+ */
+
+import type { G8Envelope } from "@/g8/lib/g8-client";
+
+export interface CoachSegment {
+  id?: string;
+  speaker: string;
+  content: string;
+  /** Milliseconds from the start of the call. */
+  in_call_timestamp?: number;
+}
+
+export interface CoachCall {
+  id: string;
+  user_email?: string;
+  prospect_name?: string | null;
+  prospect_company?: string | null;
+  date_of_call?: string | null;
+  call_mode?: string;
+  call_status?: string;
+  persona_type?: string | null;
+  audio_url?: string | null;
+  final_score?: number | null;
+  duration_ms?: number | null;
+  scores?: Array<{ evaluation_data?: unknown; evaluationData?: unknown; created_at?: string }>;
+  transcript_segments?: CoachSegment[];
+}
+
+export interface LeaderboardRow {
+  id?: string | null;
+  name: string;
+  email: string;
+  score: number;
+  calls: number;
+  avgScore?: number;
+  avg_score?: number;
+}
+
+export type Verdict = "met" | "partial" | "missed" | string;
+
+export interface ScoreStage {
+  label: string;
+  /** 0-100, or null when no line applied. */
+  pct: number | null;
+  criteria: Array<{ label: string; verdict: Verdict; evidence?: string }>;
+}
+
+export interface Scorecard {
+  scorePct: number | null;
+  stages: ScoreStage[];
+  summary: string;
+  strengths: string[];
+  improvements: string[];
+}
+
+const POINTS: Record<string, number> = { met: 1, partial: 0.5, missed: 0 };
+const LEGACY = [["opening", "Opening"], ["pattern_interrupt", "Pattern interrupt"], ["value_proposition", "Value proposition"]] as const;
+
+export function bodyOf<T = Record<string, unknown>>(res: G8Envelope<unknown> | null | undefined): T {
+  const data = (res as { data?: unknown } | null | undefined)?.data;
+  return (data ?? res ?? {}) as T;
+}
+
+export function listOf<T>(res: G8Envelope<unknown> | null | undefined, ...keys: string[]): T[] {
+  const body = bodyOf<unknown>(res);
+  if (Array.isArray(body)) return body as T[];
+  const rec = (body ?? {}) as Record<string, any>;
+  for (const k of keys) if (Array.isArray(rec[k])) return rec[k] as T[];
+  return [];
+}
+
+function strings(v: unknown): string[] {
+  return Array.isArray(v) ? v.map((x) => (typeof x === "string" ? x : String((x as any)?.text ?? (x as any)?.content ?? ""))).filter(Boolean) : [];
+}
+
+/** The scorecard of a call, or null when it has not been graded. Never throws on odd data. */
+export function scorecardOf(call: CoachCall | null | undefined): Scorecard | null {
+  const first = call?.scores?.[0];
+  let raw: any = first?.evaluation_data ?? first?.evaluationData;
+  if (typeof raw === "string") { try { raw = JSON.parse(raw); } catch { raw = null; } }
+  if (!raw || typeof raw !== "object") return null;
+  const er = raw.evaluatorResult ?? raw.evaluator_result ?? {};
+  const stages: ScoreStage[] = Array.isArray(raw.stages) && raw.stages.length
+    ? raw.stages.map((s: any) => {
+        const criteria = (Array.isArray(s.criteria) ? s.criteria : []).map((c: any) => ({ label: String(c.label ?? c.name ?? c.criterion ?? ""), verdict: String(c.verdict ?? ""), evidence: c.evidence ? String(c.evidence) : undefined }));
+        const judged = criteria.filter((c: { verdict: string }) => Object.hasOwn(POINTS, c.verdict));
+        const pct = judged.length ? Math.round((100 * judged.reduce((n: number, c: { verdict: string }) => n + POINTS[c.verdict], 0)) / judged.length) : null;
+        return { label: String(s.label ?? s.name ?? "Stage"), pct, criteria };
+      })
+    : LEGACY.filter(([k]) => er[k] != null).map(([k, label]) => ({ label, pct: Math.round(((er[k].score ?? 0) / 10) * 100), criteria: [] }));
+  // Legacy rows store `final_score` as a total out of 30 (three categories out of 10); checklist rows store a percent AND scorePct.
+  const checklist = Array.isArray(raw.stages) && raw.stages.length > 0;
+  const fromFinal = typeof call?.final_score === "number" ? (checklist ? call.final_score : Math.round((100 * call.final_score) / 30)) : null;
+  const scorePct = typeof raw.scorePct === "number" ? raw.scorePct : fromFinal;
+  return { scorePct, stages, summary: String(er.summary ?? ""), strengths: strings(er.areas_of_strength ?? er.strengths), improvements: strings(er.areas_of_improvement ?? er.improvements) };
+}
+
+export const avgOf = (r: LeaderboardRow): number => r.avgScore ?? r.avg_score ?? 0;
+
+/** Legacy total score ceiling: three categories, ten points each. */
+export const LEGACY_MAX = 30;
+
+/** m:ss from milliseconds. */
+export function clock(ms: number | undefined | null): string {
+  const s = Math.max(0, Math.round((ms ?? 0) / 1000));
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+}

package/blocks/coach/recipes/read-a-scorecard.ts

@@ -0,0 +1,27 @@
+/**
+ * @title Read a graded practice call: score, stages, transcript
+ * @when Building a report or an alert from practice calls. `listCalls` returns the key owner's calls newest
+ * first with their scores inline; `?email=` for another rep needs a manager key (403 otherwise). A call's
+ * `scores[0].evaluation_data` is either checklist `stages[].criteria[].verdict` (met / partial / missed) or
+ * the older `evaluatorResult` categories scored out of 10. Call ids come from the list, never a guess.
+ * Audio is a short-lived signed URL: fetch it when needed, do not store it.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function latestGradedCall(email?: string) {
+  const list = await g8.api.salesCoach.listCalls({ query: email ? { email } : {} });
+  const calls = (list.data.items ?? []) as Array<{ id: string; final_score?: number | null; scores?: unknown[] }>;
+  const graded = calls.find((c) => (c.scores?.length ?? 0) > 0);
+  if (!graded) return null;
+
+  const transcript = await g8.api.salesCoach.getCallTranscript({ path: { call_id: graded.id } });
+  return { callId: graded.id, score: graded.final_score ?? null, segments: transcript.data.items ?? [] };
+}
+
+export async function recordingUrl(callId: string) {
+  const res = await g8.api.salesCoach.getCallAudioUrl({ path: { call_id: callId } });
+  const data = res.data as { signedUrl?: string; signed_url?: string };
+  return data.signedUrl ?? data.signed_url ?? null;
+}

package/blocks/coach/recipes/weekly-coaching-digest.ts

@@ -0,0 +1,53 @@
+/**
+ * @title A weekly digest: each rep's weakest stage and first tip
+ * @when A manager wants one message per rep. Needs a manager key (other reps' calls are manager-only).
+ * The leaderboard gives the reps (email, calls, avg score); each rep's calls give the stages. Only calls
+ * with a score count. Sending the digest is up to you (email, Slack); nothing here contacts anyone.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Stage = { label?: string; criteria?: Array<{ verdict?: string }> };
+type Evaluation = { stages?: Stage[]; evaluatorResult?: { areas_of_improvement?: string[] } };
+type Call = { date_of_call?: string | null; scores?: Array<{ evaluation_data?: Evaluation | string }> };
+
+/** evaluation_data is an object on some routes and a JSON string on others. */
+function evaluationOf(call: Call): Evaluation | undefined {
+  const raw = call.scores?.[0]?.evaluation_data;
+  if (typeof raw !== "string") return raw;
+  try { return JSON.parse(raw) as Evaluation; } catch { return undefined; }
+}
+
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+const POINTS: Record<string, number> = { met: 1, partial: 0.5, missed: 0 };
+
+export async function digest() {
+  const board = await g8.api.salesCoach.getSalesCoachLeaderboard();
+  const reps = (board.data.items ?? []) as Array<{ email: string; name: string; calls: number }>;
+  const out: Array<{ email: string; weakest?: string; tip?: string }> = [];
+
+  for (const rep of reps) {
+    const list = await g8.api.salesCoach.listCalls({ query: { email: rep.email } });
+    const totals = new Map<string, { sum: number; n: number }>();
+    let tip: string | undefined;
+    for (const call of (list.data.items ?? []) as Call[]) {
+      // Last 7 days only; a call without a date is skipped rather than guessed.
+      const when = call.date_of_call ? Date.parse(call.date_of_call) : NaN;
+      if (!(Date.now() - when <= WEEK_MS)) continue;
+      const ev = evaluationOf(call);
+      tip ??= ev?.evaluatorResult?.areas_of_improvement?.[0];
+      for (const stage of ev?.stages ?? []) {
+        for (const c of stage.criteria ?? []) {
+          if (!c.verdict || !Object.hasOwn(POINTS, c.verdict) || !stage.label) continue;
+          const t = totals.get(stage.label) ?? { sum: 0, n: 0 };
+          totals.set(stage.label, { sum: t.sum + POINTS[c.verdict], n: t.n + 1 });
+        }
+      }
+    }
+    const weakest = [...totals.entries()].sort((a, b) => a[1].sum / a[1].n - b[1].sum / b[1].n)[0]?.[0];
+    out.push({ email: rep.email, weakest, tip });
+  }
+  return out;
+}