# Changelog All notable changes to `wa-agent` are documented here. This project follows [Keep a Changelog](https://keepachangelog.com/) conventions; versions are not yet under strict semver — the shapes are stable but treat the surface as 0.x. ## [0.19.1] — 2026-08-12 ### Security **`MetaEmbeddedSignup.complete()` trusted caller-supplied `wabaId` / `phoneNumberId` without verifying them.** Those ids arrive from a browser, and a multi-tenant app maps `phone_number_id → tenantId`; an authenticated user of your app could post another business's `phone_number_id`, have it persisted against their own tenant, and start receiving that business's inbound WhatsApp. Inbox takeover (IDOR). Anyone on v0.19.0 calling `complete()` with ids from the client should upgrade. v0.19.0 was live for roughly one hour. - **`complete()` now verifies by default.** It enumerates the (WABA, phone number) pairs the exchanged token authorizes and validates any supplied ids against that allowlist, throwing `asset_not_authorized` (with both sides in `detail`) on a miss. The failure happens before `subscribed_apps` — a takeover attempt never reaches a write. - **New `listAuthorizedAssets(exchangedToken)`** returns those pairs as `AuthorizedAsset[]`. It uses **exactly** the token passed and refuses to fall back to `systemUserToken`: a System User token can see every number in the app, so enumerating with it would authorize the takeover rather than block it. - **Token roles are now separated.** `graphJson` sends exactly the token its caller chose; `systemUserToken` still wins for operational calls made after authorization is settled (subscribe, register) via the private `tokenFor`. Before this, the system token silently overrode the exchanged token on every WABA-scoped call. - **`selectAuthorizedAsset(assets, hint)`** exported — the matching rules (exact pair / phone only / WABA only / discovery) as a pure function, for apps running their own connect endpoint. - **`result.authorizedAssets`** added: the evidence that the connecting user owned the number, worth persisting alongside the tenant row. - **New error codes:** `asset_lookup_failed`, `no_authorized_assets`, `asset_not_authorized`. - **`trustSuppliedAssets: true`** opts out, for apps that source the ids through a channel they control end-to-end. Documented as unsafe; it only applies when both ids are present. Credit: the vulnerability and the shape of the fix come from psico's own `aaba824` ("Fix IDOR in /api/wa/connect: verify assets against exchanged token"). v0.19.0 was generalized from that repo's older OAuth-redirect handler, which predated the hardening — the newer connect endpoint wasn't read. ### Changed - `complete()` no longer calls `listWabas` / `listPhoneNumbers`; both paths (discovery and verification) go through `listAuthorizedAssets`. The two helpers remain exported for standalone use, and now send exactly the token passed to them. - `result.wabas` / `result.phoneNumbers` are populated on the JS SDK path too (derived from the authorized set), where v0.19.0 returned empty arrays. ### Tests 1360 → **1376 passing** (16 new): the IDOR guard (cross-WABA pairs, unauthorized phone, unauthorized WABA, exchanged-vs-system token assertion, failed lookup not falling through to trust, the opt-out) plus `selectAuthorizedAsset` as a unit. ### Notes Behavior change in a patch release, deliberately: the safe default is worth more than compatibility with a call that shouldn't have worked. Apps that were passing ids the token genuinely authorizes see no difference beyond one extra Graph call. ## [0.19.0] — 2026-08-12 ### Added The Tech Provider surface. Everything a multi-tenant app needs between "customer clicks connect" and "their messages route to the right Agent" — plus the webhook fields Meta delivers when that customer keeps answering from their phone. Extracted from psico, generalized: nothing here knows what your tenants sell. - **`MetaEmbeddedSignup`** (`src/signup/embedded_signup.ts`) — the Embedded Signup handshake as one class. Exchanges the one-time `code` for a token, discovers the WABA + phone number, subscribes your app to the WABA's webhooks, and optionally registers the number with the Cloud API. Supports both flows Meta ships: pass `wabaId` / `phoneNumberId` from the JS SDK's `sessionInfoResponse` to skip discovery, or configure `stateSecret` and use `authUrl()` / `complete()` for the OAuth redirect. State is signed HS256 with a 10-minute expiry and a nonce; when `stateSecret` is set, `complete()` requires a valid state and throws before touching the network. ```ts const signup = new MetaEmbeddedSignup({ appId: env.META_APP_ID, appSecret: env.META_APP_SECRET, redirectUri: `${env.PUBLIC_BASE_URL}/wa/signup/callback`, systemUserToken: env.META_SYSTEM_USER_TOKEN, }); const result = await signup.complete({ code, wabaId, phoneNumberId }); ``` Every failure path throws `EmbeddedSignupError` with a stable `code` (`invalid_state`, `token_exchange_failed`, `waba_lookup_failed`, `no_waba_found`, `phone_lookup_failed`, `no_phone_number`, `subscribe_failed`, `register_failed`) plus the HTTP `status` and parsed Graph `detail`. A failed subscribe throws rather than returning a half-connected tenant — persisting a number whose webhooks you don't receive produces a customer who thinks they're live and isn't. `fetchImpl` and `now` are injectable; `graphBase` defaults to the framework's Graph version and can be overridden per env. - **`createD1TenantResolver({db, kv?, ...})`** (`src/multi_tenant/tenant_resolver.ts`) — the `phone_number_id → tenantId` lookup every multi-tenant app hand-writes, returned as the exact callbacks the multi-tenant surface expects: `resolveTenantId` (registry), `enumerateTenants` (registry + cron), `anyTenantForVerify` (`mountMultiTenantWebhook`), plus `resolveByPhoneNumberId` and `invalidate`. KV-cached (1h default), table and column names configurable and validated as bare identifiers. Misses are **not** cached by default — a number missing from your table usually means signup is mid-flight, and caching that costs you the first real message; opt in with `negativeCacheTtlSeconds` when unknown-number floods are burning D1 reads. D1 failures return `null` and are never cached as a miss, so an outage can't poison the cache for an hour. ```ts const tenants = createD1TenantResolver({ db: (env) => env.DB, kv: (env) => env.KV }); const registry = new MultiTenantAgentRegistry({ ...tenants, buildAgent }); mountMultiTenantWebhook(registry, app, '/wa', { anyTenantForVerify: tenants.anyTenantForVerify }); ``` - **Coexistence webhook parsing** (`src/webhook/coexistence.ts`) — `partitionCoexistenceWebhook`, `extractEchoes`, `extractCoexistenceChanges`, `isCoexistenceWebhook`, `isCoexistenceField`, `COEXISTENCE_FIELDS`. When a number runs the WhatsApp Business app alongside the Cloud API, Meta delivers `smb_message_echoes`, `history`, and `smb_app_state_sync` next to `messages`. None carry the `contacts` + `messages` pair `extractInbound` expects, so before v0.19 they arrived and were silently dropped. `partitionCoexistenceWebhook` splits them from the enqueueable remainder; `extractEchoes` normalizes echoes to `{wamid, phoneNumberId, to, from, type, text, timestampMs, raw}` (text reads the body, or the caption on media echoes). `history` / `smb_app_state_sync` values pass through raw — they're large, versioned by Meta, and what's worth persisting is app-specific. - **`HumanHandoffWindow`** (`src/handoff/human_handoff.ts`) — the behavior every coexistence deployment needs: when the human answers from their phone, the agent backs off. KV-backed window (15 min default), one key per thread, TTL does the expiry. `markFromEchoes(echoes)` marks every thread an echo touched; `guard()` returns a `GuardFn` for `agent.guard(...)` that silences the turn while the window is open. ```ts const handoff = new HumanHandoffWindow({ kv: env.KV, tenantId }); agent.guard(handoff.guard()); mountWebhook(agent, app, '/wa', { onCoexistence: async ({ echoes }) => { await handoff.markFromEchoes(echoes); }, }); ``` Register safety guards **before** the handoff guard — guards short-circuit on the first denial, and a crisis reply outranks silence. Cloudflare KV enforces a 60-second minimum TTL; shorter windows are clamped up rather than failing at runtime. `markFromEchoes` accepts `resolveTenantId` for apps that share one instance across tenants. - **`onCoexistence` option on `mountWebhook` and `mountMultiTenantWebhook`** — runs after signature verification and before enqueue, receiving `{env, tenantId, changes, echoes, envelope}`. Coexistence changes are stripped from what reaches `Agent.enqueue`: a mixed envelope still enqueues its ordinary messages, a coexistence-only envelope enqueues nothing. Handler throws are caught and logged so Meta still gets its 200 — replaying a whole envelope over one failed echo makes things worse. - **`registry.invalidate(tenantId)` + `MemoryAgentCache.delete(tenantId)`** — evict one tenant's cached Agent so the next turn rebuilds it from current config (policy edit, agent-mode switch, reconnected number). Previously the only escape was waiting for the isolate to recycle. `AgentCache.delete` is optional on the interface, so caches written against the v0.6 shape keep type-checking; `invalidate` returns `false` when it can't evict. ### Docs - **New: `docs/COEXISTENCE.md`** — what coexistence is, the double-reply problem, the `onCoexistence` + `HumanHandoffWindow` wiring, `MessageEcho` reference, guard ordering, and the anti-patterns (treating an echo as inbound, a window with no expiry, keying handoff off `from` instead of `to`). - **New: `docs/EMBEDDED_SIGNUP.md`** — decision tree between the JS SDK and redirect flows, both wirings end-to-end, the error taxonomy table, `createD1TenantResolver` reference, and the two caches to invalidate after every signup. - **`docs/README.md`** — both docs linked in Guide, the by-version table, and a new "I'm a Tech Provider onboarding customers' own numbers" persona path. - **`README.md`** — v0.19.0 Status entry. ### Tests 1250 → **1360 tests passing** across 108 files (110 new): `coexistence` (19), `human_handoff` (22), `embedded_signup` (33), `tenant_resolver` (24), `mount_webhook_coexistence` (12, covering both mounts + cache invalidation). All four new modules are pure logic and added to `stryker.config.json`. Mutation scores: `coexistence` 89.7%, `human_handoff` 90.5%, `tenant_resolver` 80.9%, `embedded_signup` 80.2%. ### Notes Additive-only; no API breakage and no migration. An envelope with no coexistence field takes the pre-v0.19 path unchanged, `onCoexistence` is opt-in, and omitting it preserves the old behavior (coexistence changes dropped). No new dependencies — `MetaEmbeddedSignup` is `fetch` + the existing `signJwt`/`verifyJwt` primitives, `HumanHandoffWindow` is KV. ## [0.18.0] — 2026-07-28 ### Added Three additive bridges that finish the provider-agnostic story. `openai` becomes fully optional — no primitive in the framework requires it anymore. `AgentLoop` now composes with `Agent.ai` instead of replacing it. All new classes live in the `wa-agent/ai-sdk` subpath (except the bridge), so the `ai` peer stays optional; consumers pay for it only if they import them. - **`AISDKSummarizer`** (`src/ai_sdk/summarizer.ts`, exported from `@emerleite/wa-agent/ai-sdk`) — provider-agnostic `SummarizerLike` implementation via AI SDK's `generateText`. Drop-in replacement for the classic `Summarizer` (OpenAI-only). Same defaults (4 bullets, source-language preservation, 400 max tokens, 0.3 temp) but works with any Vercel AI SDK `LanguageModel`. Fail-soft: returns `null` on empty input, provider error, or empty response. ```ts import { AISDKSummarizer } from '@emerleite/wa-agent/ai-sdk'; import { anthropic } from '@ai-sdk/anthropic'; const summarizer = new AISDKSummarizer({ model: anthropic('claude-haiku-4-5') }); ``` - **`AISDKTranscriber`** (`src/ai_sdk/transcriber.ts`, exported from `@emerleite/wa-agent/ai-sdk`) — provider-agnostic audio transcription via AI SDK's `experimental_transcribe`. Drop-in replacement for `Transcriber` (which called Whisper through the `openai` SDK's `toFile` helper). Accepts `ReadableStream | Uint8Array | ArrayBuffer`, forwards optional `providerOptions` per the SDK's transcription-model contract, fail-soft on error / empty text. ```ts import { AISDKTranscriber } from '@emerleite/wa-agent/ai-sdk'; import { openai } from '@ai-sdk/openai'; const transcriber = new AISDKTranscriber({ model: openai.transcription('whisper-1'), providerOptions: { openai: { language: 'pt' } }, }); ``` **This removes the last hard tie to the `openai` SDK.** The classic `Transcriber` still works; new code should reach for `AISDKTranscriber` and route Whisper through `@ai-sdk/openai` (or Groq/Fireworks/Together/…). - **`agentLoopAsAIClient(opts)`** (`src/agent_loop/as_ai_client.ts`, exported from the core `@emerleite/wa-agent`) — bridge that exposes an `AgentLoop` as an `AIClient`, so `Agent.ai` + `reply.ai(text)` can run the loop under the hood. Before v0.18 the migration from `OpenAIAssistant` to `AgentLoop` forced consumers to abandon `reply.ai(text)` and drive replies manually. Now: ```ts import { Agent, AgentLoop, ConversationMemory, ToolRegistry, agentLoopAsAIClient } from '@emerleite/wa-agent'; import { createAISDKAgentLLM } from '@emerleite/wa-agent/ai-sdk'; import { openai } from '@ai-sdk/openai'; const loop = new AgentLoop({ llm: createAISDKAgentLLM(openai('gpt-4o-mini')), tools: new ToolRegistry([/* … */]), memory: new ConversationMemory({ db: env.DB }), }); const agent = new Agent({ whatsapp: { /* ... */ }, db: env.DB, ai: agentLoopAsAIClient({ loop, systemPrompt: SYSTEM_PROMPT, context: ({ threadId }) => ({ env, whatsapp: threadId }), }), }); agent.onText(async ({ text, reply, session }) => { await reply.ai(text, { threadId: session?.threadId }); // now routes through AgentLoop }); ``` `systemPrompt` accepts a function form so per-thread system prompts can be composed at call time. `context` builds a per-call tool context. `runOverrides` supplies `tenantId` / `stopWhen` / `signal` per call. `threadIdFallback` defaults to `crypto.randomUUID()`. ### Docs - **`docs/PROVIDER_STRATEGY.md`** — the three new symbols slotted into the layer diagram and the peer-dep table. `openai` peer moves from "required for `Transcriber` / `OpenAIAssistant`" to "only if you use `Transcriber` / `OpenAIAssistant` — `AISDKTranscriber` doesn't need it". - **`docs/AGENT_LOOP.md`** — new "Bridging `AgentLoop` into `Agent.ai`" section covering the `agentLoopAsAIClient` recipe; the OpenAIAssistant migration section now points at the bridge as an alternative to refactoring away from `reply.ai(text)`. - **`README.md`** — v0.18.0 Status entry. - **`docs/README.md`** — by-version table gains v0.18.0. ### Tests 1227 → **1250 tests passing** across 103 files (23 new): `aisdk_summarizer` (6), `aisdk_transcriber` (9), `agent_loop_as_ai_client` (8). ### Notes Zero API breakage. `Summarizer` / `Transcriber` / `OpenAIAssistant` all still work. The classic `Summarizer` and `Transcriber` are not deprecated — they remain the shortest path for consumers who already have the `openai` SDK wired. ## [0.17.1] — 2026-07-28 ### Docs Provider-strategy documentation refresh. No code changes beyond a JSDoc `@deprecated` note. - **New: `docs/PROVIDER_STRATEGY.md`** — decision tree covering the three provider-agnostic layers (`AIClient` / `AgentLoop` / `AIRouter`), full compatibility table with **LiteLLM proxy + Ollama + LM Studio** as first-class fits for `OpenAICompatProvider`, peer-dep breakdown (nothing is required — only pulled in by the specific primitive you use), and recipes for common swaps ("OpenAI → Anthropic in one import", "Ollama for dev, cloud for prod", "per-tenant provider override without redeploy"). - **`docs/AGENT_LOOP.md` — new "Migrating from `OpenAIAssistant`" section** with a before/after code diff. `OpenAIAssistant` (Assistants API, proprietary to OpenAI + Azure) is the only genuine vendor lock-in the framework ships; the migration path to `AgentLoop` + `@emerleite/wa-agent/ai-sdk` is a refactor to swap providers with a one-import change. - **`docs/AI_ROUTER.md` — explicit LiteLLM proxy + Ollama recipes** in a dedicated section. Points at `PROVIDER_STRATEGY.md` for the full picture. - **`docs/README.md`** — new entry in the Guide category; by-version table gains v0.17.0 + v0.17.1. - **README.md** — v0.17.1 Status entry. ### Changed - **`OpenAIAssistant` soft-deprecated** via `@deprecated` JSDoc on the class. The class continues to work; there is no removal timeline. TypeScript surfaces the deprecation warning to consumers on upgrade. Recommended replacement is `AgentLoop` + `@emerleite/wa-agent/ai-sdk`, which is provider-agnostic across 15+ AI SDK providers. ### Notes Zero API surface changes. Same 1227 tests passing. This release exists to make the lock-in story browsable — the framework was already provider-agnostic; the docs didn't say so loudly enough. ## [0.17.0] — 2026-07-28 ### Added - **`agent.onImage` / `onAudio` / `onVideo` / `onDocument` / `onSticker` / `onLocation` / `onContacts`** — first-class media handlers on `Agent`. Pre-v0.17 the only way to handle non-text media was `agent.on('onMessage', ...)` + a manual `switch (inbound.type)`. Every non-text-only bot reimplemented the switch — aysu still does today. Now: `agent.onImage(async (ctx) => await pipeline(env, ctx))`. Wired into `dispatch()` so `commands` still owns text/audio-with-transcript; media handlers own the rest. Registering the same media type twice replaces the previous handler (last-wins). - **`agent.guard(fn)` pre-dispatch guard** — allow/deny hook that runs after `onMessage` lifecycle hooks and before button/command/media dispatch. `fn` returns `null` to allow or `{reply?: string, silent?: boolean}` to deny. When denied and `reply` is set (and `silent` is falsy), the framework sends the reply before short-circuiting. First denying guard wins; later guards are not consulted. Distinct from `Blocklist` (hard-drop with no reply) — this is the "trial expired / paywall / geo-gate" pattern where you want to tell the user what happened. - **`WhatsAppClient.sendUtilityTemplate(to, {name, language?, bodyParams?, urlButtonSuffix?, buttonIndex?})`** — Meta UTILITY-category template sender. Sibling of `sendAuthenticationTemplate` (v0.16). Composes body-params + optional URL-button suffix in the shape Meta expects. Body-only, button-only, and both-together templates all supported. See [`docs/META_SETUP.md`](docs/META_SETUP.md) for the template registration flow. - **`createD1ChainResolver({db, fallback?, tableName?, taskColumn?, chainColumn?, cacheMs?})`** — D1-backed runtime override for `AIRouter.resolveChain`. Reads `(task, chain)` from a D1 table (default `ai_provider_overrides`), falls back to a secondary resolver (typically `envChainResolver(env)`) on cache miss. Per-isolate cache with configurable TTL (default 60s) — hot-path calls are a Map lookup, not a D1 query. Table names + columns are validated as bare identifiers (SQL string is not parameterizable). Complements `envChainResolver` (env-var only) for consumers who want per-tenant / A/B / on-the-fly overrides without a deploy. - **`withTenant(tenantId, tenantColumn, ...extraWhere)`** in `@emerleite/wa-agent` — Drizzle helper for multi-tenant row-level enforcement. Composes `WHERE tenant_id = ? [AND ...]`. Lint-checkable pattern: consumers can write a Biome/ESLint rule that fails when a query touches a tenant-scoped table without `withTenant`. Extracted from psico. - **`@emerleite/wa-agent/testing` subpath export** with `withIsolatedD1()` — per-test D1 isolation helper for consumers writing integration tests. Registers vitest `beforeEach` + `afterEach` hooks that apply framework migrations and drop non-system tables between tests. `vitest` and `@cloudflare/vitest-pool-workers` become optional peers of the framework (only pulled in when consumers import the testing subpath). Consolidates the recipe previously copy-pasted from `docs/TESTING.md`. ### Notes Additive release; no API breakage. The new `Agent` methods (`onImage`/`guard`/…) return the instance for chaining, consistent with `command`/`button`/`onText`. `AIRouter.resolveChain` already accepted `Promise`, so `createD1ChainResolver` slots in without any changes to the router itself. New optional peer dependencies: - `vitest` (`^2.0.0 || ^3.0.0`) — only when importing `@emerleite/wa-agent/testing` - `@cloudflare/vitest-pool-workers` (`^0.5.0`) — same ### Tests 1184 → **1227 tests passing** across 100 files (43 new): `agent_media_and_guards` (13), `send_utility_template` (8), `d1_chain_resolver` (10), `with_tenant` (5), tsc unit adjustments (+7). ## [0.16.2] — 2026-07-28 ### Added - **`package.json` metadata for the npm package page**: `repository`, `bugs`, `homepage`, `author`. The npm registry now renders a "Repository" link to the GitHub project, an "Issues" link to the tracker, and a "Homepage" link to the README. Previously the package page had no cross-links to source or issues. ### Ops - **`.github/workflows/ci.yml`** — CI on every PR + push to `main`. Runs `typecheck`, `check:hardcoded`, `build`, and the full test suite on Node 22. Concurrency-cancelled per ref. - **`.github/workflows/publish.yml`** — publishes to npm on any `v*.*.*` tag push. Gates on tag matching semver form + `package.json.version`, then runs the ship-it checklist, then `npm publish --access=public --provenance` (OIDC-attested via GitHub `id-token` permission). Requires `NPM_TOKEN` repo secret with 2FA-bypass enabled. - **`package-lock.json`** committed to the repo (was gitignored) so `npm ci` in the CI workflows can install exact resolved versions. Modern guidance for libraries — the lockfile is a dev / CI reproducibility artifact and does not affect what consumers install. - **`CLAUDE.md` + `docs/CONTRIBUTING.md`** — release checklist rewritten around the tag-push automation. One-time repo setup docs added for the `NPM_TOKEN` granular access token. ### Notes First release published via the automated GitHub Actions workflow. Behavior unchanged; no API surface changes; no test count change. ## [0.16.1] — 2026-07-28 ### Fixed - **`LLMClassifier.classify` — `routerError` now falls through empty error messages.** When the router returned `{ok: false, errorMessage: '', errorKind: 'timeout'}`, the result's `routerError` was `''` — unhelpful. Now falls through to `errorKind`. Small behavior change; the old behavior was arguably a bug. ### Docs Comprehensive coverage refresh for v0.14–v0.16 primitives that previously lived only in the CHANGELOG. Every one of the 21 new symbols now appears in a browsable doc. - **New:** `docs/LLM_CLASSIFIER.md` — decision tree, custom parse/template, three-tier fallback recipe, anti-patterns for the v0.15 primitive. - **New:** `docs/MEDIA.md` — end-to-end media story consolidating `R2Cache` (v0.4) + `R2MediaStore` (v0.12) + `ingestMedia` + `MediaStorage` interface (v0.15). Decision tree at top; photo→R2→vision + LGPD erasure recipes. - **New:** `docs/QUEUE.md` — `D1CoalesceQueue` per-user dispatch (v0.14 `processBatchForUser` / parallel `processAll`), same-user race documented, tenant scoping, full webhook + cron wiring. - **Updated:** `docs/UTILITIES.md` — grew from 273 → 519 lines. 7 new sections: `phoneLookupCandidates`, `Streak` (day-math), `resolveReplyContext`, `classifyDbError`/`logDbError`, `landingHtml`/`landingResponse`, `PT_BR_INTENT_TRIGGERS`/`matchPtBrIntent`, `PROVIDER_LIMITS`/cost estimator. - **Updated:** `docs/SECURITY.md` — new "Authentication template" section for `sendAuthenticationTemplate` (v0.16), plus a full end-to-end OTP flow recipe combining v0.13 crypto + v0.16 template + v0.13 cookies. - **Updated:** `docs/META_SETUP.md` — new "Status updates + `pricing.category`" section (v0.15) explaining the UTILITY→MARKETING reclassification alarm surface + `extractStatuses` shape. New "Creating an AUTHENTICATION template" section pointing at `SECURITY.md`. - **Updated:** `docs/AI_ROUTER.md` — new "Azure reasoning + vision models" section (`maxTokensField`, `omitTemperature`, `images`) and "`extraLogFields` hook" section (v0.16). - **Updated:** `docs/README.md` — index refresh. New docs in Guide + Recipes categories. By-version table + by-persona entries updated. - **Updated:** `README.md` — Status section grew v0.14/v0.15/v0.16 entries. Recipe docs list refreshed with cross-links. ### Ops - **`CLAUDE.md`** at repo root — non-negotiables (testing convention, migrations, release format, working style) that Claude Code loads automatically at every session start. Consolidates rules previously spread across `docs/CONTRIBUTING.md` and Claude memory. - **`stryker.config.json`** — added the 19 v0.12–v0.16 pure-logic modules that had 100% unit coverage but had never been mutation-tested (`phone_br`, `whatsapp_format`, `llm_json`, `log`, `state_block`, `streak`, `reply_context`, `db_error`, `og_landing`, `pt_br_intents`, `provider_limits`, `llm_classifier`, `safety_footer`, `r2_media_store`, `media_pipeline`, `admin_auth`, `crypto`, `cookie`, `tracer`). ### Tests 1141 → **1184 tests passing** across 96 files (43 new). Mutation score improvements on the six modules previously below 75% coverage: | Module | Before | After | Δ | |---|---|---|---| | `og_landing` | 68.97 | 86.21 | +17.2 | | `llm_classifier` | 60.82 | 73.74 | +12.9 | | `pt_br_intents` | 70.00 | 80.00 | +10.0 | | `crypto` | 77.14 | 85.71 | +8.6 | | `safety_footer` | 68.97 | 72.41 | +3.4 | | `admin_auth` | 73.33 | 76.67 | +3.3 | Overall mutation score 66.35 → 67.09; `covered` metric 79.97 → 80.77. ### Notes Patch release. No new public API. `LLMClassifier`'s tweaked fallback behavior is the only observable change and only for the empty-error-message corner case. ## [0.16.0] — 2026-07-28 ### Added - **`WhatsAppClient.sendAuthenticationTemplate(to, code, {name, language?, buttonIndex?})`** — Meta AUTHENTICATION-category OTP flow. Encodes the non-obvious rule that the OTP code MUST appear in BOTH the body parameter AND the URL button parameter — miss one and the "Copy code" button doesn't populate. Pairs with v0.13's `generateOtpCode` + `hashOtpCode` for a complete portal-OTP flow. - **`landingHtml(opts)` + `landingResponse(opts)`** (`src/util/og_landing.ts`) — minimal OpenGraph-enriched HTML landing page. Renders a `/` that Meta's WhatsApp crawler reads for URL-button preview cards, with an optional human meta-refresh to your real site. All user-supplied fields HTML-escaped. From zap-prime `admin/landing.ts`. - **`makeSafetyFooterEnricher({triggers, footer, alreadyMentioned?})`** (`src/ai/safety_footer.ts`) — generic factory for the deterministic-safety-footer pattern (LLM was supposed to inject a safety line and didn't — you inject it post-hoc, idempotently). Consumers configure the trigger regex (against input) + the footer text + optionally the "already mentioned" regex (against output). No PT-BR or CVV assumptions in the framework version. Generalizes bibliafala's `safety_check.js`. ### Changed - **`AIRouter.route({extraLogFields})`** — new optional hook that fires ON SUCCESS with the winning provider's raw response and returns extra ledger columns. Right for inlining classifier category / intent / route tag into `ai_call_log` without a follow-up UPDATE. Errors from the callback are swallowed (tracing failure never fails the route). Extra keys must appear in the ledger's `allowedExtraColumns` — no schema surprises. ### DX - `scripts/wrangler-test-strip.sh` was considered (per bibliafala `scripts/run-tests.mjs`) but the pattern is bibliafala-specific (Workers AI binding stripping for local vitest). Deferred — consumers with the same need copy the pattern; the framework doesn't need to bundle it. ### Notes Additive release. No API changes; consumers on 0.15.x pick up new symbols by upgrading. `AIRouter.extraLogFields` is opt-in — omitting it preserves pre-v0.16 behavior bit-for-bit. ### Tests 1121 → **1141 tests passing** across 96 files (20 new): `og_landing` (8), `safety_footer` (7), `auth_template` (3), `extract_statuses` (+2 in v0.15). Typecheck clean; build clean. ## [0.15.0] — 2026-07-28 ### Added - **`LLMClassifier`** (`src/ai/llm_classifier.ts`) — thin wrapper over `AIRouter` for the classify → parse → fallback pattern. Constructor takes `router`, `chainName`, `systemPrompt`, `categories`, `fallback` + optional `userTemplate` / `parse` / `maxTokens` / `temperature`. Default parser accepts both strict JSON (`{"categoria":"X"}` or `{"category":"X"}`) and a loose regex; default userTemplate wraps the input in `...` (bibliafala's 100-message-validated pattern). Fail-closes to `fallback` on router error, parse failure, or unknown category. Codifies the shape bibliafala and aysu both hand-rolled. - **`resolveReplyContext({inReplyToWamid, whatsapp, byReplyWamid, byRecency, withinMinutes})`** (`src/util/reply_context.ts`) — resolve an inbound WhatsApp message to a bot-owned entity via (a) explicit reply pointer or (b) recency-window fallback. Reply pointer wins over recency. Generalizes aysu's `getMealByReplyWamid` + `findRecentMeal` composition — any "edit the last X" flow (orders, bookings, meals, tickets) fits. - **`ingestMedia({client, mediaId, store, scope, id})`** + **`MediaStorage`** interface (`src/media/media_pipeline.ts`) — one-call download + upload for Meta media. Uses `WhatsAppClient.downloadMediaWithMeta` for the auth'd two-hop dance, hands the bytes + Meta-provided `mime_type` to any `MediaStorage`. `R2MediaStore` (v0.12) already matches the interface; consumers wanting KV / S3 / custom storage implement the same `upload({scope, id, body, contentType})` shape. - **`WhatsAppClient.downloadMediaWithMeta(mediaId)`** — variant of `downloadMedia` that also returns `{stream, mimeType, sha256, fileSize}`. Right for pipelines that need the real content-type instead of guessing (zap-prime's ingestPhoto pattern). - **`extractStatuses(envelope)` + `StatusUpdate` type** (`src/webhook/extract.ts`) — normalize Meta's `statuses[]` array to `{wamid, status, pricingCategory, timestampMs, recipient, errors}`. The `pricingCategory` field is the surface for the UTILITY→MARKETING reclassification alarm every template-heavy bot needs. Complements `extractInbound` (message path). - **`classifyDbError(e)` + `logDbError(scope, method, e)`** (`src/util/db_error.ts`) — D1 / SQLite error taxonomy: `'schema'` (real bugs, dump stack), `'transient'` (retry-able), `'unknown'`. Convert any store's silent-catch into `[Scope] method=X kind=Y msg=Z` log lines. Extracted from bibliafala's `lead.js:classifyDbError`. ### Changed - **`OpenAICompatProvider` — Azure param-shape support:** - New `maxTokensField: 'max_tokens' | 'max_completion_tokens'` option. Azure OpenAI reasoning-family deployments (`gpt-5.4-*`, `o1-*`) reject `max_tokens` and require `max_completion_tokens`. Default preserves classic behavior. - New `omitTemperature: boolean` option. Reasoning-family models reject any non-default `temperature`. Default `false`. - New optional `images?: Array<{url?, b64?, mimeType?}>` in `ProviderRunArgs` (backward compatible). When present, the user message is rewritten as a multi-part `[{type:'text'},{type:'image_url'}]` array so vision-capable models see them. Providers that don't support multimodal drop the field silently. ### Notes Additive release. All new capabilities are opt-in; consumers using pre-v0.15 code paths see no behavior change. `LLMClassifier` requires `AIRouter` (v0.9+) — the classifier is a shape on top of the router, not a replacement. ### Tests 1093 → **1121 tests passing** across 93 files (28 new): `llm_classifier` (8), `reply_context` (6), `db_error` (5), `extract_statuses` (5), `media_pipeline` (4). Typecheck clean; build clean. ## [0.14.0] — 2026-07-28 ### Added - **`D1CoalesceQueue.processBatchForUser(whatsapp, handler)`** — atomic claim + dispatch of ONE user's pending batch. Right for the webhook path: each Meta webhook keeps its dispatch in its own Worker invocation, so a slow free-tier user's classifier cascade no longer blocks subscribers waiting behind them. Distinct from `processNextBatch()` which picks whichever user is oldest-due. - **`D1CoalesceQueue.listPendingUsers()`** — public list of distinct whatsapp numbers with due pending rows (tenant-scoped). Enables custom cron fan-out patterns. - **`D1CoalesceQueue.claimBatchForUser(whatsapp)`** — public atomic claim for one user. Composable with any handler wiring. - **`D1CoalesceQueue.processAll(handler, { parallel })`** — new optional `parallel` option fans out `processBatchForUser` across N users at a time via `Promise.allSettled`. Chunks run sequentially so the Worker's subrequest budget doesn't get tripped on large backlogs. Default `parallel: 1` preserves pre-v0.14 behavior bit-for-bit. - **`phoneLookupCandidates(input)`** (`src/util/phone_br.ts`) — sibling of `normalizeBrazilianPhone` for the LOOKUP direction. Yields all plausible variants (±DDI, ±"9") of a BR phone number so consumers can try each candidate against a store whose historical rows might be in mixed formats. Complements the write-side normalizer. - **`brtToday` / `dayDelta` / `nextStreak`** (`src/util/streak.ts`) — pure day-math for cross-device activity streaks in BRT (UTC-3, no DST). Handles no-prev / same-day / consecutive / gap / clock-drift cases. Persistence layer is up to the consumer (a `StreakStore` class may come later if enough consumers reinvent the same UPSERT). - **`PT_BR_INTENT_TRIGGERS` + `matchPtBrIntent`** (`src/ai/pt_br_intents.ts`) — regex pack for the intent buckets Brazilian WhatsApp bots consistently reinvent (help/thanks/praise/complaint/cancel). Composes with `HeuristicFallbackClassifier` as the fallback step. Extend by overriding keys or composing `new RegExp(PT_BR_INTENT_TRIGGERS.cancel.source + '|meu-verbo', 'i')`. - **`PROVIDER_LIMITS` + `estimateCostUsd` + `estimateCostMicroUsd`** (`src/ai/provider_limits.ts`) — curated registry of LLM provider free-tier caps (RPD / RPM / TPD / TPM) + per-token pricing for Groq / Cerebras / OpenRouter / DeepInfra / Maritaca / Azure / Workers AI. Complements `LLMCostCalculator` (the calculator is stateless + takes ANY price table; the registry is the reference data source). Data verified 2026-06-19 against provider docs — treat as starting point, not truth. ### Notes Additive release. No API changes; consumers on 0.13.x pick up new symbols by upgrading. All new capabilities are opt-in. **Skipped from the survey:** `typing_indicator: {type: 'text'}` was already shipped in `WhatsAppClient.markRead({ typing: true })`; the report suggesting it as new was mistaken. ### Tests 1057 → **1093 tests passing** across 88 files (36 new): `phone_lookup_candidates` (8), `streak` (12), `pt_br_intents` (11), `provider_limits` (7). Typecheck clean; build clean. ## [0.13.1] — 2026-07-24 ### Changed - **Renamed the npm package from `wa-agent` to `@emerleite/wa-agent`.** The bare `wa-agent` name on the registry belongs to an unrelated squatted 0.1.1 from 2021 that we can't reclaim; scoping under `@emerleite` is the standard workaround and matches how other projects handle it (`next` vs Next.js, `vite` vs Vite are lucky exceptions). - **Consumers:** update to `npm install @emerleite/wa-agent`. Every import specifier changes from `'wa-agent'` → `'@emerleite/wa-agent'` (and same for the subpath exports `/hono` and `/ai-sdk`). Nothing else in the code has to change. - **CLI:** `npx @emerleite/wa-agent init [dir] [--template=]` (the bin field is still named `wa-agent`, so `npm exec wa-agent init` also works from an installed project). - **Scaffold rewriting rules updated** — the `bin/wa-agent.js` CLI now rewrites paths to `node_modules/@emerleite/wa-agent/...` and installs the scoped dep in scaffolded `package.json`. - **Docs updated end-to-end** — every doc + README + example was rewritten to use the scoped name in imports, install commands, and `node_modules/*` paths. Framework prose still refers to "wa-agent" the framework (like Next.js refers to itself as Next.js, not `next`). - **Historical CHANGELOG entries below are left as-written** — they describe what shipped at each version and are read-only history. The rename doesn't invalidate any prior release. ### Notes No code changes; identical binary content to 0.13.0. The one-and-only reason for the version bump is to give the rename a clean marker so tooling that compares installed versions has something to react to. 1057 tests still passing; typecheck clean. ## [0.13.0] — 2026-07-24 ### Added - **`requireAdminAuth`** + **`timingSafeStringEqual`** (`src/security/admin_auth.ts`) — dual Bearer / Basic guard for `/admin/*` endpoints. Scripts and CI hit routes with `Authorization: Bearer `; browsers hit the same routes and get the native login prompt via HTTP Basic. Both paths compare in constant time. Returns `null` on OK, a 401 `Response` with `WWW-Authenticate: Basic realm="…"` on fail. All three credentials are optional — if none configured, every request is denied (safer than open-by-misconfig). - **Crypto primitives** (`src/security/crypto.ts`) — `generateOtpCode(length = 6)`, `generateRandomToken(bytes = 32)`, `sha256Hex`, `hashOtpCode(code, salt)` (per-owner salted), `hashSessionToken(token)`. All Web Crypto based (works in the Workers runtime). Designed for portal / login flows: OTP verification, session token issuance with hash-in-DB / plain-in-cookie. - **Cookie helpers** (`src/security/cookie.ts`) — `serializeCookie(name, value, opts)` with tuned defaults (Path=/, Secure, HttpOnly, SameSite=Lax), `clearCookie`, `parseCookieHeader`, `getCookie(req, name)`. Zero-dep — just RFC 6265 with the modern attributes we actually use. - **`Tracer` interface** + **`NoOpTracer`** + **`LangfuseTracer`** (`src/observability/tracer.ts`) — pragmatic HTTP wrapper over Langfuse's ingestion API. One `flushTrace(event)` call per operation of interest. Consumers `ctx.waitUntil(tracer.flushTrace(...))` for zero user-visible latency. `NoOpTracer` is the default so wiring a `tracer?: Tracer` argument anywhere stays free when the env vars aren't set. Deliberate choice over full OpenTelemetry SDK — configuration overhead not worth it for the "log one trace per agent turn" use case. - **`formatStateBlock`** (`src/util/state_block.ts`) — form-fill helper. Renders a "current state" block for injection into an LLM system prompt so the model doesn't re-ask fields already collected. Skips null / undefined / '' / [] values by default; configurable `labels`, `formatValue`, and `skip` predicate. Returns `""` when nothing renders so callers can safely template it in unconditionally. - **`docs/AGENT_TOOL_VALIDATION.md`** — recipe for tool error handling: schema failures → framework returns Zod error as tool-result string (auto-recover); semantic failures → return actionable string; infrastructure failures → throw. The single most impactful pattern for a well-behaved agent. - **`docs/SCOPED_AGENT_PROMPT.md`** — template + rationale for Meta AI policy (Jan/2026) scope restriction. Numbered SCOPE list, "never engage with general questions" clause, format constraints, ask-before-you-act clauses. Explicitly enumerates what NOT to include (persona bloat, prompt-injection defenses in the prompt, per-tool examples). - **`docs/ARCHITECTURE.md`** — full layering diagram, module inventory table (every top-level `src/` dir + its migrations), request path (webhook → coalesce → dispatch → reply → audit), cron path, extension points, and 10 load-bearing design decisions distilled from v0.1 → v0.13. - **`docs/SECURITY.md`** — every security primitive in one place: `requireAdminAuth`, `verifyMetaSignature`, `Blocklist`, `RateLimit`, OTP + session crypto, cookie helpers, `timingSafeStringEqual`. Threat model (in-scope vs out-of-scope) + anti-patterns. - **`docs/TRACING.md`** — `Tracer` interface, `LangfuseTracer` setup, `AgentLoop` wiring recipe under `ctx.waitUntil`, sampling patterns, cron + `AIRouter` recipes, custom backend authoring (OTel bridge example), anti-patterns. - **`docs/STATE_BLOCK.md`** — form-fill agent pattern: draft persistence, `formatStateBlock` injection into the system prompt, "set-one-field" + commit tool shape, custom `labels` / `formatValue` / `skip`, anti-patterns. - **`docs/UTILITIES.md`** — one-stop reference for the v0.12 primitives: `phone_br`, `whatsapp_format`, `llm_json`, `R2MediaStore`, `log`. When to use each, recipes, anti-patterns. - **`docs/SCAFFOLD_CLI.md`** — `wa-agent init` (v0.11.2) reference: templates, per-file rewriting rules, custom template authoring. - **`docs/CONTRIBUTING.md`** — dev-loop for framework hackers: test layers, mutation testing, hardcoded linter, AI SDK adapter maintenance, scaffold CLI hacking, migration authoring, docs conventions, release checklist. - **`docs/README.md`** — categorized doc index (Getting started / Guide / Recipes / Reference / Ops), by-version table, by-persona table. - **`README.md`** — refreshed "Recipe docs" section with the full doc index; added v0.11.1 through v0.13.0 entries to the "Status" section so version history is discoverable without leaving the README. ### Tests - 1000 → **1057 tests passing** across 84 files (57 new). `admin_auth` (15), `crypto` (12), `cookie` (14), `tracer` (5), `state_block` (9), `admin_auth` extras (2). ### Notes Additive release. No API changes; existing consumers upgrade to pick up the new symbols. All new modules are opt-in — the framework doesn't wire them into `Agent` or `AgentLoop` this release. `LangfuseTracer` is a normal class with `fetch` injectable — no new peerDep added; the Langfuse SDK is deliberately NOT a dependency (the ingestion API is stable and one POST is simpler than importing a client that expects OTel plumbing). The doc set is intentionally comprehensive: every load-bearing primitive from v0.11–v0.13 now has a dedicated doc, and `docs/README.md` indexes them by task, version, and persona. ## [0.12.0] — 2026-07-24 ### Added - **`normalizeBrazilianPhone`, `localizeBrazilianPhone`, `formatBrazilianPhone`, `digits`** (`src/util/phone_br.ts`) — canonical BR phone helpers. WhatsApp/Meta occasionally omits the "9" that BR mobiles require (same user arriving as `5548996967308` on one turn and `554896967308` on the next); without normalization you get duplicate leads and broken lookups. The rule: 55 + DDD(2) + 9 + local(8) = 13 digits; if a 12-digit input has a local prefix starting with 6/7/8/9 it's a mobile missing its "9" and gets one injected. Also accepts messy inputs (with formatting, with or without country code); unknown shapes pass through as digits so consumers don't lose data. Extracted from two independent implementations in sibling projects (zap-prime, aysu) that both reinvented the same wheel. - **`formatForWhatsapp`** (`src/util/whatsapp_format.ts`) — Markdown → WhatsApp dialect converter. Rewrites `**bold**` → `*bold*`, `# Header` → `*Header*`, `- item` → `• item`, `[text](url)` → `text (url)`, collapses 3+ newlines to 2. Complements the existing `stripMarkdown` (which strips everything for log destinations): use this one on strings heading to `reply.text(...)` so answers render correctly in-app instead of showing literal `**`. - **`extractFirstJsonObject`, `tryExtractFirstJsonObject`** (`src/util/llm_json.ts`) — robust JSON extraction from arbitrary LLM output. Strips ```` ```json ```` fences, isolates the first balanced `{...}` block (respecting string escapes), then `JSON.parse`s. `tryExtract*` returns `null` on any failure — useful inside `AgentTool.execute` where the parse error should become the tool-result string so the model re-asks the user. - **`R2MediaStore`** (`src/media/r2_media_store.ts`) — user-generated media store. Distinct from `R2Cache` (which caches framework-generated TTS output): this one keys inbound media by `(scope, id)` so each conversation's uploads are isolated and easy to enumerate. Optional `fileSuffix` for CDN sniffing, optional `publicHost` (falls back to bare key when empty), key sanitization to prevent path traversal. - **`log`** (`src/util/log.ts`) — structured `[PREFIX] scope: message` logger. Prefixes: `[START]`, `[SUCCESS]`, `[FAIL]`, `[FINISH]`, `[INFO]`. Grep-friendly for `wrangler tail`. `log.fail(scope, msg, err?)` also pipes the error to `console.error` so stacks land in the dashboard with source maps. Convention documented so consumers get a coherent log corpus across their bot + framework internals. ### Tests - 955 → **1000 tests passing** across 79 files (45 new). All extractions arrived with unit tests: `phone_br` (17), `whatsapp_format` (7), `llm_json` (11), `r2_media_store` (7), `log` (5). ### Notes Additive release. No API changes; consumers on 0.11.x upgrade to pick up the new symbols. All new modules are opt-in — nothing else in the framework depends on them. ## [0.11.2] — 2026-07-24 ### Added - **`wa-agent` CLI** (`bin/wa-agent.js`) — zero-dep Node script exposed as the `wa-agent` bin. One subcommand today, `init [dir] [--template=]`, that scaffolds a runnable project from the `examples/