Runnable Examples

Runnable example applications demonstrate real-world integration patterns across each user touch point. Rather than relying on hand-walked code snippets, every touch point is backed by a runnable application, a documented execution contract, and automated verification against the Nervly platform stack.

All eight examples authenticate with test-mode API keys (nervly_sk_test_...), execute within ephemeral or isolated test workspaces, and assert real observable end states.

The Eight Landed Touch-Point Examples

Example	Owning Repository Path	Run Command	Summary of What Is Demonstrated
Node SDK App	nervly-js/examples/node-app	npm run example	Everyday Node integration using @nervly/sdk with health check, idempotent trigger, priority handling, bulk trigger, message status read-back to DELIVERED, preferences, and typed error handling.
Edge SDK Worker	nervly-js/examples/edge-worker	npm run example -- edge-worker	Cloudflare Workers edge runtime integration using @nervly/sdk via wrangler dev (workerd) with per-request client configuration and asserted test-mode delivery.
MCP Agent	nervly-js/examples/mcp-agent	npm run example -- mcp-agent	Deterministic Model Context Protocol (MCP) client agent driving POST /v1/mcp tool discovery, status inspection, sandbox preview, and delivery verification through @nervly/sdk.
REST API	nervly-gate/examples/rest-api	make example	Curl-first REST interactions with health, idempotent trigger, replay deduplication, bulk dispatch, message read-back, preferences, and rate-limit / validation error headers.
Provider Webhooks	nervly-gate/examples/provider-webhooks	make example	Signed provider delivery receipts (Termii and Twilio callbacks with HMAC-SHA256 signature verification) driving message lifecycle states.
CLI Scripted Journey	nervly-cli/examples/journey	make example	Scripted developer CLI journey: environment diagnostics, encrypted secrets management, device-code console authentication, and real-time webhook tunneling (forward webhooks).
Dashboard Browser Journey	nervly-app/examples/dashboard-journey	npm run example	Automated Playwright browser journey through the console: session authentication, provider review, API key generation, live message drawer inspection, and DND compliance opt-outs.
Cross-Surface Golden Path	nervly-base/examples/golden-path	make example	Flagship cross-surface verification spanning SDK, REST, CLI, and receipts in a single automated run under the shared harness contract.

---

Cross-Surface Golden Path

The cross-surface golden path is the flagship example in nervly-base/examples/golden-path. It proves interoperability by walking the complete developer journey across four distinct platform boundaries in a single automated sequence:

1. Workspace Bootstrap: Mints an ephemeral, uniquely named test-mode read-and-write API key.
2. SDK Trigger & REST Read-back: Triggers an event using @nervly/sdk and verifies via GET /v1/messages that the message reaches terminal status DELIVERED with test_mode: true.
3. CLI Webhook Tunnel: Launches nervly forward webhooks to relay incoming delivery events from the gateway to a local HTTP receiver, verifying the re-signed HMAC-SHA256 signature against the forwarding secret stored in the CLI's encrypted vault.
4. Provider Receipt Ingestion: Replays a signed provider delivery callback (Termii HMAC-SHA256) through POST /v1/webhooks/termii and verifies that the message updates to DELIVERED.
5. Subscriber Preferences & Suppression: Sets a channel opt-out (PUT /v1/users/{subscriberId}/preferences), triggers a new notification, and asserts that the dispatch is suppressed (SUPPRESSED).
6. Teardown: Deletes created test rows and revokes the ephemeral API key.

Execution Summary

Phase	Boundary	Asserted End State
1. Gateway Health	REST API	Gateway answers status: OK with connected message bus
2. Event Trigger	Node SDK	Event accepted (status: QUEUED, priority HIGH)
3. Message Status	REST API	Message observed DELIVERED with test_mode: true
4. Secrets Vault	CLI Keyring	Forwarding secret stored and verified
5. Webhook Forwarding	CLI Relay	Local receiver verifies event ID and HMAC signature
6. Provider Callback	Webhook Ingestion	Inbound callback accepted and delivery receipt logged
7. Opt-Out Compliance	Preferences API	Opt-out stored; subsequent dispatch observed SUPPRESSED
8. Teardown	Control Plane	Ephemeral test rows purged and API key revoked

Golden Path Execution Transcript

The following transcript demonstrates an execution of the golden path harness:

golden-path run 20261008T004652Z-b2e0 (target=local)
→ guard: local target, local hosts, test-mode key policy accepted
→ cli: using built binary nervly
→ isolation: isolated config and keychain store initialized
→ bootstrap: login as dev@nervly.local
  login accepted (session cookie + CSRF token captured)
  minted test-mode key examples-20261008T004652Z-b2e0
  workspace dev-local (source=seed)
→ fixtures: seeding test fixture row into dev-local
  seeded termii fixture
→ checks: gateway health
  gateway healthy (status=OK, nats_connected=true)
→ checks: trigger via the SDK (imports @nervly/sdk package entry)
  SDK trigger accepted (event evt_..., priority HIGH, via package entry)
→ checks: GET /v1/messages read-back for evt_...
  asserted end state: evt_... is DELIVERED in test mode via REST API
→ checks: planting forwarding secret in isolated store
  forwarding secret planted and read back
  relay reachable
  receiver listening at local receiver endpoint
→ checks: nervly forward webhooks --max-deliveries 1
  asserted end state: receiver verified evt_... with valid signature
→ checks: signed termii callback for termii_golden_...
→ checks: GET /v1/messages read-back for evt_...
  asserted end state: evt_... is DELIVERED via GET /v1/messages
  delivery receipt recorded
→ checks: PUT /v1/users/sub-golden-path-...-optout/preferences (channels.sms=false)
  preferences stored (sms off)
→ checks: SDK trigger after opt-out
  opt-out trigger accepted
→ checks: GET /v1/messages read-back for evt_...
  asserted end state: evt_... is SUPPRESSED via GET /v1/messages
→ checks: zero-leak scan of transcript and artifacts
  zero-leak scan clean
✓ all checks passed (SDK trigger → REST DELIVERED, CLI relay verified, provider receipt applied, opt-out SUPPRESSED)
→ teardown: deleting test message rows
  message rows deleted and verified absent
→ teardown: revoking test API key
  API key revoked
golden-path finished: PASS

---

Running the Root Example Suite

The root example suite aggregates all eight landed examples in sequence against a booted local stack. From the root orchestration checkout (nervly-base):

make up          # launch infrastructure and backend services
make seed-dev    # populate development test workspaces
make examples    # execute all 8 touch-point examples in sequence

The suite generates an aggregated machine-readable summary report at artifacts/examples-suite/report.json and a human-readable summary table at artifacts/examples-suite/report.md.