{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "dev-1", "title": "Dev 1: developers page", "author": "Ballmac ", "description": "A developers page: a 14-day request chart with errors stacked, success rate and median time, API keys shown in full once and revoked behind a confirmation, and a request log with filter, responses and copy as curl.", "dependencies": [ "lucide-react" ], "registryDependencies": [ "utils", "https://ui.ballmac.com/r/alert-dialog.json", "https://ui.ballmac.com/r/badge.json", "https://ui.ballmac.com/r/blur-fade.json", "https://ui.ballmac.com/r/button.json", "https://ui.ballmac.com/r/copy-button.json", "https://ui.ballmac.com/r/json-viewer.json", "https://ui.ballmac.com/r/number-ticker.json", "https://ui.ballmac.com/r/segmented-control.json", "https://ui.ballmac.com/r/skeleton.json", "https://ui.ballmac.com/r/state-view.json", "https://ui.ballmac.com/r/return-focus.json" ], "files": [ { "path": "registry/ballmac/components/blocks/dev-1/dev-1.tsx", "content": "// Ballmac UI: Dev 1. https://ui.ballmac.com/blocks/dev-1\n\"use client\"\n\nimport * as React from \"react\"\nimport { ChevronRight, CircleAlert, CircleCheck, CircleX, KeyRound, Loader2, Plus, Search, ShieldAlert, TerminalSquare, TriangleAlert } from \"lucide-react\"\n\nimport { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle } from \"@/components/ballmac/alert-dialog\"\nimport { Badge } from \"@/components/ballmac/badge\"\nimport { BlurFade } from \"@/components/ballmac/blur-fade\"\nimport { Button } from \"@/components/ballmac/button\"\nimport { CopyButton } from \"@/components/ballmac/copy-button\"\nimport { JsonViewer } from \"@/components/ballmac/json-viewer\"\nimport { NumberTicker } from \"@/components/ballmac/number-ticker\"\nimport { SegmentedControl, SegmentedControlItem } from \"@/components/ballmac/segmented-control\"\nimport { Skeleton } from \"@/components/ballmac/skeleton\"\nimport { useReturnFocus } from \"@/lib/ballmac/return-focus\"\nimport { frameProps, StateView, type StateProps } from \"@/components/ballmac/state-view\"\nimport { cn } from \"@/lib/utils\"\n\ntype Dev1Scope = \"read\" | \"write\" | \"admin\"\ntype Dev1Env = \"test\" | \"live\"\n\ntype Dev1Key = {\n id: string\n name: string\n scope: Dev1Scope\n /** The last four characters, the only part that is ever shown again. */\n last4: string\n /** Already written for people (\"12 Mar 2026\"). */\n created: string\n /** Already written for people (\"2 hours ago\"). Leave out for a key that was never used. */\n lastUsed?: string\n}\n\ntype Dev1Request = {\n id: string\n method: \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\"\n path: string\n status: number\n /** Milliseconds. */\n ms: number\n /** Already written for people (\"2 min ago\"). */\n time: string\n ip?: string\n /** The name of the key the request used. */\n keyName?: string\n response?: unknown\n}\n\ntype Dev1Usage = {\n /** One entry per day, oldest first. */\n days: { label: string; ok: number; errors: number }[]\n /** Median response time in milliseconds. */\n p50: number\n}\n\ntype Dev1Props = Omit, \"title\"> &\n StateProps & {\n keys?: Dev1Key[]\n requests?: Dev1Request[]\n usage?: Dev1Usage\n /** The environment shown at first. */\n defaultEnv?: Dev1Env\n onEnvChange?: (env: Dev1Env) => void\n /** The address the API lives at, used in the curl commands. */\n baseUrl?: string\n /**\n * Creates a key. Resolve with its id and the full secret, which is shown once; throw to show the reason. Defaults to a\n * simulated key so the page works without a backend.\n */\n onCreateKey?: (input: { name: string; scope: Dev1Scope; env: Dev1Env }) => Promise<{ id: string; secret: string; last4?: string }>\n /** Called after Revoke is confirmed. */\n onRevokeKey?: (id: string) => void | Promise\n /** The id of a request that is open at first. */\n defaultOpenRequest?: string\n }\n\nconst sampleKeys: Dev1Key[] = [\n { id: \"k1\", name: \"Production server\", scope: \"write\", last4: \"a1b2\", created: \"12 Mar 2026\", lastUsed: \"2 hours ago\" },\n { id: \"k2\", name: \"Analytics (read only)\", scope: \"read\", last4: \"9f3c\", created: \"2 Jan 2026\", lastUsed: \"yesterday\" },\n { id: \"k3\", name: \"CI deploy\", scope: \"admin\", last4: \"77de\", created: \"30 Oct 2025\" },\n]\n\nconst sampleUsage: Dev1Usage = {\n p50: 84,\n days: [\n [\"Oct 4\", 3120, 24], [\"Oct 5\", 3410, 31], [\"Oct 6\", 3290, 19], [\"Oct 7\", 2810, 22], [\"Oct 8\", 2630, 15], [\"Oct 9\", 3560, 40], [\"Oct 10\", 4010, 38],\n [\"Oct 11\", 3890, 29], [\"Oct 12\", 4210, 61], [\"Oct 13\", 4090, 34], [\"Oct 14\", 3320, 25], [\"Oct 15\", 2980, 17], [\"Oct 16\", 3870, 28], [\"Oct 17\", 4380, 52],\n ].map(([label, ok, errors]) => ({ label: label as string, ok: ok as number, errors: errors as number })),\n}\n\nconst sampleRequests: Dev1Request[] = [\n { id: \"req_8f2a91\", method: \"POST\", path: \"/v1/charges\", status: 201, ms: 142, time: \"12 sec ago\", ip: \"203.0.113.24\", keyName: \"Production server\", response: { id: \"ch_3Nf2\", amount: 12900, currency: \"usd\", status: \"succeeded\" } },\n { id: \"req_8f2a90\", method: \"GET\", path: \"/v1/customers/cus_91\", status: 200, ms: 38, time: \"41 sec ago\", ip: \"203.0.113.24\", keyName: \"Production server\", response: { id: \"cus_91\", email: \"jordan@acme.com\", balance: 0 } },\n { id: \"req_8f2a8f\", method: \"POST\", path: \"/v1/refunds\", status: 402, ms: 96, time: \"3 min ago\", ip: \"198.51.100.7\", keyName: \"Production server\", response: { error: { type: \"card_error\", code: \"charge_already_refunded\", message: \"This charge has already been refunded.\" } } },\n { id: \"req_8f2a8e\", method: \"GET\", path: \"/v1/events?limit=50\", status: 200, ms: 61, time: \"6 min ago\", ip: \"198.51.100.19\", keyName: \"Analytics (read only)\", response: { data: [], has_more: false } },\n { id: \"req_8f2a8d\", method: \"DELETE\", path: \"/v1/webhooks/we_12\", status: 204, ms: 54, time: \"14 min ago\", ip: \"203.0.113.24\", keyName: \"Production server\" },\n { id: \"req_8f2a8c\", method: \"POST\", path: \"/v1/charges\", status: 500, ms: 2140, time: \"22 min ago\", ip: \"203.0.113.24\", keyName: \"Production server\", response: { error: { type: \"api_error\", message: \"Something went wrong on our side. The request was not processed.\" } } },\n { id: \"req_8f2a8b\", method: \"GET\", path: \"/v1/invoices\", status: 401, ms: 12, time: \"31 min ago\", ip: \"192.0.2.88\", response: { error: { type: \"authentication_error\", message: \"No valid API key was provided.\" } } },\n { id: \"req_8f2a8a\", method: \"PATCH\", path: \"/v1/customers/cus_91\", status: 200, ms: 77, time: \"48 min ago\", ip: \"203.0.113.24\", keyName: \"Production server\", response: { id: \"cus_91\", name: \"Jordan Lee\" } },\n]\n\nconst methodTone: Record = {\n GET: \"bg-chart-1/20\",\n POST: \"bg-chart-2/20\",\n PUT: \"bg-chart-3/25\",\n PATCH: \"bg-chart-3/25\",\n DELETE: \"bg-destructive/15\",\n}\nconst statusText: Record = { 200: \"OK\", 201: \"Created\", 204: \"No content\", 400: \"Bad request\", 401: \"Unauthorized\", 402: \"Request failed\", 403: \"Forbidden\", 404: \"Not found\", 429: \"Too many requests\", 500: \"Server error\", 502: \"Bad gateway\" }\nconst scopeCopy: Record = { read: \"Can read data. Cannot change anything.\", write: \"Can read and change data.\", admin: \"Full access, including keys and webhooks. Keep it out of apps.\" }\n\nfunction StatusChip({ status }: { status: number }) {\n const ok = status < 400\n const warn = status >= 400 && status < 500\n const Icon = ok ? CircleCheck : warn ? TriangleAlert : CircleX\n return (\n \n \n {status}\n \n \n )\n}\n\nfunction DevSkeleton() {\n return (\n
\n \n \n \n
\n )\n}\n\nfunction Card({ id, title, description, action, children }: { id: string; title: string; description?: string; action?: React.ReactNode; children: React.ReactNode }) {\n return (\n
\n
\n
\n

\n {title}\n

\n {description ?

{description}

: null}\n
\n {action}\n
\n {children}\n
\n )\n}\n\n/**\n * A developers page: how the API is doing (a 14-day chart with errors stacked, success rate, median time), API keys that are shown in\n * full exactly once and revoked behind a confirmation, and a request log with a filter, expandable responses and copy as curl.\n */\nfunction Dev1({\n keys: keysProp = sampleKeys,\n requests = sampleRequests,\n usage = sampleUsage,\n defaultEnv = \"test\",\n onEnvChange,\n baseUrl = \"https://api.acme.com\",\n onCreateKey,\n onRevokeKey,\n defaultOpenRequest,\n state = \"ready\",\n onRetry,\n emptyState,\n errorState,\n className,\n ...props\n}: Dev1Props) {\n const id = React.useId()\n const [env, setEnv] = React.useState(defaultEnv)\n const [keys, setKeys] = React.useState(keysProp)\n React.useEffect(() => setKeys(keysProp), [keysProp])\n const [creating, setCreating] = React.useState(false)\n const [name, setName] = React.useState(\"\")\n const [scope, setScope] = React.useState(\"read\")\n const [saving, setSaving] = React.useState(false)\n const [createError, setCreateError] = React.useState()\n const [fresh, setFresh] = React.useState<{ name: string; secret: string } | null>(null)\n const [revoke, setRevoke] = React.useState(null)\n const returnFocus = useReturnFocus(!!revoke)\n const [filter, setFilter] = React.useState<\"all\" | \"errors\">(\"all\")\n const [query, setQuery] = React.useState(\"\")\n const [open, setOpen] = React.useState(defaultOpenRequest ?? null)\n const [announce, setAnnounce] = React.useState(\"\")\n const made = React.useRef(0)\n const ready = state === \"ready\" || state === \"empty\"\n const log = state === \"empty\" ? [] : requests\n const prefix = env === \"live\" ? \"sk_live_\" : \"sk_test_\"\n\n const total = usage.days.reduce((s, d) => s + d.ok + d.errors, 0)\n const errors = usage.days.reduce((s, d) => s + d.errors, 0)\n const rate = total ? ((total - errors) / total) * 100 : 100\n const peak = Math.max(1, ...usage.days.map((d) => d.ok + d.errors))\n const busiest = usage.days.reduce((a, d) => (d.ok + d.errors > a.ok + a.errors ? d : a), usage.days[0] ?? { label: \"\", ok: 0, errors: 0 })\n\n const q = query.trim().toLowerCase()\n const shown = log.filter((r) => (filter === \"all\" || r.status >= 400) && (!q || r.path.toLowerCase().includes(q) || r.method.toLowerCase().includes(q) || String(r.status).includes(q)))\n const errorCount = log.filter((r) => r.status >= 400).length\n const curl = (r: Dev1Request) => `curl ${baseUrl}${r.path} \\\\\\n -X ${r.method} \\\\\\n -H \"Authorization: Bearer $API_KEY\"`\n const firstCurl = `curl ${baseUrl}/v1/charges \\\\\\n -X POST \\\\\\n -H \"Authorization: Bearer $API_KEY\" \\\\\\n -d amount=2000 -d currency=usd`\n\n async function create(e: React.FormEvent) {\n e.preventDefault()\n if (!name.trim()) return setCreateError(\"Give the key a name so you can recognise it later.\")\n setSaving(true)\n setCreateError(undefined)\n try {\n const result: { id: string; secret: string; last4?: string } = onCreateKey\n ? await onCreateKey({ name: name.trim(), scope, env })\n : await new Promise<{ id: string; secret: string }>((r) => {\n made.current += 1\n setTimeout(() => r({ id: `new-${made.current}`, secret: `${prefix}${\"x7Kq2MvR9tLpA4dZ8nWcB3yF\".slice(0, 20)}${String(made.current).padStart(4, \"0\")}` }), 700)\n })\n setKeys((l) => [{ id: result.id, name: name.trim(), scope, last4: result.last4 ?? result.secret.slice(-4), created: \"Just now\" }, ...l])\n setFresh({ name: name.trim(), secret: result.secret })\n setName(\"\")\n setScope(\"read\")\n setCreating(false)\n setAnnounce(`Key ${name.trim()} created. Copy it now.`)\n } catch (err) {\n setCreateError(err instanceof Error && err.message ? err.message : \"The key could not be created. Try again.\")\n } finally {\n setSaving(false)\n }\n }\n\n const content = (\n
\n \n \n
\n
\n
\n

\n \n

\n

requests

\n
\n
\n {usage.days.map((d) => {\n const all = d.ok + d.errors\n return (\n
\n \n
\n
\n
\n
\n
\n )\n })}\n
\n
\n {usage.days[0]?.label}\n {usage.days[usage.days.length - 1]?.label}\n
\n
\n\n \n \n \n \n \n \n \n \n \n {usage.days.map((d) => (\n \n \n \n \n \n ))}\n \n
Requests per day
DaySuccessfulErrors
{d.label}{d.ok}{d.errors}
\n
\n
\n
\n {[\n { label: \"Success rate\", value: `${rate.toFixed(1)}%`, hint: rate >= 99 ? \"Healthy\" : \"Worth a look\" },\n { label: \"Median time\", value: `${usage.p50} ms`, hint: \"p50\" },\n { label: \"Errors\", value: new Intl.NumberFormat(\"en-US\").format(errors), hint: \"Last 14 days\" },\n ].map((s) => (\n
\n
{s.label}
\n
{s.value}
\n
{s.hint}
\n
\n ))}\n
\n
\n \n \n\n \n setCreating(true)}>\n \n Create key\n \n ) : null\n }\n >\n {fresh ? (\n
\n

\n \n Copy “{fresh.name}” now\n

\n

This is the only time the full key is shown. Store it somewhere safe; if you lose it, create a new one.

\n
\n \n {fresh.secret}\n \n \n
\n \n
\n ) : null}\n {creating ? (\n
\n
\n \n setName(e.target.value)}\n placeholder=\"Production server\"\n aria-invalid={!!createError || undefined}\n aria-describedby={createError ? `${id}-name-error` : undefined}\n className=\"border-input bg-background focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:border-destructive h-9 rounded-md border px-3 text-sm outline-none focus-visible:ring-[3px]\"\n />\n {createError ? (\n

\n {createError}\n

\n ) : null}\n
\n
\n \n Access\n \n setScope(v as Dev1Scope)} aria-labelledby={`${id}-scope`} size=\"sm\">\n Read\n Write\n Admin\n \n

{scopeCopy[scope]}

\n
\n
\n \n {\n setCreating(false)\n setCreateError(undefined)\n }}\n >\n Cancel\n \n
\n
\n ) : null}\n
    \n {keys.map((k) => (\n
  • \n \n \n \n
    \n

    \n {k.name}\n \n {k.scope}\n \n

    \n

    \n {prefix}••••••••{k.last4}\n

    \n
    \n

    \n Created {k.created} · {k.lastUsed ? `used ${k.lastUsed}` : \"never used\"}\n

    \n \n
    • \n ))}\n {!keys.length ?
  • No keys yet. Create one to make your first request.
    • : null}\n
\n \n \n\n \n \n
\n \n setQuery(e.target.value)} className=\"placeholder:text-muted-foreground w-24 bg-transparent text-xs outline-none sm:w-32\" />\n
\n setFilter(v as typeof filter)} aria-label=\"Show\" size=\"sm\">\n All\n Errors {errorCount}\n \n
\n ) : null\n }\n >\n {log.length ? (\n
    \n {shown.map((r) => {\n const isOpen = open === r.id\n return (\n
  • \n setOpen(isOpen ? null : r.id)}\n className=\"hover:bg-accent/40 focus-visible:ring-ring/50 grid w-full grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-x-4 gap-y-1 px-5 py-3 text-start outline-none focus-visible:ring-[3px] focus-visible:ring-inset md:grid-cols-[4.5rem_minmax(0,1fr)_9rem_4.5rem_6rem_auto]\"\n >\n {r.method}\n \n {r.path}\n \n \n \n \n \n \n \n \n {isOpen ? (\n
    \n
    \n
    \n {[\n [\"Request ID\", r.id],\n [\"Took\", `${r.ms} ms`],\n [\"When\", r.time],\n ...(r.keyName ? [[\"Key\", r.keyName]] : []),\n ...(r.ip ? [[\"IP address\", r.ip]] : []),\n ].map(([k, v]) => (\n
    \n
    {k}
    \n
    \n {v}\n
    \n
    \n ))}\n
    \n \n
    \n
    \n

    Response

    \n {r.response !== undefined ? :

    No body. The server answered {r.status} {statusText[r.status] ?? \"\"}.

    }\n
    \n
    \n ) : null}\n
    • \n )\n })}\n {!shown.length ?
  • No requests match.
    • : null}\n
\n ) : (\n
\n \n \n \n

{emptyState?.title ?? \"No requests yet\"}

\n

{emptyState?.description ?? \"Make your first request with a test key and it will appear here within a few seconds.\"}

\n
\n 
\n                  {firstCurl}\n
\n
\n \n
\n
\n {emptyState?.action}\n
\n )}\n \n \n
\n )\n\n return (\n
\n
\n
\n

\n Developers\n

\n

Keys, usage and a log of what your code sent.

\n
\n {\n setEnv(v as Dev1Env)\n onEnvChange?.(v as Dev1Env)\n }}\n aria-label=\"Mode\"\n disabled={!ready}\n >\n Test mode\n \n \n Live mode\n \n \n
\n {env === \"live\" && ready ? (\n

\n \n You are looking at live mode. Requests with these keys change real customer data.\n

\n ) : null}\n } error={{ title: errorState?.title ?? \"Developer data could not be loaded\", description: errorState?.description ?? \"Your keys are safe and nothing changed. Check your connection and try again.\", ...errorState }}>\n {content}\n \n\n !o && setRevoke(null)}>\n \n \n Revoke “{revoke?.name}”?\n Anything using this key stops working straight away. This cannot be undone, but you can create a new key.\n \n \n Cancel\n {\n if (!revoke) return\n await onRevokeKey?.(revoke.id)\n setKeys((l) => l.filter((x) => x.id !== revoke.id))\n setAnnounce(`${revoke.name} revoked`)\n }}\n >\n Revoke key\n \n \n \n \n

\n {announce}\n

\n
\n )\n}\n\nexport { Dev1, type Dev1Props, type Dev1Key, type Dev1Request, type Dev1Usage, type Dev1Scope, type Dev1Env }\n", "type": "registry:component", "target": "@components/ballmac/blocks/dev-1/dev-1.tsx" } ], "meta": { "schema": 1, "tier": "free", "tags": [ "developer", "api", "api keys", "request log", "usage", "test mode", "live mode", "curl", "logs", "dashboard", "platform" ], "version": "1.0.0", "updated": "2026-10-17", "tests": true, "ai": { "summary": "A developer dashboard page. ({ id, secret })} onRevokeKey onEnvChange defaultEnv />. The secret returned by onCreateKey is shown once in a copy banner and only its last four characters are kept in the list.", "whenToUse": [ "The developer or API section of a platform product", "Letting customers manage keys and debug requests themselves" ], "whenNotToUse": [ "Showing one secret in a settings form (use api-key-field)", "Webhook endpoints and deliveries (use webhook-card)", "Server logs for operators (use log-stream)" ], "composesWith": [ "settings-4", "settings-5", "app-shell-1", "agent-3" ], "a11y": [ { "keys": "Chart", "action": "An image with a text summary, plus a hidden table with the numbers for each day; bars never carry meaning by color alone" }, { "keys": "Create key", "action": "The new key is announced and shown in an alert with a Copy button; Revoke asks first in an alert dialog" }, { "keys": "Enter / Space on a request", "action": "Opens its response (aria-expanded); status is an icon, the number and words, not color alone" } ], "customization": [ "baseUrl for the curl commands; defaultEnv: 'test' | 'live' (live shows a warning and sk_live_ prefixes)", "onCreateKey must call your backend: the secret must never be derivable on the client", "defaultOpenRequest opens a request at first" ] }, "states": [ { "id": "loading", "title": "Loading", "example": "dev-1-loading", "trigger": "state=\"loading\"", "note": "A skeleton of the usage chart, the keys and the request log under the real heading." }, { "id": "empty", "title": "No requests yet", "example": "dev-1-empty", "trigger": "state=\"empty\" (or requests={[]})", "note": "Explains that requests appear within seconds and gives a ready curl command to make the first one, with a copy button." }, { "id": "error", "title": "Could not load", "example": "dev-1-error", "trigger": "state=\"error\"", "note": "An alert saying keys are safe and nothing changed, with Try again (onRetry)." } ], "examples": [ "dev-1-demo", "dev-1-live", "dev-1-empty", "dev-1-loading", "dev-1-error" ], "url": "https://ui.ballmac.com/components/dev-1" }, "categories": [ "blocks", "developer" ], "type": "registry:block" }