MedusaEvents — GNU Taler × MedusaJS event-commerce POC

Working proof-of-concept for the NLnet NGI TALER proposal: a reusable taler-merchant TypeScript client, a medusa-payment-taler MedusaJS v2 payment provider, and a multi-vendor event demo — all running against the public GNU Taler sandbox (backend.demo.taler.net, KUDOS currency).

See docs/roadmap.md for planned work, docs/changelog.md for completed work, and docs/adr/ for the architecture decisions behind both packages.

Verified end-to-end (2026-07-17)

1. Storefront cart (Day Ticket + 2 Beer Tokens, €45) → Medusa payment session → live Taler order KUDOS:45 with taler://pay/... URI
2. Paid with the real GNU Taler wallet CLI (built from taler-typescript-core source; withdrew KUDOS from bank.demo.taler.net)
3. Cart completed → Medusa order #1, payment captured via provider status mapping (unpaid|claimed → pending, paid → captured)
4. GET /admin/vendor-settlement → per-vendor gross/units with the Taler order id as reconciliation reference
5. Partial refund (€5) from Medusa admin → Taler order shows refunded: true, refund_amount: KUDOS:5, reason: "Refund issued from Medusa"

Run it

Prereqs: Node ≥20, local PostgreSQL with a medusa_events database.

# (repo root — uses pnpm workspaces)
pnpm install

# build the two packages
pnpm -F taler-merchant build
pnpm -F medusa-payment-taler build

# backend (see "Fresh database setup" below for migrations + admin user)
cd apps/backend
PORT=7481 npx medusa develop          # admin at http://localhost:7481/app

# storefront
cd ../storefront
npx next dev -p 7482                  # http://localhost:7482

Fresh database setup: npx medusa db:migrate (also runs the starter seed), npx medusa user -e <email> -p <password>, then npx medusa exec ./src/scripts/seed-event.ts for the event demo data.

Taler config lives in apps/backend/.env: TALER_MERCHANT_URL, TALER_MERCHANT_TOKEN (sandbox instance uses token sandbox), TALER_CURRENCY=KUDOS (sandbox shim — demo prices map 1:1).

Checkout demo

In the storefront, add event products to the cart, check out, pick GNU Taler as payment method and press Pay with GNU Taler: a QR code with the taler://pay/ URI appears and the page polls /store/taler/order-status until the wallet pays, then places the order automatically. Pay with the Android/iOS Taler wallet (get KUDOS at https://bank.demo.taler.net) or the wallet CLI.

Not in the POC (grant scope)

OpenAPI-generated types, webhook-based status (POC polls), replay/idempotency test matrix, dockerized Taler backend for CI, WCAG 2.1 AA audit, marketplace module (vendors are product metadata), npm publishing.