Reference
Reference Index
Every WATS reference doc and when to reach for it.
canonical · applies to 0.3.x-alpha · reviewed 2026-05-02
Graph primitives (@wats/graph)
| Doc | When to use it |
|---|---|
reference/client.md | Constructing a GraphClient; construction-time validation; request lifecycle. |
reference/endpoints.md | Defining a new endpoint with defineEndpoint; path templates, param kinds, body passthrough. |
reference/scoped-clients.md | Binding a phoneNumberId or wabaId into a PhoneNumberClient / WABAClient. |
reference/calling.md | WhatsApp Calling lifecycle, call permissions, call-button/deep-link helpers, calling webhooks, and operator constraints. |
reference/groups.md | WhatsApp Groups endpoint contracts, limits, webhook outcomes, service opt-in routes. |
reference/errors.md | The error registry; every pywa error code → WATS subclass; classification rules. |
reference/pagination.md | paginate / paginateAll; cursor extraction; AbortSignal; PaginationError taxonomy. |
reference/media.md | Media runtime: upload, metadata, binary download, delete, encrypted decrypt, upload sessions, and Node/Bun path helpers via @wats/graph/node-media. Endpoint family subpaths: @wats/graph/endpoints/{messages,media,templates,flows,calling,business-management,groups}. |
Core primitives (@wats/core)
| Doc | When to use it |
|---|---|
reference/webhook-normalizer.md | Translating a raw Meta webhook envelope into a TypedUpdate discriminated union. |
reference/filters.md | Typed-filter surface: brand, combinators, and built-ins. |
reference/router.md | TypedRouter handle-based registration, observer seams, DispatchReport shape. |
reference/whatsapp-facade.md | The WhatsApp composition root; what it binds, what it exposes, when to bypass it. |
reference/listeners.md | Listener substrate: wa.listen({ ... }), timeouts, cancellation, registry lifecycle. |
HTTP primitives (@wats/http)
| Doc | When to use it |
|---|---|
reference/webhook-adapter.md | Wiring up a webhook endpoint: createWebhookAdapter core + Bun / Node / Fetch wrappers. |
reference/webhook.md | Low-level verifyWebhookChallenge + validateWebhookSignature primitives. |
Crypto primitives (@wats/crypto)
| Doc | When to use it |
|---|---|
reference/crypto.md | CryptoProvider seam; Node / Bun / WebCrypto adapters; typed error hierarchy. |
Shared types (@wats/types)
| Doc | When to use it |
|---|---|
reference/types.md | Discriminated-union domain types. |
App-layer primitives
| Doc | When to use it |
|---|---|
reference/config.md | @wats/config YAML/JSON schema, env-secret refs, validation, redaction. |
reference/cli.md | @wats/cli commands: init, setup, doctor, serve, openapi export, messages list/show. |
reference/service.md | @wats/service runtime-neutral standalone webhook/API service. |
reference/persistence.md | Durable runtime state: SQLite + Postgres adapters, migrations, idempotency, outbox, message projection. |
reference/service.md | Generated OpenAPI 3.1 document and GET /openapi.json service route. |
Guides
| Guide | When to use it |
|---|---|
../guides/cli-init.md | Config scaffolding, setup wizard, doctor, dry-run serve. Start here. |
../guides/live-webhook.md | Public HTTPS tunnel, live serve, webhook onboarding checklist. |
../guides/transport-and-testing.md | Injecting MockTransport; consumer-fixture pattern. |
../guides/groups-quickstart.md | Credential-free Groups flow from create through invite, approval, and group messaging. |
../guides/deploy-docker.md | Container deployment design scaffold — not a supported runnable image yet. |
../guides/deploy-bun.md | Deploying a webhook on Bun. |
../guides/deploy-node.md | Deploying a webhook on Node http.createServer. |
../guides/deploy-cloudflare-workers.md | Deploying a webhook on Cloudflare Workers. |