API Stability Policy

active · applies to WATS 0.x alpha package line · reviewed 2026-05-24

WATS public APIs carry one of three labels during the 0.x alpha line: stable-for-0.x, experimental, or internal. Pick your coupling accordingly.

Stable-for-0.x surfaces

Stable-for-0.x surfaces avoid breaking changes within the same minor version. Compatible fixes, docs clarifications, stricter validation for unsafe inputs, and additive helpers may still ship in patch releases.

Current stable-for-0.x surfaces:

• @wats/types shared domain type modules and documented subpaths.
• @wats/crypto provider interfaces and Node/WebCrypto adapter subpaths.
• Core Graph substrate in @wats/graph: GraphClient, transport interfaces, defineEndpoint, createFetchTransport, createMockTransport, pagination, and error taxonomy.
• @wats/http webhook challenge/signature verification and runtime-neutral webhook adapters.
• @wats/core typed update normalization, filters, router, listener registry, and WhatsApp facade foundation.

Breaking changes to these surfaces require at least a 0.x minor bump plus changelog and migration notes.

Experimental surfaces

Experimental surfaces are public enough to use and test, but may change in any 0.x minor while WATS works toward WhatsApp parity. Changes are still documented and tested. Pin versions and expect movement.

Current experimental surfaces:

• Flow DSL and data-channel helpers in @wats/graph/endpoints/flows and root Graph Flow exports.
• Calling endpoint helpers in @wats/graph/endpoints/calling and root Graph Calling exports.
• Endpoint catalog breadth beyond the stable Graph substrate, including new admin/business, template, media, marketing-message, and future parity families.
• @wats/config, @wats/cli, @wats/service, and @wats/persistence operator/application-edge surfaces while live mode, deployment, and persistence are still evolving.
• @wats/persistence/sqlite is experimental local/single-instance persistence; @wats/persistence/postgres is an experimental shape-only adapter (mock-client tested, no default CI live Postgres); service integration is a separate follow-up surface.
• Generated OpenAPI details and docs-site navigation during public alpha.

Experimental exports carry a JSDoc @experimental tag on their source barrels or declarations.

Internal and unsupported surfaces

Internal and unsupported surfaces carry no application stability guarantee.

• @wats/internal-utils is published internal support for WATS runtime dependency closure. npm must install it; you should not import it.
• @wats/testing is private workspace-only test infrastructure and is not published.
• Config persistence schema, raw webhook-body persistence, deeper CLI thread/conversation navigation, and observed status UI are not exported yet.
• Credentialed local live wats serve is experimental operator tooling. It requires explicit --live --yes-live --env-file .env.local and is not a production hosting contract.

Policy for changes

• Patch releases may include docs fixes, test-only changes, validation hardening, packaging fixes, and bug fixes that preserve public contracts.
• Minor releases may add new public endpoint families, package exports, CLI behavior, config fields, service routes, or experimental surface reshaping.
• Breaking changes in stable-for-0.x surfaces require a minor release, changelog entry, docs updates, and migration notes when relevant.
• Experimental surfaces may change in any minor, but never break silently in a patch unless the old behavior was unsafe or clearly invalid.

Related

• Public API surface
• Release policy
• Package map
• pywa parity matrix