@graph8/sdk 0.362.0 → 0.370.0

package/README.md

@@ -8,7 +8,7 @@ The most comprehensive GTM SDK. One `npm install`. Every graph8 capability.
 > operation in [`docs/api/`](docs/api/README.md). It ships with the package, so it matches this version.
 > Run `npx @graph8/sdk init-agent` to point Claude Code, Codex and Cursor in your project at it automatically.
 >
-> Blocks (copy-in components and hooks per feature): `npx @graph8/sdk list`, `search <text>`, `add <block>[/<Component>]`, `create <stack> <dir>` (a whole Next.js app: `npx @graph8/sdk create starter my-app`), and `doctor` to check your key, scopes and subscription. Each takes `--help`.
+> Blocks (copy-in components and hooks per feature): `npx @graph8/sdk list`, `search <text>`, `add <block>[/<Component>]` (`--routes` also wires its screens as routes and nav entries in a created app), `create <stack> <dir>` (a whole Next.js app: `npx @graph8/sdk create starter my-app`), and `doctor` to check your key, scopes and subscription. Each takes `--help`.
 
 ## Install
 
@@ -496,15 +496,19 @@ npx @graph8/sdk create mailchimp my-app   # then: cd my-app && cp .env.local.exa
 | Stack | Screens |
 |---|---|
 | `starter` | An empty app: proxy, shell and one landing page |
-| `mailchimp` | Contacts, companies, forms, submissions, lists, suppressions, newsletter, subscribers, nurture |
-| `clay` | Contacts, companies, lists, suppressions, prospect search, bulk enrichment, workbench |
-| `6sense` | Contacts, companies, intent feed, website visitors, competitor tracker |
-| `intercom` | Contacts, companies, web chat conversations, mailboxes, AI inbox, AI agents |
-| `outreach` | Contacts, companies, lists, mailboxes, sequences, inbox, dialer, call log, meetings, analytics |
-| `apollo` | Outreach's screens plus prospect search, enrichment, intent, visitors, deals and integrations |
-| `gong` | Contacts, companies, lists, dialer, call log, meetings, coaching feed, analytics |
-| `salesforce` | Contacts, companies, custom objects, lists, lifecycle, deals, quotes, analytics, workflows, copilot, integrations |
-| `hubspot` | The full CRM and marketing suite: forms, newsletter, nurture, web chat, sequences, inbox, pages, lifecycle, deals, quotes, workflows |
+| `mailchimp` | Newsletter, nurture, forms, contacts, companies, tasks, lists, suppressions |
+| `clay` | Prospect search, workbench, enrichment, lists, contacts, companies, tasks, suppressions |
+| `6sense` | Intent, visitors, competitors, companies, contacts, tasks |
+| `intercom` | Inbox, web chat conversations, contacts, companies, tasks, AI agents, mailboxes |
+| `calendly` | Meetings and scheduling (event types, availability, booking pages) over contacts, companies and tasks |
+| `pipedrive` | Analytics, deals, quotes, contacts, companies, inbox, meetings, scheduling, tasks and mailboxes; deals and quotes open each other, replies can start a deal |
+| `outreach` | Analytics, contacts, companies, lists, sequences, campaigns, inbox, dialer, call log, meetings, scheduling, tasks, mailboxes, suppressions |
+| `apollo` | Outreach's screens plus prospect search, enrichment, intent, visitors, deals and integrations; contacts get Enrich, Add to sequence and a Deals tab |
+| `gong` | Analytics, call log, coaching, dialer, meetings, scheduling, contacts, companies, tasks, lists, suppressions |
+| `salesforce` | Analytics, contacts, companies, lists, deals, quotes, lifecycle, tasks, workflows, copilot, custom objects, suppressions, integrations |
+| `hubspot` | The full CRM and marketing suite: inbox, web chat, sequences, campaigns, newsletter, nurture, forms, pages, social, ads, deals, quotes, lifecycle, workflows |
+| `zoominfo` | Prospect search, enrichment, intent and visitors over contacts, companies and lists |
+| `hootsuite` | Social posts, ads, landing pages and analytics over your contacts and lists |
 
 Every available stack is proven by `npm run build && npm run e2e:create -- <stack>`, which packs the SDK, scaffolds the app with the built CLI, installs it and requires `next build` to pass. More stacks appear here as their blocks land; `create` refuses a stack that is not available yet.
 

package/blocks/_foundation/README.md

@@ -8,7 +8,9 @@ Shared base every other block depends on. Install it first (the CLI does it for
 |---|---|
 | `lib/g8-client.ts` | Browser caller: `g8Get/g8Post/g8Put/g8Patch/g8Delete` -> your own `/api/g8/...` proxy. No API key. Returns the API envelope `{ data, pagination? }`, throws `G8Error`. |
 | `server/proxy.ts` | `createG8Proxy(config)`: the logic of the proxy (forwarding, allowlist, `authorize` hook). |
-| `server/route.ts` | Installs as `app/api/g8/[...path]/route.ts` and mounts the proxy. |
+| `server/route.ts` | Installs as `app/api/g8/[...path]/route.ts` and mounts the proxy. `allowedPrefixes` is generated from the installed blocks' operations; local preview is on. |
+| `server/local-key.ts`, `server/connect.ts`, `server/connect-route.ts` | Local preview key store: `app/api/g8-connect/route.ts` checks a pasted key (GET /me) and keeps it in `.g8/local-key` on the server. 404 in production. |
+| `components/connect-graph8.tsx` | `ConnectGraph8Panel` + `G8ConnectGate`: the first-run Connect graph8 panel in `next dev`; a no-op in production. |
 | `hooks/use-g8-query.ts` | `useG8Query(fetcher, deps)` -> `{ data, error, loading, refetch }`. Latest request wins. |
 | `hooks/use-g8-mutation.ts` | `useG8Mutation(fn)` -> `{ mutate, mutateAsync, data, error, loading, reset }`. |
 | `hooks/use-paginated.ts` | `usePaginated(fetchPage, deps)` -> `{ items, hasMore, loadMore, reload, loading, loadingMore, error }`. Follows `pagination.next_cursor`. |
@@ -18,6 +20,7 @@ Shared base every other block depends on. Install it first (the CLI does it for
 | `components/empty-state.tsx` | `EmptyState`: empty list with a first step. |
 | `components/screen/*.tsx` | The **screen kit** (below): `ScreenLayout`, `StatStrip`, `SplitView`, `DetailPanel`, `Toolbar`, `StatusPill`, `EntityAvatar`, `SectionCard`, `FormSheet`, `KeyValueList`, `Sparkline`, `BarList`, `TimeSeriesChart`. Barrel: `@/g8/components/screen`. |
 | `hooks/use-url-state.ts` | `useUrlState(key, default = "")` -> `[value, set]`. One string in the URL query as state (replaceState + popstate, SSR-safe). |
+| `lib/g8-cache.ts` | The shared query cache behind the hooks' optional `key`: dedupe, stale-while-revalidate, focus/reconnect refresh, `invalidate(prefix)`, `setQueryData`, bounded LRU. See "Query cache" below. |
 
 ## Flow of every call
 
@@ -30,6 +33,48 @@ Shared base every other block depends on. Install it first (the CLI does it for
 Ids that pass between calls always come from a previous response (a list's `id` into the next call's
 path). Never invent one.
 
+## Query cache (opt in with a `key`)
+
+Every hook works exactly as before without a key. Pass one and the data lives in one app-wide cache
+(`lib/g8-cache.ts`, no dependencies):
+
+```ts
+const contacts = useG8Query(
+  (signal) => g8Get("/contacts", { page, limit: 25, q }, { signal }),
+  [page, q],
+  { key: ["contacts", "list", { page, q }] },          // name EVERY input the fetcher reads
+);
+const contact = useG8Query((s) => g8Get(`/contacts/${id}`, {}, { signal: s }), [id], { key: ["contacts", "detail", id] });
+const save = useG8Mutation((v: Patch) => g8Patch(`/contacts/${v.id}`, v), { invalidates: ["contacts"] });
+```
+
+- **Dedupe**: components asking for the same key share one request and one answer.
+- **Stale-while-revalidate**: a cached key renders instantly on mount (no skeleton) and refreshes in the
+  background once older than `staleTime` (default 0). Use `staleTime: 60_000` for data that rarely changes
+  (custom-field schemas, pipelines, dispositions).
+- **Focus/reconnect**: watched keys refresh when the window regains focus or the network returns, at most
+  once per 5 s per key (`refetchOnFocus: false` opts out; `usePaginated` defaults to false so a scroll is kept).
+- **Invalidation**: `invalidate("contacts")` (or a mutation's `invalidates: ["contacts"]`) marks every key
+  starting with `"contacts"` stale; keys on screen refetch now, a request started before the write is
+  superseded, the rest refetch when next shown. Prefixes match whole parts (`"deals"` never matches `"deals-x"`).
+- **Writes into the cache**: `setQueryData(key, value | old => new)`; `useG8Mutation(fn, { optimistic: { prefix, update } })`
+  changes cached data before the request and puts it back if the write fails.
+- **Memory**: at most 200 keys (LRU); a key nobody watches is dropped after 5 minutes; requests abort when
+  their LAST subscriber unmounts.
+- **`placeholderData`**: show a list row while the full record loads (`isPlaceholderData: true`). Never seed
+  an edit form from it (edit-before-load PATCHes blanks over real values): enable Edit only when
+  `!isPlaceholderData && !loading`.
+- **SSR**: nothing is cached on the server; hooks render their initial state and fetch after hydration.
+- **Keys are JSON-like**: strings, numbers, booleans, null, arrays, plain objects and Dates. A `Map`, `Set`,
+  `URLSearchParams` or class instance throws (it would otherwise collide with every other one).
+- **Sign-out and org switch**: the cache is one per page and is not keyed by user or org. Call
+  `g8QueryCache.clear()` on sign-out or org switch, and add the org to your keys if you pass `targetOrgId`,
+  so one org's cached rows are never shown to another.
+
+Key convention used by the blocks: `[area, "list" | "detail" | <sub-resource>, ...inputs]`, area = the API
+path's first segment (`contacts`, `companies`, `deals`, `sequences`, `lists`, `inbox`, `tasks`...), so a write
+to an area invalidates that area with one prefix.
+
 ## Tiers: when to confirm
 
 Every operation has a tier (`read`, `write`, `billable`, `external`, `destructive`); each component's
@@ -62,6 +107,21 @@ The proxy therefore **refuses every request (500) until you configure it**:
 5. Local prototypes only: `dangerouslyAllowUnauthenticated: true` and `dangerouslyAllowAllPaths: true`
    switch the two gates off. Never ship them.
 
+### Local preview (apps made by `graph8-sdk create`)
+
+Created apps run before they have sign-in: the route sets `localPreview: true`. While `authorize` is unset the
+proxy answers a request only if NODE_ENV is not `production` AND it comes from this machine: Host is
+`localhost`, `127.0.0.1` or `[::1]` (blocks DNS rebinding), the browser's `Sec-Fetch-Site`/`Origin` say it is
+the app's own page (blocks other sites in the same browser), and no forwarding proxy names a remote client
+(blocks tunnels). `npm run dev` listens on 127.0.0.1, because a machine on your network could forge those
+headers. Other hosts get 403; a production build gets 500 until `authorize` is set. Once `authorize` is set,
+`localPreview` does nothing.
+
+The key comes from `G8_API_KEY` (env, `.env.local`) or, in local preview only, the key pasted in the
+Connect graph8 panel, which the server checks against `GET /me` and stores in `.g8/local-key` (0600, git-ignored).
+`npx @graph8/sdk doctor --production` fails until the route is safe to deploy;
+`npx @graph8/sdk doctor --fix-prefixes` regenerates `allowedPrefixes` after you add or remove blocks.
+
 What the proxy does on its own: rejects `..`, encoded slashes and empty segments (400); forwards only
 `content-type`, `accept`, `accept-language` and `idempotency-key` (never the browser's cookies or
 `Authorization`); strips hop-by-hop headers, `set-cookie` and `location` from the response; does not follow
@@ -91,6 +151,9 @@ for meaning, no entrance animations, light and dark through the tokens.
 | `Sparkline` | `sparkline` | Tiny SVG trend for tiles and cells. `data: number[]`, optional `tone`. |
 | `BarList` | `bar-list` | Ranked rows with a proportional ink bar; `href` makes a row a link. |
 | `TimeSeriesChart` | `time-series-chart` | `data`, `xKey`, `series: { key, label?, tone? }[]`, `kind` line, area, bar. Needs the `recharts` peer. `tone: "prior"` is the dashed comparison. |
+| `useRowActivation` | `hooks/use-row-activation` | `<TableRow {...rowActivationProps(() => open(row.id))}>` (inside `.map()`; `useRowActivation` is the hook form): the whole row is focusable, Enter/Space/click open it, nested checkboxes, buttons and links keep their own behaviour. Pass `{ role: "button" }` for a non-table row. |
+| `RecordLink` | `components/screen/record-link` | A record name as a real `<a href="?id=X">`: plain click opens in place (URL state), Cmd/Ctrl/middle-click opens a new tab on the same record. `full` adds `view=full`. |
+| `plural`, `pluralWord` | `lib/plural` | `plural(1, "contact")` -> "1 contact", `plural(3, "company", "companies")` -> "3 companies". Never hand-roll `=== 1 ? "" : "s"`. |
 | `useUrlState` | `hooks/use-url-state` | `const [id, setId] = useUrlState("id")`; `setId(null)` removes it; `{ push: true }` adds a history entry. |
 
 A finished list screen, start to end:

package/blocks/_foundation/block.json

@@ -7,10 +7,14 @@
     "browser-safe API calls via a server proxy",
     "query, mutation, pagination and job-polling hooks",
     "spend/send/delete confirmation dialog",
-    "screen kit: layout, stats, split view, detail panel, toolbar, status pills, avatars, cards, form sheet, charts"
+    "screen kit: layout, stats, split view, detail panel, toolbar, status pills, avatars, cards, form sheet, charts",
+    "local preview: a Connect graph8 screen stores the server's key for `next dev`; generated allowedPrefixes",
+    "white-label: BrandProvider + useBrand give every block's copy and link-outs your platform name and app URL (default graph8)"
   ],
   "dependsOn": [],
-  "operations": [],
+  "operations": [
+    "describe_current_key_me_get"
+  ],
   "components": [
     {
       "name": "ConfirmSpendDialog",
@@ -19,6 +23,13 @@
       "operations": [],
       "tiers": []
     },
+    {
+      "name": "AskButton",
+      "file": "components/confirmed-action.tsx",
+      "purpose": "useConfirmAction + AskButton: a button asks, one ConfirmSpendDialog per screen confirms, then the write runs (Cancel is ignored while it runs).",
+      "operations": [],
+      "tiers": []
+    },
     {
       "name": "ApiError",
       "file": "components/api-error.tsx",
@@ -123,23 +134,44 @@
       "purpose": "Line, area or bar chart over time on recharts: ink series, tones only for meaning, dashed prior period, hairline grid.",
       "operations": [],
       "tiers": []
+    },
+    {
+      "name": "RecordLink",
+      "file": "components/screen/record-link.tsx",
+      "purpose": "A record's name as a real <a href=\"?id=X\">: a plain click opens it in place (URL state), Cmd/Ctrl/middle-click opens a new tab on the same record.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "ConnectGraph8Panel",
+      "file": "components/connect-graph8.tsx",
+      "purpose": "Local preview only: paste a graph8 API key, the server checks it (GET /me) and stores it in .g8/local-key, never in the browser; replace or remove it. G8ConnectGate shows it until a key is connected and is a no-op in production.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "BrandProvider",
+      "file": "components/brand-provider.tsx",
+      "purpose": "White-label context: the app's name, logo, and what the platform is called and where it lives, for every block's copy and link-outs. Fields left out stay graph8's.",
+      "operations": [],
+      "tiers": []
     }
   ],
   "hooks": [
     {
       "name": "useG8Query",
       "file": "hooks/use-g8-query.ts",
-      "purpose": "Load data with loading/error/data, an out-of-order guard and refetch."
+      "purpose": "Load data with loading/error/data, an out-of-order guard and refetch. Optional `key` joins the shared cache (dedupe, stale-while-revalidate, focus refresh, invalidation)."
     },
     {
       "name": "useG8Mutation",
       "file": "hooks/use-g8-mutation.ts",
-      "purpose": "Run a write with loading/error state and success/error callbacks."
+      "purpose": "Run a write with loading/error state and success/error callbacks. Optional `invalidates` refreshes cached keys; optional `optimistic` update with rollback."
     },
     {
       "name": "usePaginated",
       "file": "hooks/use-paginated.ts",
-      "purpose": "Cursor pagination over the API envelope (pagination.next_cursor) with load-more and reload."
+      "purpose": "Cursor pagination over the API envelope (pagination.next_cursor) with load-more and reload. Optional `key` caches the loaded pages."
     },
     {
       "name": "useJobPoll",
@@ -150,6 +182,16 @@
       "name": "useUrlState",
       "file": "hooks/use-url-state.ts",
       "purpose": "One string in the URL query as state (replaceState + popstate, SSR-safe, no next/navigation): the open record, tab or search survives reload and Back."
+    },
+    {
+      "name": "useRowActivation",
+      "file": "hooks/use-row-activation.ts",
+      "purpose": "Props that make a whole list row focusable and openable with Enter/Space and click, leaving nested checkboxes, buttons and links alone. rowActivationProps is the same as a plain function for use inside .map()."
+    },
+    {
+      "name": "useBrand",
+      "file": "hooks/use-brand.ts",
+      "purpose": "The current brand ({ name, appUrl, linkLabel, logo }) from the nearest BrandProvider, else graph8's defaults; brandUrl(brand, path) builds a link-out."
     }
   ],
   "lib": [
@@ -157,9 +199,25 @@
       "file": "lib/g8-client.ts",
       "purpose": "Browser caller for the app's own /api/g8 proxy. Holds no key, returns the SDK envelope, throws G8Error."
     },
+    {
+      "file": "components/screen/time-series-chart-recharts.tsx",
+      "purpose": "The recharts implementation of TimeSeriesChart, code-split: TimeSeriesChart loads it on first render, so pages without a chart never download recharts."
+    },
+    {
+      "file": "components/screen/time-series-format.ts",
+      "purpose": "TimeSeriesChart props, series type and axis formatters (defaultFormatX/defaultFormatY), with no recharts import."
+    },
+    {
+      "file": "lib/g8-cache.ts",
+      "purpose": "Shared query cache behind the hooks' optional `key`: one in-flight request per key, stale-while-revalidate, focus/reconnect refresh, invalidate(prefix), setQueryData, optimistic writes, bounded LRU (200) with GC."
+    },
     {
       "file": "components/screen/index.ts",
       "purpose": "Barrel for the screen kit: import every part from @/g8/components/screen."
+    },
+    {
+      "file": "lib/plural.ts",
+      "purpose": "plural(n, 'contact') -> '1 contact' / '2 contacts' (and pluralWord): one correct plural helper for titles, counts and bulk dialogs."
     }
   ],
   "server": [
@@ -168,10 +226,25 @@
       "purpose": "createG8Proxy(): forwards browser calls to the graph8 API with the server-side key, a required path allowlist and authorize hook (it refuses to run without them) and a server-side org hook.",
       "target": "g8/server/proxy.ts"
     },
+    {
+      "file": "server/local-key.ts",
+      "purpose": "Node only: the local-preview key file (.g8/local-key, 0600, self-gitignored) and resolveApiKey() (environment first, then the file outside production).",
+      "target": "g8/server/local-key.ts"
+    },
+    {
+      "file": "server/connect.ts",
+      "purpose": "createG8ConnectRoute(): GET status, POST a key (checked with GET /me), DELETE it; answers only next dev requests from this machine, 404 in production.",
+      "target": "g8/server/connect.ts"
+    },
     {
       "file": "server/route.ts",
       "purpose": "The Next.js App Router catch-all route that mounts the proxy.",
       "target": "app/api/g8/[...path]/route.ts"
+    },
+    {
+      "file": "server/connect-route.ts",
+      "purpose": "The Next.js route behind the Connect graph8 screen.",
+      "target": "app/api/g8-connect/route.ts"
     }
   ],
   "recipes": [
@@ -210,7 +283,7 @@
     },
     {
       "decision": "How the proxy knows the caller is a signed-in user of the app",
-      "default": "None: the route refuses every request until `authorize` is set",
+      "default": "Local preview: until `authorize` is set the route answers only `next dev` requests from this machine; a production build refuses every request until `authorize` is set",
       "askHuman": true
     },
     {

package/blocks/_foundation/components/api-error.tsx

@@ -1,8 +1,9 @@
 "use client";
 
-import { G8Error } from "@graph8/sdk";
+import { G8Error } from "@graph8/sdk/errors";
 import { CircleAlert } from "lucide-react";
 import { Button, cn } from "@graph8/sdk/ui";
+import { DEFAULT_BRAND, useBrand } from "../hooks/use-brand";
 
 export interface ApiErrorProps {
   error: unknown;
@@ -23,22 +24,22 @@ interface FieldError {
 }
 
 /** A readable one-line reason for any thrown value. 422 field errors are listed. */
-export function describeError(error: unknown): { message: string; fields: string[]; status?: number; requestId?: string } {
+export function describeError(error: unknown, platform: string = DEFAULT_BRAND.linkLabel): { message: string; fields: string[]; status?: number; requestId?: string } {
   if (error instanceof G8Error) {
     const fields = Array.isArray(error.detail)
       ? (error.detail as FieldError[]).map((f) => `${(f.loc ?? []).filter((p) => p !== "body").join(".")}: ${f.msg ?? ""}`.trim())
       : [];
     const message =
-      typeof error.detail === "string" ? error.detail : fields.length ? "Some fields are invalid." : explain(error);
+      typeof error.detail === "string" ? error.detail : fields.length ? "Some fields are invalid." : explain(error, platform);
     return { message, fields, status: error.status, requestId: error.requestId };
   }
   return { message: error instanceof Error ? error.message : "Something went wrong.", fields: [] };
 }
 
-function explain(error: G8Error): string {
-  if (error.status === 401) return "Your session with graph8 is not valid. Check the server API key.";
+function explain(error: G8Error, platform: string): string {
+  if (error.status === 401) return `Your session with ${platform} is not valid. Check the server API key.`;
   if (error.status === 403) return "This API key is not allowed to do that (missing scope, or the proxy blocked the path).";
-  if (error.status === 429) return "graph8 is rate limiting requests. Wait a moment and retry.";
+  if (error.status === 429) return `${platform} is rate limiting requests. Wait a moment and retry.`;
   if (error.status === 0) return "Could not reach the server. Check your connection.";
   return error.message;
 }
@@ -48,8 +49,9 @@ function explain(error: G8Error): string {
  * is an error with Retry, never an empty list. Ember is reserved for this: errors and alerts.
  */
 export function ApiError({ error, title = "Something went wrong", onRetry, className, compact, retryLabel = "Retry", actions }: ApiErrorProps) {
+  const brand = useBrand();
   if (error == null) return null;
-  const info = describeError(error);
+  const info = describeError(error, brand.linkLabel);
 
   if (compact) {
     return (

package/blocks/_foundation/components/brand-provider.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+/**
+ * Wraps the app so every block shows YOUR brand: the platform's name in copy and link-outs, and where those links
+ * go. A created app renders it in components/app-shell.tsx from `g8.config.ts`:
+ *
+ *   <BrandProvider brand={brand}>{children}</BrandProvider>
+ *
+ * Fields left out keep graph8's defaults (see hooks/use-brand.ts). No API calls.
+ */
+
+import { useMemo, type ReactNode } from "react";
+import { BrandContext, resolveBrand, type BrandConfig } from "../hooks/use-brand";
+
+export interface BrandProviderProps {
+  brand?: Partial<BrandConfig> | null;
+  children: ReactNode;
+}
+
+export function BrandProvider({ brand, children }: BrandProviderProps) {
+  const value = useMemo(() => resolveBrand(brand), [brand?.name, brand?.appUrl, brand?.linkLabel, brand?.logo]); // eslint-disable-line react-hooks/exhaustive-deps
+  return <BrandContext.Provider value={value}>{children}</BrandContext.Provider>;
+}

package/blocks/_foundation/components/confirmed-action.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+/**
+ * useConfirmAction + AskButton (foundation, shared by every block's record detail): the pattern detail screens use for every write. A button calls `ask(config)`; the screen
+ * renders ONE `<ConfirmSpendDialog {...dialog} />` (so the confirmation is visible in the screen's own source), the person confirms,
+ * then `config.run()` executes and the failure, if any, is shown in `failure`.
+ *
+ * SDK operations: none of its own; `run` is whatever the caller passes. `tolerateStatus` lists HTTP statuses that count as done
+ * (a delete answering 404); `mapError` can turn a thrown error into a clearer one (return null to treat it as done).
+ */
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Button } from "@graph8/sdk/ui";
+import type { ConfirmTier } from "@/g8/components/confirm-spend-dialog";
+
+export interface ConfirmActionConfig {
+  tier: ConfirmTier;
+  title: string;
+  description?: ReactNode;
+  confirmLabel?: string;
+  estimatedCredits?: number;
+  recipients?: number;
+  affected?: number;
+  tolerateStatus?: number[];
+  mapError?: (error: unknown) => unknown;
+  run: () => Promise<unknown>;
+  onDone?: () => void;
+}
+
+export interface AskButtonProps extends ConfirmActionConfig {
+  ask: (config: ConfirmActionConfig) => void;
+  label: string;
+  variant?: "default" | "outline" | "ghost";
+  disabled?: boolean;
+}
+
+export function useConfirmAction() {
+  const [cfg, setCfg] = useState<ConfirmActionConfig | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [failure, setFailure] = useState<unknown>(null);
+
+  const go = async () => {
+    if (!cfg) return;
+    setBusy(true);
+    setFailure(null);
+    try {
+      await cfg.run();
+      cfg.onDone?.();
+    } catch (err) {
+      const status = (err as { status?: number })?.status;
+      if (status != null && cfg.tolerateStatus?.includes(status)) cfg.onDone?.();
+      else {
+        const shown = cfg.mapError ? cfg.mapError(err) : err;
+        if (shown == null) cfg.onDone?.();
+        else setFailure(shown);
+      }
+    } finally {
+      setBusy(false);
+      setCfg(null);
+    }
+  };
+
+  return {
+    ask: (config: ConfirmActionConfig) => setCfg(config),
+    busy,
+    failure,
+    dialog: {
+      open: cfg != null,
+      tier: cfg?.tier ?? ("external" as ConfirmTier),
+      title: cfg?.title ?? "",
+      description: cfg?.description,
+      estimatedCredits: cfg?.estimatedCredits,
+      recipients: cfg?.recipients,
+      affected: cfg?.affected,
+      confirmLabel: cfg?.confirmLabel,
+      confirming: busy,
+      onConfirm: () => void go(),
+      // While the write is running, Cancel does nothing: closing then would hide a write that still lands.
+      onCancel: () => { if (!busy) setCfg(null); },
+    },
+  };
+}
+
+export function AskButton({ ask, label, variant = "outline", disabled, ...config }: AskButtonProps) {
+  return (
+    <Button size="sm" variant={variant} disabled={disabled} onClick={() => ask({ confirmLabel: label, ...config })}>
+      {label}
+    </Button>
+  );
+}