Skip to content

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 ​

bash
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:live

Verified live — the proof ​

The live harness (scripts/verify-live.mjs) boots the app against the real tenant and asserts every route. Latest run:

GateResult
Read routes24 / 24 2xx
Write journey17 / 17 2xx
Unexpected 400s0
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.

Released under the MIT License. Not affiliated with ZR Express.