@graph8/sdk 0.303.0 → 0.357.0

package/blocks/quotes/components/product-picker.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+/**
+ * ProductPicker: choose a quotable product (and its price) to add to a quote.
+ *
+ * Only products marked quotable in graph8 appear: Stripe products the workspace opted in, and manual products.
+ * Creating or updating a quote with a non-quotable product is refused by the API, which is why the picker reads
+ * this list instead of the raw Stripe catalog. Tiered Stripe prices are not offered (the API leaves them out).
+ *
+ * SDK operations, in the order the picker uses them:
+ *   1. listQuotableProducts  GET /quotable-products?currency&page&limit  (read; `{ items, total, page, limit }`)
+ *
+ * A pick returns a ready LineItem (`onPick`), carrying `stripe_product_id` + `stripe_price_id` or
+ * `manual_product_id`, so the builder never has to guess ids.
+ */
+
+import { useState } from "react";
+import { Button, Input, Skeleton } from "@graph8/sdk/ui";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { body, frequencyOf, lineFromProduct, money, text } from "../lib/quotes";
+import type { LineItem, ProductPrice, QuotableProduct } from "../lib/quotes";
+
+export interface ProductPickerProps {
+  /** Only offer prices in this currency (the quote's currency). */
+  currency?: string;
+  onPick: (line: LineItem) => void;
+  pageSize?: number;
+  className?: string;
+}
+
+const intervalLabel = (p: ProductPrice) => (frequencyOf(p.recurring_interval) === "one_time" ? "one time" : `per ${p.recurring_interval}`);
+
+export function ProductPicker({ currency, onPick, pageSize = 25, className }: ProductPickerProps) {
+  const [page, setPage] = useState(1);
+  const [search, setSearch] = useState("");
+  const q = useG8Query((signal) => g8Get("/quotable-products", { currency: currency?.toUpperCase(), page, limit: pageSize }, { signal }), [currency, page, pageSize]);
+  const data = body(q.data);
+  const items = (Array.isArray(data.items) ? data.items : []) as QuotableProduct[];
+  const total = typeof data.total === "number" ? data.total : items.length;
+  const needle = search.trim().toLowerCase();
+  const shown = needle ? items.filter((p) => `${p.name} ${text(p.category)}`.toLowerCase().includes(needle)) : items;
+
+  return (
+    <div className={className}>
+      <Input aria-label="Search products" placeholder="Filter this page by name or category" value={search} onChange={(e) => setSearch(e.target.value)} className="mb-3" />
+      {q.error ? <ApiError error={q.error} onRetry={() => void q.refetch()} /> : null}
+      {q.loading && !q.data ? <div className="space-y-2" aria-busy="true">{[0, 1, 2].map((i) => <Skeleton key={i} className="h-12 w-full" />)}</div> : null}
+      {!q.loading && !q.error && shown.length === 0 ? (
+        <EmptyState title="No quotable products" description="Mark a Stripe product as quotable, or add a manual product, in graph8's quote settings." />
+      ) : null}
+      <ul className="divide-y rounded-md border">
+        {shown.map((p) => (
+          <li key={p.stripe_product_id ?? p.manual_product_id} className="p-3 text-sm">
+            <div className="font-medium">{p.name} <span className="text-muted-foreground text-xs font-normal">{p.source}{p.category ? ` · ${p.category}` : ""}</span></div>
+            {p.description ? <div className="text-muted-foreground text-xs">{p.description}</div> : null}
+            <div className="mt-2 flex flex-wrap gap-2">
+              {p.prices.length === 0 ? <span className="text-muted-foreground text-xs">No flat price for this currency.</span> : null}
+              {p.prices.map((price, i) => (
+                <Button key={price.stripe_price_id ?? i} size="sm" variant="outline" aria-label={`Add ${p.name} ${money(price.unit_amount, price.currency ?? currency)} ${intervalLabel(price)}`}
+                  onClick={() => onPick(lineFromProduct(p, price))}>
+                  {money(price.unit_amount, price.currency ?? currency)} {intervalLabel(price)}
+                </Button>
+              ))}
+            </div>
+          </li>
+        ))}
+      </ul>
+      <div className="mt-3 flex items-center justify-between text-sm">
+        <span className="text-muted-foreground">{total} products</span>
+        <div className="flex gap-2">
+          <Button size="sm" variant="outline" disabled={page === 1} onClick={() => setPage(page - 1)}>Previous</Button>
+          <Button size="sm" variant="outline" disabled={page * pageSize >= total} onClick={() => setPage(page + 1)}>Next</Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/blocks/quotes/components/quote-builder.tsx

@@ -0,0 +1,195 @@
+"use client";
+
+/**
+ * QuoteBuilder: create or edit a DRAFT quote: title, signer, contract dates, payment terms and line items picked
+ * from quotable products (ProductPicker), with live totals.
+ *
+ * SDK operations, in the order the builder uses them:
+ *   1. getQuote            GET   /quotes/{id}               (read; only when editing, to fill the form)
+ *   2. listQuotableProducts GET  /quotable-products          (read; inside ProductPicker)
+ *   3. searchQuoteContacts GET   /quote-contacts?q&company_id&deal_id (read; the signer picker)
+ *   4. createQuote         POST  /quotes                     (external tier)
+ *   5. updateQuotePatch    PATCH /quotes/{id}                (external tier; drafts only, the server refuses others)
+ *
+ * Saving a draft emails nobody: the contract tiers quote writes `external` because the same route family sends
+ * quotes, but a draft only stores data. So this screen saves in one click and keeps the confirmation for the
+ * step that really reaches the customer, which is SEND in QuoteViewer (ConfirmSpendDialog, tier external).
+ *
+ * Required by the API: `title`, `deal_id`, `contract_start_date`, at least one line item, and a signer
+ * (`signer_contact_id` or `signer_email`). The form lists what is still missing instead of failing with a 422.
+ * `deal_id` comes from the deals block (PipelineBoard / DealDetail); this screen never invents one.
+ */
+
+import { useEffect, useMemo, useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Textarea } from "@graph8/sdk/ui";
+import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { PAYMENT_TERMS, asRec, body, linesFromQuote, lineTotal, money, subtotal, text, toRequestLines } from "../lib/quotes";
+import type { LineItem, PaymentTerms, Rec } from "../lib/quotes";
+import { useDebounced } from "../hooks/use-debounced";
+import { ProductPicker } from "./product-picker";
+
+export interface QuoteBuilderProps {
+  /** Edit this draft. Omit to create a new quote (then `dealId` is required). */
+  quoteId?: string;
+  /** The deal the quote belongs to (UUID from the deals block). */
+  dealId?: string;
+  /** Company (mashup company id) used to find signer contacts. */
+  companyId?: number;
+  currency?: string;
+  /** Called with the saved quote id. Route to QuoteViewer from here. */
+  onSaved?: (quoteId: string) => void;
+  className?: string;
+}
+
+interface Form {
+  title: string;
+  currency: string;
+  payment_terms: PaymentTerms;
+  contract_start_date: string;
+  valid_until: string;
+  tax: string;
+  notes: string;
+  signer_email: string;
+  signer_name: string;
+  signer_contact_id: number | null;
+}
+
+const EMPTY: Form = { title: "", currency: "USD", payment_terms: "net_30", contract_start_date: "", valid_until: "", tax: "0", notes: "", signer_email: "", signer_name: "", signer_contact_id: null };
+
+function SignerPicker({ form, setForm, companyId, dealId }: { form: Form; setForm: (f: Form) => void; companyId?: number; dealId?: string }) {
+  const [q, setQ] = useState("");
+  const debounced = useDebounced(q);
+  const found = useG8Query((signal) => g8Get("/quote-contacts", { q: debounced || undefined, company_id: companyId, deal_id: dealId, limit: 20 }, { signal }), [debounced, companyId, dealId]);
+  const contacts = (Array.isArray(body(found.data).items) ? body(found.data).items : []) as Rec[];
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="qb-signer-search">Signer</Label>
+      <Input id="qb-signer-search" placeholder="Search contacts by name or email" value={q} onChange={(e) => setQ(e.target.value)} />
+      {found.error ? <ApiError error={found.error} onRetry={() => void found.refetch()} /> : null}
+      <div className="flex flex-wrap gap-2">
+        {contacts.map((c) => (
+          <Button key={text(c.id)} size="sm" variant={form.signer_contact_id === Number(c.id) ? "default" : "outline"}
+            onClick={() => setForm({ ...form, signer_contact_id: Number(c.id), signer_email: text(c.email), signer_name: text(c.person_name) })}>
+            {text(c.name)}
+          </Button>
+        ))}
+      </div>
+      <div className="grid gap-2 sm:grid-cols-2">
+        <Input aria-label="Signer email" placeholder="signer@company.com" value={form.signer_email} onChange={(e) => setForm({ ...form, signer_email: e.target.value, signer_contact_id: null })} />
+        <Input aria-label="Signer name" placeholder="Signer name" value={form.signer_name} onChange={(e) => setForm({ ...form, signer_name: e.target.value })} />
+      </div>
+    </div>
+  );
+}
+
+function LinesTable({ lines, setLines, currency }: { lines: LineItem[]; setLines: (l: LineItem[]) => void; currency: string }) {
+  const patch = (key: string, p: Partial<LineItem>) => setLines(lines.map((l) => (l.key === key ? { ...l, ...p } : l)));
+  if (lines.length === 0) return <p className="text-muted-foreground text-sm">No line items yet. Pick a product below.</p>;
+  return (
+    <Table>
+      <TableHeader><TableRow><TableHead>Product</TableHead><TableHead>Qty</TableHead><TableHead>Unit ({currency})</TableHead><TableHead>Discount %</TableHead><TableHead className="text-right">Total</TableHead><TableHead /></TableRow></TableHeader>
+      <TableBody>
+        {lines.map((l) => (
+          <TableRow key={l.key}>
+            <TableCell>{l.product_name}<div className="text-muted-foreground text-xs">{l.billing_frequency === "one_time" ? "one time" : `per ${l.billing_frequency}`}</div></TableCell>
+            <TableCell><Input aria-label={`Quantity of ${l.product_name}`} type="number" min={1} value={l.quantity} className="w-20" onChange={(e) => patch(l.key, { quantity: Math.max(1, Number(e.target.value) || 1) })} /></TableCell>
+            <TableCell><Input aria-label={`Unit price of ${l.product_name}`} type="number" min={0} step="0.01" value={l.unit_amount / 100} className="w-28" onChange={(e) => patch(l.key, { unit_amount: Math.round((Number(e.target.value) || 0) * 100) })} /></TableCell>
+            <TableCell><Input aria-label={`Discount of ${l.product_name}`} type="number" min={0} max={100} value={l.discount_pct} className="w-20" onChange={(e) => patch(l.key, { discount_pct: Math.min(100, Math.max(0, Number(e.target.value) || 0)) })} /></TableCell>
+            <TableCell className="text-right">{money(lineTotal(l), currency)}</TableCell>
+            <TableCell className="text-right"><Button size="sm" variant="ghost" aria-label={`Remove ${l.product_name}`} onClick={() => setLines(lines.filter((x) => x.key !== l.key))}>Remove</Button></TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+
+export function QuoteBuilder({ quoteId, dealId, companyId, currency = "USD", onSaved, className }: QuoteBuilderProps) {
+  const existing = useG8Query((signal) => g8Get(`/quotes/${encodeURIComponent(quoteId ?? "")}`, undefined, { signal }), [quoteId], { enabled: Boolean(quoteId) });
+  const [form, setForm] = useState<Form>({ ...EMPTY, currency });
+  const [lines, setLines] = useState<LineItem[]>([]);
+  const detail = body(existing.data);
+  const status = text(detail.status, "draft");
+
+  useEffect(() => {
+    if (!quoteId || !existing.data) return;
+    setForm({
+      title: text(detail.title), currency: text(detail.currency, currency), payment_terms: (PAYMENT_TERMS as readonly string[]).includes(text(detail.payment_terms)) ? (text(detail.payment_terms) as PaymentTerms) : "net_30",
+      contract_start_date: text(detail.contract_start_date).slice(0, 10), valid_until: text(detail.valid_until).slice(0, 10), tax: String(Number(detail.tax_amount ?? 0) / 100),
+      notes: text(detail.public_notes), signer_email: text(detail.signer_contact_email ?? detail.signer_email), signer_name: text(detail.signer_contact_name ?? detail.signer_name),
+      signer_contact_id: typeof detail.signer_contact_id === "number" ? detail.signer_contact_id : null,
+    });
+    setLines(linesFromQuote(detail.line_items));
+  }, [existing.data]);
+
+  const taxCents = Math.round((Number(form.tax) || 0) * 100);
+  const sub = useMemo(() => subtotal(lines), [lines]);
+  const effectiveDeal = dealId ?? text(detail.deal_id);
+  const missing = [
+    !form.title.trim() && "a title",
+    !quoteId && !effectiveDeal && "a deal",
+    !form.contract_start_date && "a contract start date",
+    lines.length === 0 && "at least one line item",
+    !form.signer_email.trim() && form.signer_contact_id == null && "a signer",
+  ].filter(Boolean) as string[];
+
+  const save = useG8Mutation(async () => {
+    const payload: Rec = {
+      title: form.title.trim(), currency: form.currency, payment_terms: form.payment_terms, contract_start_date: form.contract_start_date,
+      line_items: toRequestLines(lines), tax_amount: taxCents, public_notes: form.notes || null, valid_until: form.valid_until || null,
+      ...(form.signer_contact_id != null ? { signer_contact_id: form.signer_contact_id } : { signer_email: form.signer_email.trim(), signer_name: form.signer_name.trim() || null }),
+    };
+    if (quoteId) return body(await g8Patch(`/quotes/${encodeURIComponent(quoteId)}`, payload));
+    return body(await g8Post("/quotes", { ...payload, deal_id: effectiveDeal, ...(companyId != null ? { mashup_company_id: companyId } : {}) }));
+  }, { onSuccess: (q) => { const id = text(q.id) || quoteId; if (id) onSaved?.(id); } });
+
+  if (quoteId && existing.loading && !existing.data) return <div className={className} aria-busy="true"><Skeleton className="h-48 w-full" /></div>;
+  if (quoteId && existing.error) return <ApiError error={existing.error} onRetry={() => void existing.refetch()} />;
+  if (quoteId && status !== "draft") return <p className={className}>This quote is {status}. Only drafts can be edited; use "Edit as draft" in the quote view to make a new draft from it.</p>;
+
+  const set = (p: Partial<Form>) => setForm({ ...form, ...p });
+  return (
+    <div className={className}>
+      <Card className="mb-4">
+        <CardHeader><CardTitle className="text-sm">Quote details</CardTitle></CardHeader>
+        <CardContent className="grid gap-3 sm:grid-cols-2">
+          <div className="space-y-1 sm:col-span-2"><Label htmlFor="qb-title">Title</Label><Input id="qb-title" value={form.title} onChange={(e) => set({ title: e.target.value })} /></div>
+          <div className="space-y-1"><Label htmlFor="qb-start">Contract start</Label><Input id="qb-start" type="date" value={form.contract_start_date} onChange={(e) => set({ contract_start_date: e.target.value })} /></div>
+          <div className="space-y-1"><Label htmlFor="qb-valid">Valid until</Label><Input id="qb-valid" type="date" value={form.valid_until} onChange={(e) => set({ valid_until: e.target.value })} /></div>
+          <div className="space-y-1">
+            <Label htmlFor="qb-terms">Payment terms</Label>
+            <select id="qb-terms" value={form.payment_terms} onChange={(e) => set({ payment_terms: e.target.value as PaymentTerms })} className="border-input bg-background h-9 w-full rounded-md border px-2 text-sm">
+              {PAYMENT_TERMS.map((t) => <option key={t} value={t}>{t.replace(/_/g, " ")}</option>)}
+            </select>
+          </div>
+          <div className="space-y-1"><Label htmlFor="qb-tax">Tax ({form.currency})</Label><Input id="qb-tax" type="number" min={0} step="0.01" value={form.tax} onChange={(e) => set({ tax: e.target.value })} /></div>
+          <div className="sm:col-span-2"><SignerPicker form={form} setForm={setForm} companyId={companyId} dealId={effectiveDeal || undefined} /></div>
+          <div className="space-y-1 sm:col-span-2"><Label htmlFor="qb-notes">Notes for the customer</Label><Textarea id="qb-notes" rows={2} value={form.notes} onChange={(e) => set({ notes: e.target.value })} /></div>
+        </CardContent>
+      </Card>
+
+      <Card className="mb-4">
+        <CardHeader><CardTitle className="text-sm">Line items</CardTitle></CardHeader>
+        <CardContent className="space-y-4">
+          <LinesTable lines={lines} setLines={setLines} currency={form.currency} />
+          <div className="text-right text-sm" data-testid="totals">
+            <div>Subtotal {money(sub, form.currency)}</div>
+            <div>Tax {money(taxCents, form.currency)}</div>
+            <div className="font-semibold">Total {money(sub + taxCents, form.currency)}</div>
+          </div>
+          <details>
+            <summary className="cursor-pointer text-sm font-medium">Add a product</summary>
+            <ProductPicker className="mt-3" currency={form.currency} onPick={(line) => setLines([...lines, line])} />
+          </details>
+        </CardContent>
+      </Card>
+
+      {save.error ? <ApiError error={save.error} title="Could not save the quote" /> : null}
+      {missing.length ? <p className="text-muted-foreground mb-2 text-sm" data-testid="missing">Still needed: {missing.join(", ")}.</p> : null}
+      <Button disabled={missing.length > 0} loading={save.loading} onClick={() => void save.mutate(undefined)}>{quoteId ? "Save draft" : "Create draft"}</Button>
+    </div>
+  );
+}

package/blocks/quotes/components/quote-list.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+/**
+ * QuoteList: quotes with a status filter, totals in the quote's own currency, and paging.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. listQuotes  GET /quotes?status&mashup_company_id&deal_id&page&limit  (read; `{ items, total, page, limit }`)
+ *
+ * Read-only: no billable, external or destructive call, so no confirmation. Pass `dealId` or `companyId` to show the
+ * quotes of one deal or company (for a tab on a deal page). `onOpen` receives the quote id for QuoteViewer.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { body, money, statusLabel, text } from "../lib/quotes";
+import type { Rec } from "../lib/quotes";
+
+export interface QuoteListProps {
+  dealId?: string;
+  companyId?: number;
+  onOpen?: (quoteId: string) => void;
+  onNew?: () => void;
+  pageSize?: number;
+  className?: string;
+}
+
+const STATUSES = ["", "draft", "sent", "viewed", "accepted", "declined", "voided", "expired", "archived"];
+
+export function QuoteList({ dealId, companyId, onOpen, onNew, pageSize = 25, className }: QuoteListProps) {
+  const [status, setStatus] = useState("");
+  const [page, setPage] = useState(1);
+  const q = useG8Query(
+    (signal) => g8Get("/quotes", { status: status || undefined, deal_id: dealId, mashup_company_id: companyId, page, limit: pageSize }, { signal }),
+    [status, dealId, companyId, page, pageSize],
+  );
+  const data = body(q.data);
+  const rows = (Array.isArray(data.items) ? data.items : []) as Rec[];
+  const total = typeof data.total === "number" ? data.total : rows.length;
+
+  return (
+    <div className={className}>
+      <div className="mb-3 flex items-center gap-2">
+        <select aria-label="Status" value={status} onChange={(e) => { setStatus(e.target.value); setPage(1); }} className="border-input bg-background h-9 rounded-md border px-2 text-sm">
+          {STATUSES.map((s) => <option key={s} value={s}>{s ? statusLabel(s) : "All statuses"}</option>)}
+        </select>
+        {onNew ? <Button className="ml-auto" onClick={onNew}>New quote</Button> : null}
+      </div>
+      {q.error ? <ApiError error={q.error} onRetry={() => void q.refetch()} /> : null}
+      {q.loading && !q.data ? <div className="space-y-2" aria-busy="true">{[0, 1, 2].map((i) => <Skeleton key={i} className="h-10 w-full" />)}</div> : !q.error && rows.length === 0 ? (
+        <EmptyState title="No quotes" description="Create a quote from a deal, pick products, and send it for signature." action={onNew ? <Button onClick={onNew}>New quote</Button> : undefined} />
+      ) : (
+        <Table>
+          <TableHeader><TableRow><TableHead>Quote</TableHead><TableHead>Status</TableHead><TableHead className="text-right">Total</TableHead><TableHead>Sent</TableHead></TableRow></TableHeader>
+          <TableBody>
+            {rows.map((r) => (
+              <TableRow key={text(r.id)}>
+                <TableCell><button type="button" className="font-medium hover:underline" onClick={() => onOpen?.(text(r.id))}>{text(r.title, "Untitled quote")}</button><div className="text-muted-foreground text-xs">{text(r.quote_number)}</div></TableCell>
+                <TableCell>{statusLabel(r.status)}</TableCell>
+                <TableCell className="text-right">{money(r.total, text(r.currency, "USD"))}</TableCell>
+                <TableCell>{r.sent_at ? new Date(text(r.sent_at)).toLocaleDateString() : ""}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+      <div className="mt-3 flex items-center justify-between text-sm">
+        <span className="text-muted-foreground">{total} quotes</span>
+        <div className="flex gap-2">
+          <Button size="sm" variant="outline" disabled={page === 1} onClick={() => setPage(page - 1)}>Previous</Button>
+          <Button size="sm" variant="outline" disabled={page * pageSize >= total} onClick={() => setPage(page + 1)}>Next</Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/blocks/quotes/components/quote-viewer.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+/**
+ * QuoteViewer: one quote read-only (line items, totals, terms, signer) with the actions its status allows and the
+ * e-signature status (SignatureStatus).
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getQuote         GET    /quotes/{id}                   (read; line items, totals in CENTS, envelope)
+ *   2. sendQuote        POST   /quotes/{id}/send              (external: emails the signer; also the resend for a sent quote)
+ *   3. editQuoteAsDraft POST   /quotes/{id}/edit-as-draft     (external; `sent` quotes only, returns `new_quote_id`: voids the sent copy, signing link dies, new draft)
+ *   4. duplicateQuote   POST   /quotes/{id}/duplicate         (external tier, but only copies into a new draft)
+ *   5. deleteQuote      DELETE /quotes/{id}                   (destructive; drafts only)
+ *
+ * Send, edit-as-draft and delete go through ConfirmSpendDialog. Duplicate creates an unsent draft and emails
+ * nobody, so it runs on one click (same reasoning as saving a draft in QuoteBuilder).
+ * Send needs a signer on the quote; without one the button explains what is missing instead of failing.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Textarea } from "@graph8/sdk/ui";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { asRec, body, lineTotal, linesFromQuote, money, statusLabel, text } from "../lib/quotes";
+import { SignatureStatus } from "./signature-status";
+
+export interface QuoteViewerProps {
+  quoteId: string;
+  /** Open the builder for this draft. */
+  onEdit?: (quoteId: string) => void;
+  /** Called with the id of a new draft (duplicate, edit-as-draft). */
+  onOpenQuote?: (quoteId: string) => void;
+  /** Called after the quote was deleted. */
+  onDeleted?: () => void;
+  className?: string;
+}
+
+type Pending = "send" | "edit" | "delete";
+
+export function QuoteViewer({ quoteId, onEdit, onOpenQuote, onDeleted, className }: QuoteViewerProps) {
+  const base = `/quotes/${encodeURIComponent(quoteId)}`;
+  const q = useG8Query((signal) => g8Get(base, undefined, { signal }), [quoteId]);
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [subject, setSubject] = useState("");
+  const [message, setMessage] = useState("");
+
+  const run = useG8Mutation(async (kind: Pending) => {
+    if (kind === "send") return body(await g8Post(`${base}/send`, { subject: subject || undefined, message: message || undefined }));
+    if (kind === "edit") return body(await g8Post(`${base}/edit-as-draft`));
+    return body(await g8Delete(base));
+  }, {
+    onSuccess: (res, kind) => {
+      setPending(null);
+      if (kind === "delete") return onDeleted?.();
+      if (kind === "edit" && text(res.new_quote_id)) return onOpenQuote?.(text(res.new_quote_id));
+      void q.refetch();
+    },
+  });
+  const copy = useG8Mutation(async () => body(await g8Post(`${base}/duplicate`)), { onSuccess: (res) => { if (text(res.id)) onOpenQuote?.(text(res.id)); } });
+
+  if (q.loading && !q.data) return <div className={className} aria-busy="true"><Skeleton className="h-48 w-full" /></div>;
+  if (q.error) return <ApiError error={q.error} onRetry={() => void q.refetch()} />;
+
+  const d = body(q.data);
+  const status = text(d.status, "draft");
+  const currency = text(d.currency, "USD");
+  const lines = linesFromQuote(d.line_items);
+  const hasSigner = Boolean(text(d.signer_contact_email ?? d.signer_email) || d.signer_contact_id);
+  const draft = status === "draft";
+  const sent = status === "sent" || status === "viewed";
+  const name = text(d.title, "this quote");
+
+  return (
+    <div className={className}>
+      <div className="mb-4 flex flex-wrap items-center gap-2">
+        <h2 className="text-lg font-semibold">{text(d.title, "Untitled quote")}</h2>
+        <span className="text-muted-foreground text-sm" data-testid="quote-status">{statusLabel(status)} · {text(d.quote_number)}</span>
+        <div className="ml-auto flex flex-wrap gap-2">
+          {draft ? <Button variant="outline" onClick={() => onEdit?.(quoteId)}>Edit</Button> : null}
+          {status === "sent" ? <Button variant="outline" onClick={() => setPending("edit")}>Edit as draft</Button> : null}
+          <Button variant="outline" loading={copy.loading} onClick={() => void copy.mutate(undefined)}>Duplicate</Button>
+          {draft ? <Button variant="ghost" onClick={() => setPending("delete")}>Delete</Button> : null}
+          {draft || sent ? <Button disabled={!hasSigner} title={hasSigner ? undefined : "Add a signer in the builder first"} onClick={() => setPending("send")}>{sent ? "Resend" : "Send for signature"}</Button> : null}
+        </div>
+      </div>
+      {run.error ? <ApiError error={run.error} title="That action failed" /> : null}
+      {copy.error ? <ApiError error={copy.error} title="Could not duplicate" /> : null}
+      {draft && !hasSigner ? <p className="text-muted-foreground mb-3 text-sm">Add a signer before sending.</p> : null}
+
+      <Card className="mb-4">
+        <CardHeader><CardTitle className="text-sm">Line items</CardTitle></CardHeader>
+        <CardContent>
+          <Table>
+            <TableHeader><TableRow><TableHead>Product</TableHead><TableHead>Qty</TableHead><TableHead>Unit</TableHead><TableHead>Discount</TableHead><TableHead className="text-right">Total</TableHead></TableRow></TableHeader>
+            <TableBody>
+              {lines.map((l) => (
+                <TableRow key={l.key}><TableCell>{l.product_name}</TableCell><TableCell>{l.quantity}</TableCell><TableCell>{money(l.unit_amount, currency)}</TableCell><TableCell>{l.discount_pct ? `${l.discount_pct}%` : ""}</TableCell><TableCell className="text-right">{money(lineTotal(l), currency)}</TableCell></TableRow>
+              ))}
+            </TableBody>
+          </Table>
+          <div className="mt-3 text-right text-sm" data-testid="saved-totals">
+            <div>Subtotal {money(d.subtotal, currency)}</div>
+            {Number(d.discount_amount) ? <div>Discount -{money(d.discount_amount, currency)}</div> : null}
+            <div>Tax {money(d.tax_amount, currency)}</div>
+            <div className="font-semibold">Total {money(d.total, currency)}</div>
+          </div>
+        </CardContent>
+      </Card>
+
+      <p className="text-muted-foreground mb-4 text-sm">
+        Signer: {text(d.signer_contact_name ?? d.signer_name) || "none"} {text(d.signer_contact_email ?? d.signer_email)} · Payment terms: {text(d.payment_terms).replace(/_/g, " ")}
+        {d.valid_until ? ` · Valid until ${text(d.valid_until).slice(0, 10)}` : ""}
+      </p>
+      <SignatureStatus quoteId={quoteId} quote={asRec(d)} onChanged={() => void q.refetch()} />
+
+      {pending === "send" ? (
+        <ConfirmSpendDialog open tier="external" title={`${sent ? "Resend" : "Send"} "${name}" for signature`} confirmLabel={sent ? "Resend" : "Send"} recipients={1} confirming={run.loading}
+          description={<div className="space-y-2 text-left"><p>Emails {text(d.signer_contact_email ?? d.signer_email)} a link to review and sign.</p>
+            <Input aria-label="Email subject" placeholder="Subject (optional)" value={subject} onChange={(e) => setSubject(e.target.value)} />
+            <Textarea aria-label="Email message" rows={3} placeholder="Message (optional)" value={message} onChange={(e) => setMessage(e.target.value)} /></div>}
+          onConfirm={() => void run.mutate("send")} onCancel={() => setPending(null)} />
+      ) : null}
+      {pending === "edit" ? (
+        <ConfirmSpendDialog open tier="external" title={`Edit "${name}" as a new draft`} confirmLabel="Void and edit" confirming={run.loading}
+          description="The signing link already sent stops working and a new draft is created. Send the draft again when it is ready." onConfirm={() => void run.mutate("edit")} onCancel={() => setPending(null)} />
+      ) : null}
+      {pending === "delete" ? (
+        <ConfirmSpendDialog open tier="destructive" title={`Delete "${name}"`} affected={1} confirming={run.loading}
+          description="The draft is removed. Sent quotes cannot be deleted." onConfirm={() => void run.mutate("delete")} onCancel={() => setPending(null)} />
+      ) : null}
+    </div>
+  );
+}

package/blocks/quotes/components/signature-status.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+/**
+ * SignatureStatus: where a quote's e-signature stands: sent, viewed, signed or declined, who still has to sign,
+ * and a log of views and signatures. Offers a reminder while the envelope is waiting.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getQuote         GET  /quotes/{id}                     (read; carries `envelope`, `signers` and audit events)
+ *   2. resendEnvelope   POST /envelopes/{envelope_id}/resend  (external: emails the signer again)
+ *
+ * The envelope only exists after the quote was sent. Pass `quote` (the object QuoteViewer already loaded) to skip
+ * the extra read. A reminder goes through ConfirmSpendDialog. The envelope id is `envelope.id` of the quote.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Skeleton } from "@graph8/sdk/ui";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { asRec, body, text } from "../lib/quotes";
+import type { Rec } from "../lib/quotes";
+
+export interface SignatureStatusProps {
+  quoteId: string;
+  /** The loaded quote detail, if the caller has it. */
+  quote?: Rec;
+  onChanged?: () => void;
+  className?: string;
+}
+
+const WAITING = ["sent", "viewed"];
+const when = (v: unknown) => (v ? new Date(text(v)).toLocaleString() : "");
+
+export function SignatureStatus({ quoteId, quote, onChanged, className }: SignatureStatusProps) {
+  const q = useG8Query((signal) => g8Get(`/quotes/${encodeURIComponent(quoteId)}`, undefined, { signal }), [quoteId], { enabled: !quote });
+  const [confirm, setConfirm] = useState(false);
+  const detail = quote ?? body(q.data);
+  const env = asRec(detail.envelope);
+  const envelopeId = text(env.id);
+  const remind = useG8Mutation(() => g8Post(`/envelopes/${encodeURIComponent(envelopeId)}/resend`), { onSuccess: () => { setConfirm(false); if (!quote) void q.refetch(); onChanged?.(); } });
+
+  if (!quote && q.loading && !q.data) return <div className={className} aria-busy="true"><Skeleton className="h-24 w-full" /></div>;
+  if (!quote && q.error) return <ApiError error={q.error} onRetry={() => void q.refetch()} />;
+  if (!envelopeId) return <p className={`text-muted-foreground text-sm ${className ?? ""}`}>Not sent for signature yet.</p>;
+
+  const status = text(env.status);
+  const signers = (Array.isArray(detail.signers) ? detail.signers : []) as Rec[];
+  const events = (Array.isArray(env.audit_events) ? env.audit_events : []) as Rec[];
+  return (
+    <Card className={className}>
+      <CardHeader><CardTitle className="text-sm">E-signature: <span data-testid="envelope-status" className="capitalize">{status}</span></CardTitle></CardHeader>
+      <CardContent className="space-y-3 text-sm">
+        <p className="text-muted-foreground">
+          {[env.sent_at && `Sent ${when(env.sent_at)}`, env.viewed_at && `viewed ${when(env.viewed_at)}`, env.signed_at && `signed ${when(env.signed_at)}`, env.declined_at && `declined ${when(env.declined_at)}`].filter(Boolean).join(", ")}
+        </p>
+        {env.decline_reason ? <p>Reason: {text(env.decline_reason)}</p> : null}
+        {typeof env.signer_count === "number" ? <p>{text(env.signed_count, "0")} of {text(env.signer_count)} signed</p> : null}
+        <ul className="space-y-1">
+          {signers.map((s) => <li key={text(s.id ?? s.email)}>{text(s.name) || text(s.email)} <span className="text-muted-foreground">({text(s.status)})</span></li>)}
+        </ul>
+        {events.length ? (
+          <details><summary className="cursor-pointer">Activity ({events.length})</summary>
+            <ul className="mt-1 space-y-1 text-xs">{events.map((e, i) => <li key={i}>{text(e.action)} · {when(e.created_at)}</li>)}</ul>
+          </details>
+        ) : null}
+        {remind.error ? <ApiError error={remind.error} title="Could not send the reminder" /> : null}
+        {WAITING.includes(status) ? <Button variant="outline" onClick={() => setConfirm(true)}>Send reminder</Button> : null}
+      </CardContent>
+      {confirm ? (
+        <ConfirmSpendDialog open tier="external" title="Remind the signer" confirmLabel="Send reminder" recipients={Math.max(1, signers.filter((s) => text(s.status) !== "signed").length)}
+          description="The signer gets the signing email again, with the same link." confirming={remind.loading} onConfirm={() => void remind.mutate(undefined)} onCancel={() => setConfirm(false)} />
+      ) : null}
+    </Card>
+  );
+}

package/blocks/quotes/hooks/use-debounced.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** The value, `ms` after it stopped changing. Search boxes use it so each keystroke is not a request. */
+export function useDebounced<T>(value: T, ms = 300): T {
+  const [settled, setSettled] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setSettled(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return settled;
+}