Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk): mark main-only SDK additions in the changelog and design doc
Yudhi Armyndharis303b9c416484
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 259e31cc4..50f48c3e5 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,12 +12,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Allow chat-restricted API keys to subscribe to chat WebSocket events.- Allow chat-restricted MCP keys to read and send within their chat allowlist using the REST authorization rules.- Carry `chatId` in `message.ack` and `message.failed` payloads so a webhook `chatId` or `kind` filter scopes delivery events per chat.-- Filter stored messages by time, direction, type or message reference, with stable message-time pagination.+- Filter stored messages by time, direction, type or message reference, with stable message-time pagination; the SDKs take these filters from the next SDK release after 0.5.1.- Scope built-in message search and group detail/settings to a chat-restricted key's allowed chats; reject plugin search for these keys.-- Expose poll choices and selection mode in message events, stored messages, history, and dashboard chats.-- Expose optional last-message types in chat lists and SDKs.-- Add bounded webhook failure redrive with optional payload retention.-- Expose caller-supplied send idempotency keys in all five SDKs.+- Expose poll choices and selection mode in message events, stored messages, history, and dashboard chats; the SDKs type them from the next SDK release after 0.5.1.+- Expose optional last-message types in chat lists and, from the next SDK release after 0.5.1, in the SDKs.+- Add bounded webhook failure redrive with optional payload retention; the SDKs expose it from the next SDK release after 0.5.1.+- Expose caller-supplied send idempotency keys in all five SDKs from the next SDK release after 0.5.1; the 0.5.1 JavaScript and PHP packages ignore the extra argument.- Add optional 24-hour idempotency keys to twelve single-recipient send routes.- Add opt-in archive-only chat media with dashboard previews.- Report RSVPs to WhatsApp events as an `event.response` webhook and WebSocket event on Baileys (#1788, thanks @jelasus).diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex 79a9fd856..e999c0487 100644--- a/docs/18-sdk-design.md+++ b/docs/18-sdk-design.md@@ -1,5 +1,7 @@# 18 - SDK Design+> This document describes `main`. Send idempotency, webhook failure redrive, message-window filters, poll choices, and last-message types are unreleased additions after SDK 0.5.1 and require the corresponding server changes after OpenWA 0.24.0.+## 18.1 OverviewOpenWA ships five official, hand-written client libraries for the REST API. They are not generated from an OpenAPI spec — each is written directly against the real API surface (paths, request DTOs, response shapes) and **unit-tested with a mocked HTTP transport that asserts on the exact request path, method, and body**, so drift in what an SDK _sends_ is caught at test time rather than in production. That mechanism says nothing about what an SDK expects _back_; see §18.6 for how response shapes are held to the contract.@@ -45,6 +47,8 @@ All five SDKs expose the same fluent surface:| `media` | conversionStatus, convertVoice _(OPERATOR)_, convertVideo _(OPERATOR)_ || `health` | check, live, ready |+The twelve single-recipient send methods (text, image, video, audio, document, sticker, location, contact, template, poll, reply and forward) take an optional per-call idempotency key: a trailing argument in JavaScript, PHP and Java, `idempotency_key=` in Python and `openwa.WithIdempotencyKey(ctx, key)` in Go. A retry of the same logical send reuses its key; see each SDK's README.+> The SDKs cover the user-facing resources above and stop there. The administrative and operational surfaces are deliberately left out — `auth/api-keys`, `audit`, `settings`, `stats`, `automation`, `infra`, `plugins` and the `integration` management routes are predominantly `ADMIN`-gated; `metrics` is a `@Public()` Prometheus scrape gated by `METRICS_TOKEN` rather than by role; `mcp` is a Streamable-HTTP transport mounted straight onto the Express adapter; and `ingress` is the `@Public()` receiver that integration providers post into. `docker` has no HTTP surface at all — it is an internal service module. Methods that require an `OPERATOR`-level key are annotated **OPERATOR** in the per-language tables below.## 18.2 TypeScript / JavaScript SDK@@ -1182,4 +1186,4 @@ cd sdk/python && python -m pytest -qcd sdk/php && composer install && ./vendor/bin/phpunit```-CI runs all five suites (`sdk-ci.yml`), path-filtered to `sdk/**` plus the server-side contract surfaces the SDKs are written against — `src/**/dto/**`, `src/**/*.controller.ts`, `src/**/*.service.ts` and `whatsapp-engine.interface.ts` — so a change to the wire contract re-runs them. The PHP package is mirrored to its own Packagist repository via a `git subtree split`, and that mirror publish is gated on the PHP tests passing, so a broken SDK cannot auto-publish. Bump the version, record the change in the root `CHANGELOG.md` `[Unreleased]` section prefixed with the SDK's name (for example `Java SDK:`), drop the methods it ships from the unreleased note in §18.1, `sdk/README.md` and the "This README describes `main`" note near the top of that SDK's own README, run the suite above, then tag/publish to the relevant registry.+CI runs all five suites (`sdk-ci.yml`), path-filtered to `sdk/**` plus the server-side contract surfaces the SDKs are written against — `src/**/dto/**`, `src/**/*.controller.ts`, `src/**/*.service.ts` and `whatsapp-engine.interface.ts` — so a change to the wire contract re-runs them. The PHP package is mirrored to its own Packagist repository via a `git subtree split`, and that mirror publish is gated on the PHP tests passing, so a broken SDK cannot auto-publish. Bump the version, record the change in the root `CHANGELOG.md` `[Unreleased]` section prefixed with the SDK's name (for example `Java SDK:`), drop the methods it ships from the note at the top of this document, `sdk/README.md` and the "This document describes `main`" note near the top of that SDK's own README, run the suite above, then tag/publish to the relevant registry.