feat: Capture Platform – unified API, API keys, SDK, thin clients

[chintu79]

Current state

• Browser extension owns classification logic (decides resource vs note vs prompt)
• Three separate endpoints: POST /api/ext/save-resource, POST /api/ext/save-note, POST /api/ext/save-prompt
• No API key authentication — extension uses session cookie only
• No SDK — every client implements its own HTTP layer
• No webhook events

Target state

Single POST /api/v1/capture endpoint consumed by every client. API key authentication for non-browser clients. @devventory/sdk package used by all clients. Backend owns classification, enrichment, relationships, and tagging. Browser extension becomes a thin client — one of 14+ possible clients (CLI, VS Code, Raycast, bots, MCP, n8n, etc.).

Phases

Phase A — Capture API + API Keys (~2 days)

• POST /api/v1/capture route with Zod validation
• Unified auth middleware supporting both sessions and API key Bearer tokens
• ApiKey Prisma model + migration (name, prefix, hash, scopes, expiresAt, revokedAt)
• API key generation (SHA-256 hashed, shown once at creation)
• API key management UI in Settings (create, list, revoke, rotate)
• AI classification pipeline (content type detection, title generation, tag inference)
• Rate limiting per key/session/IP
• Keep old endpoints running in parallel

Phase B — SDK (~1 day)

• packages/sdk/ with Devventory class
• Methods: capture(), search(), resources.*, notes.*, prompts.*
• Zero dependencies (uses native fetch)
• TypeScript types from @devventory/types
• Retry with exponential backoff
• Tree-shakeable, ~2KB gzipped

Phase C — Extension refactor (~2 days)

• Install @devventory/sdk in extension
• Replace direct API calls with dv.capture()
• Remove content-type classification logic from extension
• Remove provider-specific business logic
• Extension becomes: detect provider → extract metadata → call SDK → show result

Phase D — Deprecate old endpoints (~1 day)

• Add deprecation headers to POST /api/ext/save-*
• Monitor for zero traffic
• Remove POST /api/ext/save-resource
• Remove POST /api/ext/save-note
• Remove POST /api/ext/save-prompt

Phase E — New clients (future issues)

• CLI (npx devventory capture)
• VS Code extension
• Raycast extension
• Telegram bot
• Webhook events
• MCP server
• n8n node / Zapier app

Files changed

File	Action
apps/web/src/app/api/v1/capture/route.ts	New
apps/web/src/lib/auth/api-auth.ts	New
apps/web/prisma/schema.prisma	Modified (add ApiKey model)
apps/web/src/app/settings/api-keys/page.tsx	New
packages/sdk/src/index.ts	New
apps/extension/entrypoints/background.ts	Modified
apps/extension/entrypoints/content.ts	Modified
apps/extension/context-engine/capabilities.ts	Simplified
apps/web/src/app/api/ext/save-resource/route.ts	Deleted (Phase D)
apps/web/src/app/api/ext/save-note/route.ts	Deleted (Phase D)
apps/web/src/app/api/ext/save-prompt/route.ts	Deleted (Phase D)

Architecture

Full specification in ARCHITECTURE.md.

Acceptance criteria

• POST /api/v1/capture accepts captures from any client (extension, curl, SDK)
• API keys can be created, revoked, and rotated from Settings
• Extension uses SDK, no longer classifies content
• Old endpoints deleted after zero traffic confirmed
• No backend changes required to add new client types