Digital Marketplace — AI skill for Claude Code

digital-marketplace

A marketplace for digital products where every listing comes with an assistant that has actually read it. Sellers upload a document, buyers purchase it once or subscribe, and questions get answered from the document itself — with citations. Reviews and refunds are durable workflows that wait for a human. English and Vietnamese.

Built on four libraries extracted from it:

Library	What it owns here
agent-runtime	the "ask about this product" agent: tools, quota gate, streaming, tracing with cost
durable-workflow	product review (waits up to 7 days for an admin) and refunds (waits for a decision, then calls the provider with retries)
subscription-billing	the billing design: idempotent webhooks, forward-only state machines, entitlements derived on read
offline-license	the self-hosted edition: admin area gated by a signed license, no phone-home

The RAG pipeline (structure-aware chunking → embeddings → pgvector → MMR re-ranking) lives in `src/rag/` and runs on Postgres alone — no vector service.

Flows

**Buy.** `POST /api/checkout/order` persists a `PENDING` order *before* calling Stripe, so a webhook that beats the response still finds it. Stripe's `checkout.session.completed` arrives at `POST /api/webhooks/stripe`: raw body → signature → event id claimed in `WebhookEvent` (the insert is the lock) → `UPDATE … WHERE status IN (PENDING)`. A replayed delivery is a `duplicate`; two racing deliveries produce one winner. Download access is one pure function (`domain/access.ts`) used by both the button and the file route, so they can never disagree.

**Ask.** `POST /api/products/:id/ask` streams SSE. Before the model is called: plan check (`ask_ai`), then monthly quota incremented in the database. The agent