@graph8/sdk 0.362.0 → 0.373.0

package/blocks/pickers/components/contact-picker.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+/**
+ * ContactPicker: choose one or several contacts by name instead of typing contact ids. A searchable select over the
+ * organisation's contacts; it reports the contact (id, name, hint), so a screen can show who was chosen and send the id.
+ *
+ * SDK operations, in order:
+ *   1. GET /contacts?name|email&page&limit   (contacts.listContacts)   read - fetched only once the picker is opened
+ *
+ * Search: a first or last name (partial match); text containing "@" is looked up as a work email (exact match).
+ * Paged (usePickerPages): 25 contacts per page, "Show more" loads the next page and keeps the earlier ones; a new search
+ * starts over and an out-of-date response never lands. Locked emails and phones come back as "***" and are never shown.
+ * `multiple` keeps the panel open and shows the chosen contacts as removable chips.
+ */
+import { useState } from "react";
+import { X } from "lucide-react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { usePickerPages } from "../hooks/use-picker-pages";
+import { SearchPicker } from "./search-picker";
+
+/** One selectable contact. */
+export interface ContactOption {
+  id: number;
+  name: string;
+  /** Job title and company, or the work email: what tells two people with the same name apart. */
+  hint?: string;
+}
+
+export interface ContactPickerProps {
+  /** Single mode: the chosen contact (controlled). */
+  value?: ContactOption | null;
+  /** Single mode: called with the contact the person chose. */
+  onChange?: (contact: ContactOption) => void;
+  /** Several contacts: tick as many as needed. Use `selected` and `onSelectedChange`. */
+  multiple?: boolean;
+  selected?: ContactOption[];
+  onSelectedChange?: (contacts: ContactOption[]) => void;
+  /** Accessible name and trigger prefix. Default "Contact". */
+  label?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  /** Id of the trigger button, so a <label htmlFor> can name it. */
+  id?: string;
+  className?: string;
+}
+
+interface Row {
+  id?: number | null;
+  first_name?: string | null;
+  last_name?: string | null;
+  job_title?: string | null;
+  company_name?: string | null;
+  work_email?: string | null;
+}
+
+const PAGE = 25;
+const real = (v?: string | null): string => (v && !v.includes("*") ? v.trim() : "");
+
+/** A contacts-list row as a selectable option; null without an id. */
+export function toContactOption(r: Row): ContactOption | null {
+  if (r.id == null) return null;
+  const email = real(r.work_email);
+  const name = [real(r.first_name), real(r.last_name)].filter(Boolean).join(" ") || email || `Contact ${r.id}`;
+  const where = [real(r.job_title), real(r.company_name)].filter(Boolean).join(" at ");
+  return { id: r.id, name, hint: where || (email && email !== name ? email : undefined) };
+}
+
+export function ContactPicker(props: ContactPickerProps) {
+  const { value, onChange, multiple, selected = [], onSelectedChange, label = "Contact", placeholder, disabled, id, className } = props;
+  const [open, setOpen] = useState(false);
+  const pages = usePickerPages<ContactOption>(open, async (q, page, signal) => {
+    const filter = q.includes("@") ? { email: q } : { name: q || undefined };
+    const env = await g8Get("/contacts", { ...filter, page, limit: PAGE }, { signal });
+    const rows = ((env.data ?? []) as Row[]).map(toContactOption).filter((o): o is ContactOption => o !== null);
+    const has = (env.pagination as { has_next?: boolean } | undefined)?.has_next;
+    return { rows, hasNext: has ?? rows.length >= PAGE };
+  });
+  const { rows, q } = pages;
+  const byId = new Map(rows.map((r) => [String(r.id), r]));
+  const chosenKeys = new Set((multiple ? selected : value ? [value] : []).map((c) => String(c.id)));
+
+  const toggle = (key: string) => {
+    const c = byId.get(key) ?? [...selected, ...(value ? [value] : [])].find((x) => String(x.id) === key);
+    if (!c) return;
+    if (multiple) {
+      onSelectedChange?.(chosenKeys.has(key) ? selected.filter((x) => String(x.id) !== key) : [...selected, c]);
+      return;
+    }
+    setOpen(false);
+    pages.setSearch("");
+    onChange?.(c);
+  };
+  return (
+    <div className={`flex flex-col gap-2 ${className ?? ""}`}>
+      <SearchPicker
+        label={label}
+        id={id}
+        disabled={disabled}
+        placeholder={placeholder ?? (multiple ? "Add contacts" : undefined)}
+        searchPlaceholder="Search by name or work email"
+        triggerContent={!multiple && value ? <span>{value.name}</span> : undefined}
+        options={rows.map((r) => ({ key: String(r.id), label: r.name, hint: r.hint }))}
+        selectedKeys={chosenKeys}
+        onSelect={toggle}
+        search={pages.search}
+        onSearchChange={pages.setSearch}
+        open={open}
+        onOpenChange={setOpen}
+        loading={pages.loading}
+        error={pages.error}
+        onRetry={pages.refetch}
+        hasMore={pages.hasMore}
+        loadingMore={pages.loadingMore}
+        onLoadMore={pages.loadMore}
+        emptyText={q ? "No contact matches that search." : "No contacts yet."}
+      />
+      {multiple && selected.length > 0 ? (
+        <ul aria-label={`Chosen ${label.toLowerCase()}s`} className="flex flex-wrap gap-1">
+          {selected.map((c) => (
+            <li key={c.id} className="flex items-center gap-1 rounded-full border border-border bg-muted px-2 py-0.5 text-xs">
+              <span>{c.name}</span>
+              <button type="button" aria-label={`Remove ${c.name}`} className="text-muted-foreground hover:text-foreground" disabled={disabled} onClick={() => onSelectedChange?.(selected.filter((x) => x.id !== c.id))}>
+                <X className="size-3" aria-hidden />
+              </button>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  );
+}

package/blocks/pickers/components/member-picker.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+/**
+ * MemberPicker: choose a teammate by name instead of typing a user id. A searchable select over the organisation's
+ * team; the value it reports is the user id the API operations take (a dialer rep, a record owner, a role holder).
+ *
+ * SDK operations, in order:
+ *   1. GET /team-members?search&status&limit   (teamMembers.listTeamMembers)   read - fetched only once the picker is opened
+ *
+ * Paged: it loads 25 people and "Show more" asks for the next 25 (the search box narrows by name or email). People
+ * without a user id (a roster row that never signed in) are left out, because no operation could take them.
+ * A 403 (a key that may not read the team) shows a plain note instead of an error panel; the caller keeps its own
+ * fallback, usually the signed-in member from `useCurrentMember`.
+ */
+import { useState } from "react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useDebounced } from "../lib/use-debounced";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { memberRecordsOf, toMemberOption } from "../hooks/use-current-member";
+import type { MemberOption } from "../hooks/use-current-member";
+import { SearchPicker } from "./search-picker";
+
+export type { MemberOption } from "../hooks/use-current-member";
+
+export interface MemberPickerProps {
+  /** The selected user id (controlled). */
+  value?: string | null;
+  onChange: (member: MemberOption) => void;
+  /** What to show for `value` when that person is not on the loaded page (for example the current holder of a role). */
+  selectedName?: string | null;
+  /** Accessible name and trigger prefix. Default "Team member". */
+  label?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  /** Id of the trigger button, so a <label htmlFor> can name it. */
+  id?: string;
+  className?: string;
+}
+
+const PAGE = 25;
+
+export function MemberPicker({ value, onChange, selectedName, label = "Team member", placeholder, disabled, id, className }: MemberPickerProps) {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState("");
+  const [limit, setLimit] = useState(PAGE);
+  const [chosen, setChosen] = useState<MemberOption | null>(null);
+  const q = useDebounced(search.trim());
+  const query = useG8Query(
+    async (signal) => {
+      const env = await g8Get("/team-members", { search: q || undefined, status: "active", limit, offset: 0 }, { signal });
+      const records = memberRecordsOf(env);
+      // `raw` is what the API returned, before any filtering here: "Show more" asks for more when the page was full.
+      const active = records.filter((m) => !m.status || m.status === "active");
+      return { rows: active.map(toMemberOption).filter((o): o is MemberOption => o !== null), raw: records.length };
+    },
+    [q, limit],
+    { enabled: open },
+  );
+  const rows = query.data?.rows ?? [];
+  const status = (query.error as { status?: number } | undefined)?.status;
+  const forbidden = status === 403;
+  const shown = rows.find((m) => m.id === value) ?? (chosen?.id === value ? chosen : null);
+  const name = shown?.name ?? selectedName ?? value ?? null;
+
+  const pick = (id: string) => {
+    const member = rows.find((m) => m.id === id);
+    if (!member) return;
+    setChosen(member);
+    setOpen(false);
+    setSearch("");
+    onChange(member);
+  };
+  return (
+    <SearchPicker
+      label={label}
+      id={id}
+      className={className}
+      disabled={disabled}
+      placeholder={placeholder}
+      searchPlaceholder="Search by name or email"
+      triggerContent={name ? <span>{name}</span> : undefined}
+      options={rows.map((m) => ({ key: m.id, label: m.name, hint: m.email }))}
+      selectedKeys={new Set(value ? [value] : [])}
+      onSelect={pick}
+      search={search}
+      onSearchChange={(v) => { setSearch(v); setLimit(PAGE); }}
+      open={open}
+      onOpenChange={setOpen}
+      loading={query.loading}
+      error={forbidden ? undefined : query.error}
+      onRetry={() => void query.refetch()}
+      errorOverride={forbidden ? <p role="status" className="p-2 text-sm text-muted-foreground">This API key cannot read the team list.</p> : undefined}
+      hasMore={(query.data?.raw ?? 0) >= limit}
+      loadingMore={query.loading && rows.length > 0}
+      onLoadMore={() => setLimit((l) => l + PAGE)}
+      emptyText={q ? "Nobody matches that search." : "No team members yet."}
+    />
+  );
+}

package/blocks/pickers/components/search-picker.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+/**
+ * SearchPicker: the dropdown shell behind MemberPicker and ContactPicker. A trigger button opens a panel with a search
+ * box, a listbox of options, a "Show more" pager and the loading / empty / error states. It owns no data: the caller
+ * passes the options and the search text, so any lookup (team members, contacts, ...) reuses one accessible widget.
+ *
+ * It calls no API itself. Closing: Escape, a click outside, or (single mode) choosing an option. In `multiple` mode the
+ * panel stays open so several options can be ticked.
+ */
+import { useEffect, useRef } from "react";
+import type { ReactNode } from "react";
+import { Check, ChevronDown } from "lucide-react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+
+export interface SearchPickerOption {
+  key: string;
+  label: string;
+  /** A second muted line: a job title, an email. */
+  hint?: string | null;
+}
+
+export interface SearchPickerProps {
+  /** Accessible name of the whole control ("Team member", "Contact"). */
+  label: string;
+  /** What the closed trigger shows; defaults to the placeholder. */
+  triggerContent?: ReactNode;
+  placeholder?: string;
+  searchPlaceholder?: string;
+  options: SearchPickerOption[];
+  selectedKeys: ReadonlySet<string>;
+  onSelect: (key: string) => void;
+  search: string;
+  onSearchChange: (value: string) => void;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  loading?: boolean;
+  error?: unknown;
+  onRetry?: () => void;
+  hasMore?: boolean;
+  loadingMore?: boolean;
+  onLoadMore?: () => void;
+  /** Shown instead of the list when there is nothing to pick. */
+  emptyText?: string;
+  /** Replaces the error panel for an expected refusal (for example a 403 on the team list). */
+  errorOverride?: ReactNode;
+  disabled?: boolean;
+  /** Id of the trigger button, so a <label htmlFor> can name it. */
+  id?: string;
+  className?: string;
+}
+
+export function SearchPicker(props: SearchPickerProps) {
+  const { label, open, onOpenChange, options, selectedKeys, loading, error, disabled, className } = props;
+  const root = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!open) return;
+    const away = (e: MouseEvent) => { if (root.current && !root.current.contains(e.target as Node)) onOpenChange(false); };
+    document.addEventListener("mousedown", away);
+    return () => document.removeEventListener("mousedown", away);
+  }, [open, onOpenChange]);
+
+  const empty = !loading && !error && options.length === 0;
+  return (
+    <div ref={root} className={`relative inline-block min-w-48 ${className ?? ""}`} onKeyDown={(e) => { if (e.key === "Escape" && open) { e.stopPropagation(); onOpenChange(false); } }}>
+      <Button id={props.id} type="button" variant="outline" size="sm" className="w-full justify-between" disabled={disabled} aria-label={label} aria-haspopup="listbox" aria-expanded={open} onClick={() => onOpenChange(!open)}>
+        <span className="truncate">{props.triggerContent ?? <span className="text-muted-foreground">{props.placeholder ?? `Choose ${label.toLowerCase()}`}</span>}</span>
+        <ChevronDown className="ml-2 size-4 shrink-0 text-muted-foreground" aria-hidden />
+      </Button>
+      {open ? (
+        <div className="absolute left-0 z-50 mt-1 flex w-72 max-w-[90vw] flex-col gap-2 rounded-md border border-border bg-background p-2 shadow-md">
+          <Input autoFocus aria-label={`Search ${label.toLowerCase()}`} placeholder={props.searchPlaceholder ?? "Search"} value={props.search} onChange={(e) => props.onSearchChange(e.target.value)} />
+          {props.errorOverride ?? (error ? <ApiError error={error} title={`Could not load ${label.toLowerCase()} options`} onRetry={props.onRetry} /> : null)}
+          <ul role="listbox" aria-label={label} className="max-h-56 overflow-y-auto">
+            {loading && options.length === 0 ? <li className="p-2 text-sm text-muted-foreground">Loading...</li> : null}
+            {empty ? <li className="p-2 text-sm text-muted-foreground">{props.emptyText ?? "Nothing matches."}</li> : null}
+            {options.map((o) => {
+              const on = selectedKeys.has(o.key);
+              return (
+                <li key={o.key} role="none">
+                  <button type="button" role="option" aria-selected={on} className={`flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-left text-sm hover:bg-accent ${on ? "bg-accent font-medium" : ""}`} onClick={() => props.onSelect(o.key)}>
+                    <span className="flex min-w-0 flex-1 flex-col">
+                      <span className="truncate">{o.label}</span>
+                      {o.hint ? <span className="truncate text-xs text-muted-foreground">{o.hint}</span> : null}
+                    </span>
+                    {on ? <Check className="size-4 shrink-0" aria-hidden /> : null}
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+          {props.hasMore ? <Button type="button" variant="ghost" size="sm" loading={props.loadingMore} onClick={props.onLoadMore}>Show more</Button> : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/blocks/pickers/hooks/use-current-member.ts

@@ -0,0 +1,104 @@
+"use client";
+
+/**
+ * useCurrentMember: the signed-in team member, so no screen has to ask a person for their own user id.
+ *
+ * It is the ONE place that resolves "who am I" for a PERSONAL API key: the dialer's rep, a record owner default and
+ * CallContactButton all read it, so they cannot drift apart. An organisation key has no person: the API answers 403
+ * and `member` stays null (`forbidden: true`); callers then offer a MemberPicker instead of a text box.
+ *
+ * SDK operations, in order:
+ *   1. GET /team-members/me   (teamMembers.getMyTeamMember)   read - the roster record of the person who minted the key
+ *
+ * `userId` is the identity-provider user id (`propelauth_user_id`): the id the dialer's softphone credential, session
+ * drafts and record roles take. `email` is the matching rep email; both describe the same person.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+
+/** A roster record as the team-members endpoints answer it (the API may return more). */
+export interface TeamMemberRecord {
+  id?: string | null;
+  name?: string | null;
+  first_name?: string | null;
+  last_name?: string | null;
+  email?: string | null;
+  propelauth_user_id?: string | null;
+  status?: string | null;
+  role?: string | null;
+}
+
+/** One selectable person. `id` is the identity-provider user id, the value every id-taking operation wants. */
+export interface MemberOption {
+  id: string;
+  name: string;
+  email?: string | null;
+}
+
+/** The API envelope's `data`, or the value itself when it was already unwrapped. */
+export function unwrapData<T>(env: unknown): T {
+  const o = env as { data?: unknown } | null | undefined;
+  return (o && typeof o === "object" && "data" in o ? o.data : env) as T;
+}
+
+/** A roster record as a selectable person; null when it has no user id (it cannot be a rep or an owner). */
+export function toMemberOption(m: TeamMemberRecord | null | undefined): MemberOption | null {
+  const id = m?.propelauth_user_id;
+  if (!m || !id) return null;
+  const full = [m.first_name, m.last_name].filter(Boolean).join(" ");
+  return { id, name: m.name || full || m.email || id, email: m.email };
+}
+
+/** The list endpoints answer a bare array, or an object with `items` / `team_members`. */
+export function memberRecordsOf(env: unknown): TeamMemberRecord[] {
+  const inner = unwrapData<unknown>(env);
+  if (Array.isArray(inner)) return inner as TeamMemberRecord[];
+  const o = inner as { items?: unknown; team_members?: unknown } | null;
+  const list = o?.items ?? o?.team_members;
+  return Array.isArray(list) ? (list as TeamMemberRecord[]) : [];
+}
+
+/** The signed-in member's record, or null. A 403 (organisation key) and a 404 both read as "no person". */
+export async function fetchCurrentMember(signal?: AbortSignal): Promise<TeamMemberRecord | null> {
+  return unwrapData<TeamMemberRecord | null>(await g8Get("/team-members/me", undefined, { signal })) ?? null;
+}
+
+export interface UseCurrentMemberOptions {
+  /** Set false to hold the request (for example when the caller already passed a `userId`). Default true. */
+  enabled?: boolean;
+}
+
+export interface CurrentMember {
+  /** The signed-in person as a selectable option; null for an organisation key, while loading, or on failure. */
+  member: MemberOption | null;
+  /** `propelauth_user_id`: what the dialer, softphone and role assignments take. */
+  userId?: string;
+  email?: string;
+  name?: string;
+  /** The raw roster record (role, status ...), for callers that need more than the id. */
+  record: TeamMemberRecord | null;
+  loading: boolean;
+  /** The key is an organisation key: it has no person, so ask with a MemberPicker. */
+  forbidden: boolean;
+  /** Any failure other than the expected 403/404 of an organisation key. */
+  error: unknown;
+}
+
+export function useCurrentMember(options: UseCurrentMemberOptions = {}): CurrentMember {
+  const enabled = options.enabled ?? true;
+  const q = useG8Query((signal) => fetchCurrentMember(signal), [], { enabled });
+  const status = (q.error as { status?: number } | undefined)?.status;
+  const refusal = status === 403 || status === 404;
+  const record = enabled ? (q.data ?? null) : null;
+  const member = toMemberOption(record);
+  return {
+    member,
+    userId: member?.id,
+    email: record?.email ?? undefined,
+    name: member?.name,
+    record,
+    loading: enabled && q.loading && !q.data,
+    forbidden: enabled && status === 403,
+    error: enabled && q.error && !refusal ? q.error : undefined,
+  };
+}

package/blocks/pickers/hooks/use-picker-pages.ts

@@ -0,0 +1,73 @@
+"use client";
+
+/**
+ * usePickerPages: the paging + search engine behind ContactPicker and CompanyPicker.
+ *
+ * Page-number lists (`?page&limit`, `pagination.has_next`) with a search box: the text is debounced, a new search
+ * starts over from page 1, "load more" appends the next page to the ones already shown, and a response for an
+ * earlier search or page is dropped (latest wins). Nothing is fetched until `enabled` (the picker is open).
+ *
+ * It calls no operation itself: `fetchPage` does, so the caller's component declares the operation.
+ */
+import { useEffect, useState } from "react";
+import { useDebounced } from "../lib/use-debounced";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+
+export interface PickerPage<T> {
+  rows: T[];
+  hasNext: boolean;
+}
+
+export interface UsePickerPages<T> {
+  search: string;
+  setSearch: (value: string) => void;
+  /** The debounced, trimmed search text the loaded rows belong to. */
+  q: string;
+  rows: T[];
+  hasMore: boolean;
+  /** The first page of this search is loading and nothing is shown yet. */
+  loading: boolean;
+  /** A following page is loading. */
+  loadingMore: boolean;
+  error: unknown;
+  refetch: () => void;
+  loadMore: () => void;
+}
+
+interface Loaded<T> extends PickerPage<T> { q: string; page: number }
+
+export function usePickerPages<T>(
+  enabled: boolean,
+  fetchPage: (q: string, page: number, signal: AbortSignal) => Promise<PickerPage<T>>,
+): UsePickerPages<T> {
+  const [search, setSearchText] = useState("");
+  const [page, setPage] = useState({ q: "", n: 1 });
+  const [store, setStore] = useState<{ q: string | null; pages: T[][]; hasNext: boolean }>({ q: null, pages: [], hasNext: false });
+  const q = useDebounced(search.trim());
+  const n = page.q === q ? page.n : 1;
+  const query = useG8Query(
+    async (signal): Promise<Loaded<T>> => ({ ...(await fetchPage(q, n, signal)), q, page: n }),
+    [q, n],
+    { enabled },
+  );
+  useEffect(() => {
+    const d = query.data;
+    if (!d || d.q !== q || d.page !== n) return; // a response for an earlier search or page
+    setStore((s) => ({ q, pages: [...(s.q === q ? s.pages.slice(0, n - 1) : []), d.rows], hasNext: d.hasNext }));
+  }, [query.data, q, n]);
+
+  const current = store.q === q;
+  const rows = current ? store.pages.flat() : [];
+  return {
+    search,
+    setSearch: (value) => { setSearchText(value); setPage({ q: value.trim(), n: 1 }); },
+    q,
+    rows,
+    hasMore: current && store.hasNext,
+    loading: enabled && (query.loading || !current) && rows.length === 0,
+    loadingMore: query.loading && rows.length > 0,
+    error: query.error,
+    refetch: () => { void query.refetch(); },
+    loadMore: () => setPage({ q, n: n + 1 }),
+  };
+}

package/blocks/pickers/lib/use-debounced.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** `value`, but only after it has stopped changing for `ms`. The search box of every picker reads through this. */
+export function useDebounced<T>(value: T, ms = 250): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}

package/blocks/quotes/README.md

@@ -10,6 +10,8 @@ Install with `npx @graph8/sdk add quotes`.
 | `ProductPicker` | Quotable products (Stripe + manual) and their prices; returns a ready line item. |
 | `QuoteViewer` | One quote with totals and status-based actions: send/resend, edit as draft, duplicate, delete. |
 | `SignatureStatus` | Envelope state, signers, activity, reminder. |
+| `QuoteLifecycleActions` | PDF download, archive and unarchive, and for a sent quote expire, revoke and mark accepted. Each risky action is confirmed. |
+| `CreateQuoteFromDeal` | A "Create quote from this deal" button (builder in a side sheet, then the saved quote). Pass it to `DealsScreen`'s `renderQuoteActions`. |
 
 ## Screens
 
@@ -19,6 +21,12 @@ Install with `npx @graph8/sdk add quotes`.
 - Open a quote (deep link `?id=<quote id>`): line items, totals, signer, signature progress, with the actions its status
   allows. Send, resend, signature reminder and edit-as-draft are external and confirmed; delete is destructive and
   confirmed; duplicate and saving a draft email nobody.
+- **Lifecycle** (under the quote header): Download PDF (opens the link the API returns, or saves base64 content), Archive
+  and Unarchive (the list has "Include archived"), and for a sent or viewed quote **Expire** and **Revoke** (both final,
+  destructive confirms) and **Mark accepted**. Mark accepted raises an invoice with your billing provider, so it is an
+  external confirm that also requires an evidence type (signed offline, customer email, verbal authorization, payment
+  received) and a note. Use it only when the customer paid or signed outside the product.
+- The Deal tab of a quote offers "Create another quote" for the same deal.
 - **New quote** asks for the deal first (search by name, skipped when `dealId` is given because graph8 attaches every
   quote to a deal), then opens the builder (details, signer, line items from the quotable products, live totals).
 - Edit a draft from the viewer in a side sheet.
@@ -94,3 +102,8 @@ and **delete** (destructive). From code, never call `sendQuote` without the pers
 - `recipes/create-and-send-quote.ts`: Create a quote from quotable products and send it for signature
 - `recipes/track-quote-signature.ts`: Wait for a quote to be signed (or declined)
 - `recipes/revise-sent-quote.ts`: Change a quote that was already sent
+
+## Cross-block glue
+
+
+- `RecordQuotesTab` (`components/record-quotes-tab.tsx`): the quotes tied to a contact (as signer) or a company (`getContactQuotes` / `getCompanyQuotes`, unpaged), each opening `/quotes?id=<id>`. `extraDetailTabs` entry for ContactsScreen and CompaniesScreen.

package/blocks/quotes/block.json

@@ -8,25 +8,35 @@
     "draft builder with live totals and signer search",
     "quotable product picker (Stripe and manual products)",
     "send, resend and edit-as-draft behind confirms",
-    "e-signature status with reminder"
+    "e-signature status with reminder",
+    "quote lifecycle: PDF download, archive and unarchive, expire, revoke and mark accepted",
+    "create a quote from a deal anywhere with one button"
   ],
   "dependsOn": [
     "deals"
   ],
   "operations": [
-    "list_quotes_quotes_get",
-    "get_quote_quotes__quote_id__get",
-    "search_quote_contacts_quote_contacts_get",
+    "archive_quote_quotes__quote_id__archive_post",
     "create_quote_quotes_post",
-    "update_quote_quotes__quote_id__patch",
-    "list_quotable_products_quotable_products_get",
-    "send_quote_quotes__quote_id__send_post",
-    "edit_quote_as_draft_quotes__quote_id__edit_as_draft_post",
-    "duplicate_quote_quotes__quote_id__duplicate_post",
     "delete_quote_quotes__quote_id__delete",
-    "resend_envelope_envelopes__envelope_id__resend_post",
+    "duplicate_quote_quotes__quote_id__duplicate_post",
+    "edit_quote_as_draft_quotes__quote_id__edit_as_draft_post",
+    "expire_quote_quotes__quote_id__expire_post",
+    "get_company_quotes_companies__company_id__quotes_get",
+    "get_contact_quotes_contacts__contact_id__quotes_get",
+    "get_deal_deals__deal_id__get",
+    "get_quote_pdf_quotes__quote_id__pdf_get",
+    "get_quote_quotes__quote_id__get",
     "list_deals_deals_get",
-    "get_deal_deals__deal_id__get"
+    "list_quotable_products_quotable_products_get",
+    "list_quotes_quotes_get",
+    "mark_quote_accepted_quotes__quote_id__mark_accepted_post",
+    "resend_envelope_envelopes__envelope_id__resend_post",
+    "revoke_quote_quotes__quote_id__revoke_post",
+    "search_quote_contacts_quote_contacts_get",
+    "send_quote_quotes__quote_id__send_post",
+    "unarchive_quote_quotes__quote_id__unarchive_post",
+    "update_quote_quotes__quote_id__patch"
   ],
   "components": [
     {
@@ -100,8 +110,13 @@
       "name": "QuotesScreen",
       "file": "components/quotes-screen.tsx",
       "purpose": "Finished quotes product: status numbers, list, viewer with send and signature tracking, deal-first builder and draft editing.",
-      "operations": [],
-      "tiers": []
+      "operations": [
+        "list_deals_deals_get",
+        "list_quotes_quotes_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     },
     {
       "name": "ProductCatalog",
@@ -115,6 +130,43 @@
       "tiers": [
         "read"
       ]
+    },
+    {
+      "name": "QuoteLifecycleActions",
+      "file": "components/quote-lifecycle-actions.tsx",
+      "purpose": "After a quote exists: download the PDF, archive or unarchive, and for a sent quote expire, revoke or mark accepted (evidence required). Each risky action is confirmed.",
+      "operations": [
+        "archive_quote_quotes__quote_id__archive_post",
+        "expire_quote_quotes__quote_id__expire_post",
+        "get_quote_pdf_quotes__quote_id__pdf_get",
+        "mark_quote_accepted_quotes__quote_id__mark_accepted_post",
+        "revoke_quote_quotes__quote_id__revoke_post",
+        "unarchive_quote_quotes__quote_id__unarchive_post"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CreateQuoteFromDeal",
+      "file": "components/create-quote-from-deal.tsx",
+      "purpose": "A 'Create quote from this deal' button: builder in a side sheet, then the saved quote with its actions. Pass it to the deals screen's renderQuoteActions.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "RecordQuotesTab",
+      "file": "components/record-quotes-tab.tsx",
+      "purpose": "The quotes tied to one contact (as signer) or one company, each opening in the quotes screen; an extraDetailTabs entry for ContactsScreen and CompaniesScreen.",
+      "operations": [
+        "get_contact_quotes_contacts__contact_id__quotes_get",
+        "get_company_quotes_companies__company_id__quotes_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [