Reference

Reference Index

Every WATS reference doc and when to reach for it.

applies to 0.4.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.

Internal packages

Doc	When to use it
`reference/internal-utils.md`	`@wats/internal-utils` — internal helpers, not a public API. Published only so public packages install cleanly from the registry.

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.

Async integration contract

Stable WATS import surface for app-side queues, workers, idempotency, throttling, and media offload.

Client Reference

The public GraphClient API surface: configuration types, request lifecycle, and validation rules.

On this page

Graph primitives (@wats/graph)Core primitives (@wats/core)HTTP primitives (@wats/http)Crypto primitives (@wats/crypto)Shared types (@wats/types)App-layer primitives Internal packages Guides