Playground Demo
The repository ships a complete demo app — examples/playground — that exercises the SDK end to end from a polished web dashboard, and is verified live against the real ZR Express tenant. It's the best way to see every capability working, and the source the docs draw their verified request shapes from.
What it is
A NestJS 11 backend that wraps the real SDK surface (one thin controller per domain), serving a vanilla HTML/CSS/JS dashboard from the same origin — no CORS, one command. It has an SDK → HTTP exception filter (proving empty-body 401/403 mapping), a write-gate guard, and a Svix-verified webhook receiver streamed to the UI over SSE.
Safety
The .env tenant is a real production tenant — so the playground is safe by default:
- Read-only by default. Every state-changing route is disabled unless
PLAYGROUND_ALLOW_WRITES=1. - Scratch data only. Everything it creates is stamped
externalId: sdk-test-…; deletes refuse anything that isn't scratch; there is no accept-payment route. - Key never reaches the browser — only the server reads
.env.
Run it
pnpm install
# read-only
pnpm --filter @terminaldz/zrexpress-playground dev # http://localhost:3000
# with the guarded write routes enabled (production-tenant warning applies)
PLAYGROUND_ALLOW_WRITES=1 pnpm --filter @terminaldz/zrexpress-playground dev
# credential-free e2e (mocked SDK transport)
pnpm --filter @terminaldz/zrexpress-playground test
# live verification harness (reads + writes + negatives, with cleanup)
PLAYGROUND_ALLOW_WRITES=1 pnpm --filter @terminaldz/zrexpress-playground verify:liveVerified live — the proof
The live harness (scripts/verify-live.mjs) boots the app against the real tenant and asserts every route. Latest run:
| Gate | Result |
|---|---|
| Read routes | 24 / 24 2xx |
| Write journey | 17 / 17 2xx |
Unexpected 400s | 0 |
| Orphaned scratch parcels (post-cleanup) | 0 |
Negatives (expected 4xx) | 4 / 4 |
Drift-blocked (expected 4xx) | 2 / 2 |
The write journey, all 2xx, in order: create → get → state-history → track → legal state transition → labels PDF → bulk create ×2 (assert:false / assert:true) → delete → 404-after-delete → bulk-delete → cleanup ×2 → webhook create → secret → delete → endpoint count back to baseline. The harness writes the full matrix to examples/playground/docs/verification-report.json (gitignored — it describes a real tenant).
Every hand-written code sample in these docs uses the exact shapes this harness proved return 2xx — see API Quirks.
Screenshots
Screenshots are intentionally not published: the playground runs against a real tenant, so any capture would show real customer names, phone numbers, and balances. Run it locally to see the dashboard.