Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk): list the leading-slash path refusal in the SDK design doc
Yudhi Armyndharis4321ee08abcd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 41dfca95a..5607d8f65 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -370,7 +370,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- The MCP guide says that message text, names and group subjects in tool results are written by other WhatsApp users, lists the settings that limit what an agent can do with them, says `POST /mcp` answers in SSE frames and needs `Accept: application/json, text/event-stream`, and sets up clients with a dedicated scoped key instead of the bootstrap admin key.- The plugin docs describe plugins loaded from disk as fully trusted and the worker as fault containment, matching `SECURITY.md`, list what a loaded plugin can still reach, point to the Compose override that disables `docker-proxy`, and say a plugin refused at boot is left out of `GET /api/plugins`, per-session config is deep-merged, `ctx.storage` is not session-scoped, and a `configUi` editor under the System theme should watch `prefers-color-scheme`.- The plugin search-provider guide describes backfill on whatsapp-web.js through `ctx.engine.getChats` and `getChatHistory` (at most 100 recent messages per chat, keyed by WhatsApp id), started per session from a `session:ready` hook so an interrupted backfill resumes and later-linked sessions are covered, and says a Baileys provider indexes live traffic only; its complete example registers as a provider as written, and it names the `storage:use` permission and says provider health is not exposed on a search route.-- The SDK docs list what the 0.5.0 registry builds lack: `getProxy`, `updateProxy` and `clickButton`, the webhook signature helpers and `WebhookDelivery` types, the API error code, retry-delay and headers accessors, the Java `UNKNOWN` fallback, the `sessions.list` `name` filter, the refusal of an empty, `.` or `..` id, the PHP `sessions->create()` empty-`config` fix and the PHP `catalog` null return; each SDK README names the ones its 0.5.0 build lacks.+- The SDK docs list what the 0.5.0 registry builds lack: `getProxy`, `updateProxy` and `clickButton`, the webhook signature helpers and `WebhookDelivery` types, the API error code, retry-delay and headers accessors, the Java `UNKNOWN` fallback, the `sessions.list` `name` filter, the refusal of an empty, `.` or `..` id and of a raw request path that does not begin with `/`, the PHP `sessions->create()` empty-`config` fix and the PHP `catalog` null return; each SDK README names the ones its 0.5.0 build lacks.- The horizontal-scaling and deployment guides and the Helm chart README describe API keys and the audit log as kept per node, give the real lease clock-skew margin and two-engine overlap bound, and no longer call session claims unimplemented.- The horizontal-scaling guide's hand-applied StatefulSet gets the chart's probe timeouts and startupProbe, checks liveness on `/api/health/live`, and sets `fsGroup: 997` instead of 1000; the guide says a forwarded request shares the owner's throttle bucket only when the peer is in `TRUSTED_PROXIES`, and its Docker Swarm example persists all of `/app/data` instead of only the sessions directory.- The quick rollback restores `main.sqlite` and the admin key file from the same backup as the data store and loads a PostgreSQL dump into an empty database, and its `rollback.sh` checks out the target version before restoring config, stops at the first failure, and stops on an external PostgreSQL server instead of restoring into a new local container.diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex 122e618c3..99f0f62f8 100644--- a/docs/18-sdk-design.md+++ b/docs/18-sdk-design.md@@ -45,7 +45,7 @@ All five SDKs expose the same fluent surface:| `media` | conversionStatus, convertVoice _(OPERATOR)_, convertVideo _(OPERATOR)_ || `health` | check, live, ready |-The tables describe `main`. The 0.5.0 registry builds do not include `sessions.getProxy`, `sessions.updateProxy` or `messages.clickButton` (`get_proxy`, `update_proxy` and `click_button` in Python; `GetProxy`, `UpdateProxy` and `ClickButton` in Go); they ship with the next SDK release. The webhook signature helpers (`verifyWebhookSignature`, `verify_webhook_signature`, `VerifyWebhookSignature`, `WebhookSignature.verify`, `WebhookSignature::verify`), the `WebhookDelivery` types and the API error code, retry-delay and headers accessors are not in 0.5.0 either; they also ship with the next SDK release. Nor is the Java fallback to `UNKNOWN`: 0.5.0 decodes a response enum value it does not recognise to `null` (`MessageType` and `ChatKind` included), and `SessionStatus`, `DeliveryStatus` and the other response enums that lack an `unknown` wire value have no `UNKNOWN` constant there. Nor is the `name` filter on `sessions.list` (`ListSessionsQuery.Name` in Go, the `name` field of `ListSessionsQuery` in Java, JavaScript and Python); it ships with the next SDK release. The refusal of an empty, `.` or `..` id (and, in the JavaScript, Go and Java raw-request methods, of a `.` or `..` path segment), the PHP `sessions->create()` fix that sends an empty `config` as `{}`, the PHP `allowInsecureHttp` option (0.5.0 always raises an `E_USER_WARNING` for a non-local `http://` `baseUrl`), and the PHP `catalog->info()` / `catalog->product()` `null` return on an empty body are not in 0.5.0 either; they ship with the next SDK release.+The tables describe `main`. The 0.5.0 registry builds do not include `sessions.getProxy`, `sessions.updateProxy` or `messages.clickButton` (`get_proxy`, `update_proxy` and `click_button` in Python; `GetProxy`, `UpdateProxy` and `ClickButton` in Go); they ship with the next SDK release. The webhook signature helpers (`verifyWebhookSignature`, `verify_webhook_signature`, `VerifyWebhookSignature`, `WebhookSignature.verify`, `WebhookSignature::verify`), the `WebhookDelivery` types and the API error code, retry-delay and headers accessors are not in 0.5.0 either; they also ship with the next SDK release. Nor is the Java fallback to `UNKNOWN`: 0.5.0 decodes a response enum value it does not recognise to `null` (`MessageType` and `ChatKind` included), and `SessionStatus`, `DeliveryStatus` and the other response enums that lack an `unknown` wire value have no `UNKNOWN` constant there. Nor is the `name` filter on `sessions.list` (`ListSessionsQuery.Name` in Go, the `name` field of `ListSessionsQuery` in Java, JavaScript and Python); it ships with the next SDK release. The refusal of an empty, `.` or `..` id (and, in the JavaScript, Go and Java raw-request methods, of a `.` or `..` path segment), the refusal by all five raw-request methods of a path that does not begin with `/`, the PHP `sessions->create()` fix that sends an empty `config` as `{}`, the PHP `allowInsecureHttp` option (0.5.0 always raises an `E_USER_WARNING` for a non-local `http://` `baseUrl`), and the PHP `catalog->info()` / `catalog->product()` `null` return on an empty body are not in 0.5.0 either; they ship with the next SDK release.> 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.@@ -409,7 +409,7 @@ try {- **Redirects are never followed.** The transport uses `redirect: 'manual'`, so a `3xx` surfaces to the caller as an error (via `OpenWAApiError`) rather than being followed — this guarantees the `X-API-Key` header is never re-sent to a redirect target (potentially a different origin).- **Auth and JSON headers take precedence.** Request headers are merged in the order `defaultHeaders` → per-call headers → `Content-Type: application/json` → `X-API-Key`. Both `Content-Type` and `X-API-Key` are applied last, so neither can be overridden by a caller-supplied header.- **Path segments are percent-encoded.** Ids (session, chat, message, etc.) are encoded so a value cannot break out of its path position, while keeping the WhatsApp-safe characters `@`, `:`, and `+` readable (e.g. `[email protected]`).-- **Empty and dot segments are refused.** An empty, `.` or `..` id rejects with a `TypeError` and nothing is sent, because `fetch` would otherwise resolve it to the parent resource. A raw `request()`/`requestBytes()` path with a `.` or `..` segment rejects with a `TypeError`; a trailing or double slash in a raw path is sent as written.+- **Empty and dot segments are refused.** An empty, `.` or `..` id rejects with a `TypeError` and nothing is sent, because `fetch` would otherwise resolve it to the parent resource. A raw `request()`/`requestBytes()` path with a `.` or `..` segment rejects with a `TypeError`, and so does one that does not begin with `/`; a trailing or double slash in a raw path is sent as written.- **Base-URL path prefix is preserved.** A `baseUrl` such as `https://gateway.example.com/v1` keeps its `/v1` prefix on every request; only a trailing slash is trimmed.- **No automatic retries.** A failed request rejects immediately — the SDK does not retry, even on `429`. Wrap calls in your own backoff if you need retries.- **Injectable transport.** Supply a custom `fetch` to wrap outbound calls with retry, logging, or observability middleware, or to run on a runtime without a global `fetch`. This is also the recommended way to unit-test without monkey-patching globals.@@ -781,7 +781,7 @@ except OpenWAApiError as e:- **Redirects are never followed.** `follow_redirects` is forced off so the `X-API-Key` header is never re-sent to a redirect target. An unfollowed `3xx` therefore surfaces as an `OpenWAApiError` rather than a success.- **Auth/JSON headers always win.** `default_headers` are applied first; the SDK then sets `Content-Type: application/json` and `X-API-Key`, so caller headers can never clobber them.- **Path segments are percent-encoded.** Each path value (session/chat/message id, etc.) is encoded so a `/`, `#`, or `?` can't break out of its position; already-safe id characters `@`, `:`, `+` are left readable. Boolean query params are serialized lowercase (`true`/`false`); `None` query values are dropped.-- **Empty and dot segments are refused.** An empty, `.` or `..` id raises `ValueError` before anything is sent, because httpx would otherwise resolve it to the parent resource.+- **Empty and dot segments are refused.** An empty, `.` or `..` id raises `ValueError` before anything is sent, because httpx would otherwise resolve it to the parent resource. A raw `request()` path that does not begin with `/` raises `ValueError` too.- **Base-URL path prefix is preserved.** A trailing `/` is stripped from `base_url`, but any path prefix (e.g. when running behind a reverse proxy) is kept on every request.- **No automatic retries.** Each call issues exactly one request; retry/backoff is the caller's responsibility. Wrap or inject a custom `transport` for retry or observability middleware.- **Testable transport injection.** Pass `transport=httpx.MockTransport(handler)` to intercept requests in tests — no global monkey-patching.@@ -1131,7 +1131,7 @@ try {- **Redirects are never followed.** Guzzle is configured with `allow_redirects => false`, so a `3xx` surfaces as an `OpenWAApiException` rather than being followed — the `X-API-Key` header is never re-sent to a redirect target.- **Auth/JSON headers take precedence.** `defaultHeaders` are merged in first, then `X-API-Key`, `Content-Type: application/json`, and `Accept: application/json` are applied on top, so they can't be clobbered.- **Path segments are percent-encoded.** Ids (session/chat/message/group ids) pass through `encodeSegment()`, which `rawurlencode`s the value but keeps the WhatsApp-id-safe characters `@`, `:`, and `+` readable — so a value containing `/`, `#`, or `?` cannot break out of its path position.-- **Empty and dot segments are refused.** An empty, `.` or `..` id throws `InvalidArgumentException` before anything is sent, because the HTTP stack would otherwise resolve it to the parent resource.+- **Empty and dot segments are refused.** An empty, `.` or `..` id throws `InvalidArgumentException` before anything is sent, because the HTTP stack would otherwise resolve it to the parent resource. A raw `request()` path that does not begin with `/` throws `InvalidArgumentException` too.- **Base-URL path prefix is preserved.** The base URL has its trailing `/` trimmed and requests are issued against an absolute `baseUrl . $path`; Guzzle's `base_uri` is intentionally unset, so a prefix like `/v1` behind a reverse proxy is retained.- **Null query values are dropped.** Absent optional query parameters (`null`) are filtered out before the request, so they are never sent.- **No automatic retries.** A failed request throws immediately; wrap calls in your own backoff if you need retries (notably for `429`). The injectable `httpClient` is the extension point for retry/observability middleware.