Changelog.

### Patch Changes

- Updated dependencies [[`4aaaecc`](https://github.com/ar-agents/ar-agents/commit/4aaaecc4bab0429f61bd034b60c0c77607562b20)]:
  - @ar-agents/facturacion@0.3.0

### Patch Changes

- Updated dependencies [[`e067a4a`](https://github.com/ar-agents/ar-agents/commit/e067a4a4f37e882b32fd0cbf6dfdb872f31d0e6e), [`e067a4a`](https://github.com/ar-agents/ar-agents/commit/e067a4a4f37e882b32fd0cbf6dfdb872f31d0e6e)]:
  - @ar-agents/identity@0.7.0
  - @ar-agents/facturacion@0.2.0

### Minor Changes

- [`7b6bb8c`](https://github.com/ar-agents/ar-agents/commit/7b6bb8c550ee827fa3aa57e837b7948b81449b40) - Add `@ar-agents/ap2` — Agent Payments Protocol primitives, plus the bridge's optional `@ar-agents/agentic-commerce-bridge/integrations/ap2` helpers that verify and sign AP2 mandates inside a custom `PaymentProvider`.

  `@ar-agents/ap2` exposes the verification + signing surface for AP2 Closed Checkout Mandates and Payment Receipts. JWS over the canonical claims set, JWK key handling. Edge-Runtime safe (Web Crypto only).

  The bridge integration is opt-in: `@ar-agents/ap2` is declared as an optional peer dependency. Hosts that don't need AP2 don't pay the bundle cost.

### Patch Changes

- Updated dependencies [[`7b6bb8c`](https://github.com/ar-agents/ar-agents/commit/7b6bb8c550ee827fa3aa57e837b7948b81449b40)]:
  - @ar-agents/ap2@0.2.0

### Minor Changes

- [`9b8e83c`](https://github.com/ar-agents/ar-agents/commit/9b8e83ce6f291a24e00101830a49afceb0102920) - Expose the `/vercel-kv` subpath in `package.json` exports.

  The dist already shipped `vercel-kv.{js,cjs,d.ts}` from the previous release, but `exports` only declared the root entry — making `import { VercelKVStateAdapter } from "@ar-agents/agentic-commerce-bridge/vercel-kv"` resolve to a path-not-exported error.

  Fixes that. `typesVersions` updated for legacy resolvers.

### Patch Changes

- Updated dependencies [[`9b8e83c`](https://github.com/ar-agents/ar-agents/commit/9b8e83ce6f291a24e00101830a49afceb0102920)]:
  - @ar-agents/mercadopago@0.17.2

### Patch Changes

- Updated dependencies [[`687aa10`](https://github.com/ar-agents/ar-agents/commit/687aa1017a665ed9b3414b9f92db634a9329ac4e), [`687aa10`](https://github.com/ar-agents/ar-agents/commit/687aa1017a665ed9b3414b9f92db634a9329ac4e)]:
  - @ar-agents/identity@0.6.0
  - @ar-agents/mercadopago@0.17.1
  - @ar-agents/facturacion@0.1.2

### Patch Changes

- Updated dependencies []:
  - @ar-agents/mercadopago@0.17.0

### Minor Changes

- [`7b6bb8c`](https://github.com/ar-agents/ar-agents/commit/7b6bb8c550ee827fa3aa57e837b7948b81449b40) - Add `@ar-agents/ap2` — Agent Payments Protocol primitives, plus the bridge's optional `@ar-agents/agentic-commerce-bridge/integrations/ap2` helpers that verify and sign AP2 mandates inside a custom `PaymentProvider`.

  `@ar-agents/ap2` exposes the verification + signing surface for AP2 Closed Checkout Mandates and Payment Receipts. JWS over the canonical claims set, JWK key handling. Edge-Runtime safe (Web Crypto only).

  The bridge integration is opt-in: `@ar-agents/ap2` is declared as an optional peer dependency. Hosts that don't need AP2 don't pay the bundle cost.

First public release. Single-hop AP2 v0.2 implementation in TypeScript.

### Phase 2.1 — single-hop AP2

- All four mandate types per AP2 v0.2 spec:
  - `mandate.checkout.open.1` (Open Checkout Mandate)
  - `mandate.checkout.1` (Closed Checkout Mandate)
  - `mandate.payment.open.1` (Open Payment Mandate)
  - `mandate.payment.1` (Closed Payment Mandate)
- All eight constraint types: `checkout.allowed_merchants`,
  `checkout.line_items` (max-flow evaluation), `payment.agent_recurrence`,
  `payment.allowed_payees`, `payment.allowed_payment_instruments`,
  `payment.allowed_pisps`, `payment.amount_range`, `payment.budget`,
  `payment.execution_date`, `payment.reference`.
- ES256 (P-256 ECDSA) signing/verification — per spec, the inner
  `checkout_jwt` MUST use a non-deterministic scheme to defeat
  rainbow-table attacks against `checkout_hash`. Ed25519 is forbidden.
- SD-JWT VC primitives — disclosure encoding (RFC 9901), `_sd` digest
  computation, `sd_hash` (base64url(sha-256(SD-JWT))), compact
  serialization with single hop.
- KB-JWT (Key Binding JWT) — terminal hop carries `nonce`, `aud`, `iat`,
  `sd_hash` and is signed by the agent's `cnf.jwk`.
- Receipts — `CheckoutReceipt` and `PaymentReceipt` as plain JWTs signed
  by the verifier issuer; `reference` = `sd_hash` of the closed mandate.
- Verifier honors all canonical verification rules per AP2 §C: signature,
  time claims, `aud`/`nonce`, `transaction_id` ↔ `checkout_hash` linkage,
  per-mandate-type role checks. Unknown constraint types fail evaluation
  per spec.

### Phase 2.2 — planned

- Multi-hop chain support (`~~`-separated chains, RFC 7800 PoP key
  binding between hops, dSD-JWT delegation per `gco-delegate-sd-jwt`).
- W3C DC-API integration for hardware-backed signing (passkey-bound
  user-side mandates).
- Stateful budget tracking for `payment.budget + payment.agent_recurrence`
  (multi-presentation defense).
- x402 / PIX / SPEI payment-instrument bindings.

### Minor Changes

- [`4aaaecc`](https://github.com/ar-agents/ar-agents/commit/4aaaecc4bab0429f61bd034b60c0c77607562b20) - Add `@ar-agents/banking/testing` subpath with `MockBcraDeudaAdapter` + `MockBcraVarsAdapter` and result factories (`mockBcraDeudaClean`, `mockBcraDeudaRiesgo`, `mockBcraDeudaUnavailable`, `mockUsdOficialSeries`, `mockCerSeries`). Lets cookbook recipes and downstream apps test BCRA-dependent flows without a live BCRA round-trip.

### Minor Changes

- [`e067a4a`](https://github.com/ar-agents/ar-agents/commit/e067a4a4f37e882b32fd0cbf6dfdb872f31d0e6e) Thanks [@naza00000](https://github.com/naza00000)! - Add `doctor` CLIs to the remaining 4 packages — completes the uniform CLI surface across the toolkit.

  ```bash
  npx @ar-agents/banking doctor       # algorithm-only tools, BCRA endpoint, 11 tools
  npx @ar-agents/facturacion doctor   # AFIP cert/key/CUIT/env/PdV check + tools
  npx @ar-agents/shipping doctor      # which carriers (Andreani/OCA/Correo) are wired
  npx -y @ar-agents/mcp doctor        # which @ar-agents/* subpackages your MCP host has wired
  ```

  The `mcp doctor` is particularly useful — it shows the full subpackage status (enabled / partial / disabled) with the always-on tools per package, so a Claude Desktop / Cursor user knows exactly what their host can do without enumerating env vars.

  All 7 published `@ar-agents/*` packages with tools now ship a uniform `doctor` subcommand. Plus `mp-doctor` from earlier still works for backward compat.

### Patch Changes

- [`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46) - Enable [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements) for all `@ar-agents/*` packages. From this version on, the npm registry includes a verifiable cryptographic record that the package was built from this exact GitHub commit, via the GitHub Actions `release.yml` workflow. Boosts supply-chain audit scores (Socket / Snyk / npm) and lets downstream agents verify package integrity without trusting the publisher.

  No API or runtime changes.

### Minor Changes

- Initial release: AR banking primitives for Vercel AI SDK 6+ agents.

  **5 tools shipped:**

  - `validate_cbu` — pure-algorithm CBU/CVU validation with bank/PSP identification (Galicia, Nación, Mercado Pago, Ualá, Naranja X, etc.)
  - `lookup_bank_by_code` — resolve a 3-digit bank code or 7-digit CVU prefix → name
  - `list_banks` — enumerate all known traditional banks
  - `list_psps` — enumerate all known fintechs
  - `lookup_credit_situation` — BCRA Central de Deudores adapter (`BcraPublicApiAdapter` ships, no auth required)

  **Robustez built-in** matching the rest of the toolkit:

  - `BcraPublicApiAdapter` accepts `requestTimeoutMs`, `maxRetries`, `onCall` observability hook
  - HTTP 404 from BCRA cleanly mapped to `available: false` (CUIT not in registry, not a crash)
  - Exponential backoff on 5xx + transient errors

  **Pure tools cost nothing** — no API key, no env var, no network. Drop-in safe.

  54 tests, 90%+ statement coverage, 6.2 KB brotli'd.

### Minor Changes

- Initial release. Argentine Boletín Oficial as a structured firehose for AI agents on the Vercel AI SDK 6.
  - 4 secciones (primera/segunda/tercera/cuarta) catalog + heading-based tipo classifier.
  - `LiveBoFetcher` (web-scraping with retry + timeout), `MockBoFetcher` (in-memory for tests), `UnconfiguredBoFetcher` (safe-by-default).
  - `boletinOficialTools()` — 6 tools: bo_search, bo_get_norma, bo_today, bo_subscribe, bo_list_subscriptions, bo_unsubscribe.
  - Subscription matcher (keyword + CUIT + organismo + sección + tipo, AND semantics) + `InMemoryBoSubscriptionAdapter` + pluggable `BoSubscriptionAdapter` interface.
  - Heuristic CUIT extractor + canonical URL builder.
  - Pure-function helpers (classifyTipo, extractCuits, buildNormaUrl) safe to call in any environment.

### Minor Changes

- [`4aaaecc`](https://github.com/ar-agents/ar-agents/commit/4aaaecc4bab0429f61bd034b60c0c77607562b20) - Add `@ar-agents/facturacion/testing` subpath with `MockWsfeClient` (public-method-compatible stand-in for `WsfeClient`) and result factories (`mockSolicitarCaeApproved`, `mockSolicitarCaeRejected`, `mockUltimoComprobante`, `mockConsultarComprobante`, `mockDummyOk`, `mockDummyDown`). Lets agent loops and recipes test factura-emission flows without a live AFIP/ARCA WSAA + WSFE round-trip.

### Minor Changes

- [`e067a4a`](https://github.com/ar-agents/ar-agents/commit/e067a4a4f37e882b32fd0cbf6dfdb872f31d0e6e) Thanks [@naza00000](https://github.com/naza00000)! - Add `doctor` CLIs to the remaining 4 packages — completes the uniform CLI surface across the toolkit.

  ```bash
  npx @ar-agents/banking doctor       # algorithm-only tools, BCRA endpoint, 11 tools
  npx @ar-agents/facturacion doctor   # AFIP cert/key/CUIT/env/PdV check + tools
  npx @ar-agents/shipping doctor      # which carriers (Andreani/OCA/Correo) are wired
  npx -y @ar-agents/mcp doctor        # which @ar-agents/* subpackages your MCP host has wired
  ```

  The `mcp doctor` is particularly useful — it shows the full subpackage status (enabled / partial / disabled) with the always-on tools per package, so a Claude Desktop / Cursor user knows exactly what their host can do without enumerating env vars.

  All 7 published `@ar-agents/*` packages with tools now ship a uniform `doctor` subcommand. Plus `mp-doctor` from earlier still works for backward compat.

### Patch Changes

- Updated dependencies [[`e067a4a`](https://github.com/ar-agents/ar-agents/commit/e067a4a4f37e882b32fd0cbf6dfdb872f31d0e6e)]:
  - @ar-agents/identity@0.7.0

### Patch Changes

- Updated dependencies [[`687aa10`](https://github.com/ar-agents/ar-agents/commit/687aa1017a665ed9b3414b9f92db634a9329ac4e)]:
  - @ar-agents/identity@0.6.0

### Patch Changes

- [`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46) - Enable [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements) for all `@ar-agents/*` packages. From this version on, the npm registry includes a verifiable cryptographic record that the package was built from this exact GitHub commit, via the GitHub Actions `release.yml` workflow. Boosts supply-chain audit scores (Socket / Snyk / npm) and lets downstream agents verify package integrity without trusting the publisher.

  No API or runtime changes.

- Updated dependencies [[`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46)]:
  - @ar-agents/identity@0.5.1

### Minor Changes

- Initial release: AFIP/ARCA factura electrónica (WSFE) for Vercel AI SDK 6+ agents.

  **10 tools shipped:**

  - `emitir_factura` — solicit a CAE for a new comprobante
  - `consultar_ultimo_comprobante` — get the next available comprobante number
  - `consultar_factura_emitida` — verify a previously-issued comprobante
  - `obtener_tipos_comprobante` / `obtener_tipos_documento` / `obtener_alicuotas_iva` / `obtener_tipos_concepto` / `obtener_tipos_moneda` — live AFIP catalogs
  - `obtener_cotizacion` — exchange rate for non-PES currencies
  - `health_check_afip` — WSFE health probe

  **Pre-flight validator** catches the 10 most common AFIP rejection reasons LOCALLY (ImpTotal != suma, Iva sum mismatch, Factura C with IVA, Servicios sin fchServ\*, Notas sin cbtesAsoc, etc.) before the network round-trip.

  **Reuses `@ar-agents/identity`** for the WSAA token cache + `fetchWithRetry` — same X.509 cert powers both. Same robustez (timeout / retry / SOAP-fault detection / `onCall` observability hook).

  **51 tests, 80%+ statement coverage, 9 KB brotli'd.**

### Minor Changes

- Initial release. Argentine Firma Digital (Ley 25.506 / ONTI) verification primitives wrapped as Vercel AI SDK 6 tools.
  - `parseCert(pem)` — parse single X.509 cert, extract subject/issuer/CUIT/key info.
  - `parseCertChain(pemBundle)` — multi-cert PEM extraction.
  - `verifyChain(pemBundle, options)` — leaf → root walk with heuristic AR-ONTI root acceptance OR explicit trust-anchor fingerprint pinning.
  - `verifyDetachedCmsSignature(sig, payload, options)` — PKCS#7 / CMS detached signature verification with optional chain walk per signer.
  - 4 tools: `firma_inspect_cert`, `firma_verify_chain`, `firma_is_onti_issued`, `firma_verify_cms_signature`.
  - Heuristic AR-ONTI / AC-Raíz detection via DN-pattern matching; extensible via `TrustStore`.
  - Verification only — signing is out of scope (requires hardware tokens).

### Minor Changes

- [`dbc2332`](https://github.com/ar-agents/ar-agents/commit/dbc23325fffe9b47954ae28ba48a723083d0a884) - Initial release. TAD (Trámites a Distancia) + GDE (Gestión Documental Electrónica) primitives for the Vercel AI SDK. The 4th pieza for sociedades-IA — RFC-001 § 3.4. Ships read-only adapters (Domicilio Electrónico inbox + Mis Trámites) with unconfigured shims, the `validate_igj_inscription` algorithm-only pre-flight validator, severity heuristic for DEC notifications (critical/important/info), and a `MockDomicilioAdapter` + `MockTramitesAdapter` testing subpath. 36 tests, publint + attw 🟢.

### Minor Changes

- [`e067a4a`](https://github.com/ar-agents/ar-agents/commit/e067a4a4f37e882b32fd0cbf6dfdb872f31d0e6e) Thanks [@naza00000](https://github.com/naza00000)! - Add `@ar-agents/identity/testing` subpath: in-memory `MockAfipPadronAdapter` + result factories.

  ```ts
  import { identityTools } from "@ar-agents/identity";
  import {
    MockAfipPadronAdapter,
    mockAfipPadronAvailable,
    mockMonotributista,
  } from "@ar-agents/identity/testing";

  const afip = new MockAfipPadronAdapter()
    .seed("20-12345678-9", mockAfipPadronAvailable({ nombre: "Acme SRL" }))
    .seed("20-99999999-9", mockMonotributista({ categoria: "A" }));

  const tools = identityTools({ afip });
  ```

  Factories: `mockAfipPadronAvailable`, `mockAfipPadronUnavailable`, `mockAfipPadronError`, `mockMonotributista`. The adapter exposes a `.calls` array so tests can assert on which CUITs the agent looked up.

  Subpath chosen so the dev-only mock stays out of production bundles.

### Minor Changes

- [`687aa10`](https://github.com/ar-agents/ar-agents/commit/687aa1017a665ed9b3414b9f92db634a9329ac4e) - Add `identity doctor` CLI for environment diagnosis.

  ```bash
  npx @ar-agents/identity doctor
  ```

  Validates `AFIP_CUIT` (algorithm-only), checks `AFIP_CERT_PEM` and `AFIP_KEY_PEM` are PEM-shaped, and confirms `AFIP_ENV` is `prod` or `homo`. Lists the 2 tools (`validate_cuit` always-on, `lookup_cuit_afip` adapter-required). Exit codes 0/1 for CI.

  Helps users distinguish "env vars missing" from "cert wrong-CA" from "wrong service alias" before hitting the WSAA round-trip.

### Patch Changes

- [`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46) - Enable [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements) for all `@ar-agents/*` packages. From this version on, the npm registry includes a verifiable cryptographic record that the package was built from this exact GitHub commit, via the GitHub Actions `release.yml` workflow. Boosts supply-chain audit scores (Socket / Snyk / npm) and lets downstream agents verify package integrity without trusting the publisher.

  No API or runtime changes.

### Minor Changes

- Identity v0.5: production robustez parity with the rest of the toolkit.

  **WSAA + WSCDC now share a hardened HTTP layer** (`fetchWithRetry`):

  - Per-request timeouts via `AbortSignal` (default 30s, override with `requestTimeoutMs`).
  - Exponential backoff on 5xx + transient network errors (default 1 retry, override with `maxRetries`).
  - SOAP-aware: HTTP 500 with a real `<Fault>` body is treated as a parseable response (not retried).
  - Optional `onCall` observability hook fires after every WSAA + WSCDC request — `{ label, durationMs, httpStatus, retried, success }` — drop-in for OpenTelemetry / Datadog / console.

  **`WsaaWscdcAdapter` accepts the new options** (`requestTimeoutMs`, `maxRetries`, `onCall`) and forwards them to both the TA refresh path and the per-CUIT lookup path.

  **`fetchWithRetry` is exported from `@ar-agents/identity/wsaa`** so multi-step flows (custom AFIP services, A4, A5, etc.) can reuse the same retry/timeout/observability stack.

  No breaking changes — existing 0.4 setups keep working with the previous (no-retry, no-timeout) defaults until you opt in.

  The MCP wrapper bumps to pull in the new identity major.

### Minor Changes

- Add `ws_sr_constancia_inscripcion` support — full constancia data (monotributo + IVA condition + impuestos asociados).

  **What's new**

  - `WsaaWscdcAfipPadronAdapter` now accepts a `service` option:
    - `"ws_sr_constancia_inscripcion"` (default, recommended) — full constancia
    - `"ws_sr_padron_a13"` — datos generales only (lighter, no monotributo)
  - Both share the same `getPersona` operation but the response shapes differ. The parser handles both transparently.
  - Constancia uses the `personaServiceA5` endpoint URL (`http://a5.soap.ws.server.puc.sr/` namespace) — reuses what was previously thought of as the "deprecated A5" endpoint, but with a different TA service name (`ws_sr_constancia_inscripcion`).
  - Live-tested against ARCA prod (AFIP rebrand) — returns nombre, condicion (MONOTRIBUTO/RESPONSABLE INSCRIPTO/EXENTO), monotributoCategoria, domicilio fiscal, actividades.

  **API additions**

  ```ts
  // New exports from @ar-agents/identity/wsaa
  import {
    CONSTANCIA_INSCRIPCION_SERVICE_NAME, // "ws_sr_constancia_inscripcion"
    PADRON_A13_SERVICE_NAME, // "ws_sr_padron_a13"
    type AfipPadronService,
    getPersona, // service-aware (replaces getPersonaA13)
  } from "@ar-agents/identity/wsaa";

  // Default — uses constancia (richer)
  new WsaaWscdcAfipPadronAdapter({ certPem, keyPem, cuitRepresentado, env });

  // Opt into the lighter A13-only flavor
  new WsaaWscdcAfipPadronAdapter({
    certPem,
    keyPem,
    cuitRepresentado,
    env,
    service: "ws_sr_padron_a13",
  });
  ```

  **Backward compatibility**

  - `getPersonaA13` is kept as a deprecated alias that calls `getPersona({ service: "ws_sr_padron_a13", ... })`.
  - `WSCDC_SERVICE_NAME` now points to `ws_sr_constancia_inscripcion` (was `ws_sr_padron_a13` in v0.3). If you relied on the v0.3 default to query A13, pass `service: "ws_sr_padron_a13"` explicitly OR authorize the new constancia service in your AFIP/ARCA "Administrador de Relaciones".

  **Note on AFIP → ARCA rebrand**

  AFIP was renamed to ARCA (Agencia de Recaudación y Control Aduanero) in 2025. URLs, panels, and forms still mix both names — the lib uses "AFIP" in code/docs because the WSAA + WSCDC service names didn't change.

### Minor Changes

- [`cd4756b`](https://github.com/ar-agents/ar-agents/commit/cd4756b3a377b1c8f439e93dd7cd3cc9cad79f2c) - First end-to-end functional release of the WSAA + WSCDC adapter.

  **Bug fixes (the previous v0.2.0 didn't work end-to-end against AFIP)**

  - WSCDC migrated from deprecated `ws_sr_padron_a5` to `ws_sr_padron_a13`. AFIP retired A5; only A4 and A13 remain in the service catalog.
  - WSAA: switched signing from detached PKCS#7 CMS to attached. AFIP needs eContent embedded to verify; detached signing returned `cms.sign.invalid`.
  - WSCDC envelope: targetNamespace `http://a13.soap.ws.server.puc.sr/`, operation renamed from `getPersona_v2` to `getPersona`, child elements (token, sign, cuitRepresentada, idPersona) are NOT namespace-prefixed (A13 WSDL uses `elementFormDefault="unqualified"`).
  - WSCDC parser updated for A13 response shape: `<personaReturn>` wrapper, multiple `<domicilio>` blocks distinguished by `<tipoDomicilio>` (FISCAL vs LEGAL/REAL), `codigoPostal` (not `codPostal`), `descripcionActividadPrincipal` at persona level.
  - SOAP fault handling: HTTP 500 with structured Fault now passes through to the parser, which converts `inexistente` faults into `available: false` results instead of throwing.

  **New: PEM-string adapter mode for serverless**

  Added `certPem` / `keyPem` options alongside `certPath` / `keyPath` so the lib works in filesystem-less runtimes (Vercel, Lambda, Cloudflare Workers). Paste PEM contents into env vars. PEM strings are robust-normalized to handle escaped `\n` survival from dashboard env-var paste and single-line copy-paste accidents.

  **Known limitation**

  A13 is "datos generales" — it does NOT include monotributo category or fechaInscripcion. The lib reports `condicion: "DESCONOCIDA"` and null for those fields. Full constancia (monotributo + IVA condition + impuestos asociados) requires `ws_sr_constancia_inscripcion`, planned for v0.4.

  Verified end-to-end against AFIP prod via the `cuit-hello` reference app deployed to Vercel.

### Minor Changes

- [`12519eb`](https://github.com/ar-agents/ar-agents/commit/12519eb6868c4b3acc556803b70c6335283e39f2) - Add `WsaaWscdcAfipPadronAdapter` — production-ready AFIP padrón lookup via WSAA + WSCDC SOAP.

  Imported from the new subpath `@ar-agents/identity/wsaa` (kept off the main entry so users who only need pure-algorithm validation don't pull in `node-forge`). The adapter implements `AfipPadronAdapter` and handles:

  - WSAA login flow: TRA generation → PKCS#7 detached CMS signing with the integration's X.509 cert → POST to `loginCms` → parsing the returned access ticket
  - TA caching with pluggable `TokenStore` (in-memory default; bring your own Upstash/Redis/Postgres adapter for multi-process deployments)
  - WSCDC `getPersona_v2` SOAP call with full response parsing into `AfipPadronData` (name, tax condition, monotributo category, address, activities)
  - Typed error surfacing: WSAA failures return `{ available: false, error: "Failed to authenticate with AFIP WSAA: ..." }` with actionable detail, never throws unexpectedly
  - Fast path for malformed CUITs: rejected before any AFIP call

  Also exports `loginCms`, `TokenCache`, `InMemoryTokenStore`, `getPersonaV2`, and the underlying `buildTraXml` / `signTra` / `parseLoginTicketResponse` / `buildGetPersonaSoap` / `parseGetPersonaResponse` helpers for callers who want to compose their own AFIP flows.

  Setup requires generating an X.509 cert + key with openssl, registering it in AFIP via Clave Fiscal, and authorizing the cert for the `ws_sr_padron_a5` service. See README's "Quick start (with AFIP padrón lookup)" section for the full walkthrough.

All notable changes to `@ar-agents/identity` are documented here. The format
follows [Keep a Changelog](https://keepachangelog.com/) and the project adheres
to [Semantic Versioning](https://semver.org/).

### Patch Changes

- [`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46) - Enable [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements) for all `@ar-agents/*` packages. From this version on, the npm registry includes a verifiable cryptographic record that the package was built from this exact GitHub commit, via the GitHub Actions `release.yml` workflow. Boosts supply-chain audit scores (Socket / Snyk / npm) and lets downstream agents verify package integrity without trusting the publisher.

  No API or runtime changes.

### Minor — Auth0 + Magic.link adapters moved to subpath exports

The Auth0 and Magic.link SDK adapters use `node:crypto` and `@magic-sdk/admin`
(which transitively imports `node:stream`, `node:http`, etc). Re-exporting
them from the main barrel made the "main bundle is Edge-Runtime safe" claim
in v0.3.0 only true under aggressive ESM tree-shaking. CJS consumers and
naive bundlers pulled the Node-only modules anyway.

```ts
// BEFORE (v0.3.x — still works, deprecated)
import { Auth0Adapter, MagicLinkSdkAdapter } from "@ar-agents/identity-attest";

// AFTER (v0.4.x — recommended)
import { Auth0Adapter } from "@ar-agents/identity-attest/auth0";
import { MagicLinkSdkAdapter } from "@ar-agents/identity-attest/magic-link-sdk";
```

The main barrel re-exports are kept for backward compatibility with a
`@deprecated` JSDoc, scheduled for removal in v1.0.0.

This closes the runtime-claim mismatch flagged by /review (CHANGELOG admitted
the limitation in fine print but the package-level "Edge Runtime support"
claim was misleading).

### Test coverage additions

- `test/crypto.test.ts` — golden-vector regression test for `hmacSha256Hex`
  vs `node:crypto.createHmac`. If the Web Crypto path drifts from the old
  implementation, all previously-issued attestations would silently fail
  signature verification — now caught loudly. Includes 5 test vectors
  (typical, empty, single-char, long, unicode) plus tests for
  `timingSafeEqualHex` and `randomUuid`.

### Minor Changes — Edge Runtime support (BREAKING for direct callers of `verifyAttestationSignature`)

**Migrated `AttestationClient` from `node:crypto` to Web Crypto.** The main
bundle now runs in Vercel Edge Runtime, Cloudflare Workers, Deno, and
any environment with `globalThis.crypto.subtle`.

**Breaking change:** `AttestationClient.verifyAttestationSignature(att)`
is now async (`Promise<void>` instead of `void`). All callers inside
agent tool execute() handlers are already async, so this is zero-cost
for typical usage. If you call it from sync code, add `await`.

```ts
// BEFORE
client.verifyAttestationSignature(att);

// AFTER
await client.verifyAttestationSignature(att);
```

The Auth0 + MagicLink adapters still use `node:crypto` for PKCE — they're
opt-in (you only pull them if you import `Auth0Adapter` / `MagicLinkSdkAdapter`).
The core `AttestationClient` + `WhatsAppOtpAdapter` + `EmailMagicLinkAdapter`
are fully Edge-safe.

### Minor Changes

- Robustness pass + 5 new features across both packages.

  # `@ar-agents/mercadopago@0.3.0`

  **Robustness (Section 6 of v0.3 spec)**

  - Per-request timeout via `AbortSignal` (default 30s, configurable via `requestTimeoutMs`).
  - Auto-retry on 5xx + 429 with exponential backoff (default 1 retry, configurable via `maxRetries`). Honors `Retry-After` header on rate-limit. **Never retries on 4xx** (deterministic user/config errors).
  - New typed errors: `MercadoPagoTimeoutError`, `MercadoPagoOverloadedError` (HTML 503 detection — when MP returns HTML instead of JSON).
  - `onCall` observability hook fires after every request with `{ method, path, durationMs, httpStatus, retried, success }`. Wire into OpenTelemetry / Sentry / Axiom without forking the lib.
  - **Deterministic idempotency keys** — `create_payment` and `refund_payment` now use `sha256(meaningful_fields)` instead of `Date.now()`. Retries dedupe correctly on MP's side.

  **New tools (3)**

  - **`charge_saved_card`** — server-side retokenize + charge for returning customers. Requires CVV (AR MP doesn't support CVV-less via public API). Idempotent on (card_id, amount, external_reference).
  - **`create_qr_payment`** — dynamic in-store QR via MP Point. Returns raw `qr_data` (EMVCo) + ready-to-display base64 PNG `qr_data_url`. Compatible with all AR wallets (Modo, BNA+, Cuenta DNI, Naranja X) via Transferencias 3.0 interop.
  - **`cancel_qr_payment`** — clear a pending QR order on a POS so the next `create_qr_payment` doesn't 409.

  **Total tool count: 24** (was 21 in v0.2). Added `qrcode` as runtime dep for in-store flow.

  # `@ar-agents/identity-attest@0.2.0`

  **3 new adapters bringing total to 5**

  - **`Auth0Adapter`** (trust 0.7, or 0.85 with MFA) — OAuth2 Authorization Code flow with PKCE. Server-side `id_token` verification via `jose` JWKS. Optional MFA step-up via `acr_values` — when MFA is completed, `effective_trust_level` bumps to 0.85.
  - **`MagicLinkSdkAdapter`** (trust 0.7) — Magic.link DIDToken validation via `@magic-sdk/admin` (optional peer dep). Lazy-loaded so users without Magic don't pay cold-start cost. Returns DID + email/phone/wallet claims.
  - **`MercadoPagoIdentityAdapter`** (trust 0.5) — partial KYC via $1 micro-charge. MP doesn't expose a public KYC API, so we use payment-payer attestation: a successful payment proves MP validated the buyer's CUIT/DNI against their internal database. Auto-refunds the $1 by default. Returns `identification_type` + `identification_number` + email + name claims.

  **New client methods**

  - `submitOauthCode(requestId, code)` — for OAuth callbacks (Auth0)
  - `submitMagicDidToken(requestId, didToken)` — for Magic.link
  - `submitMercadoPagoPaymentId(requestId, paymentId)` — for MP webhook callbacks

  **Quality**

  - 28/28 tests pass (was 15 in v0.1)
  - 12.93 KB ESM brotli'd (jose is treeshakeable; was 4.44 KB without OAuth adapter)
  - publint + arethetypeswrong all 🟢
  - `jose` is a dep (used by Auth0Adapter); `@magic-sdk/admin` is optional peer dep

  **Trust levels reference (current)**

  - 0.3 — `WhatsAppOtpAdapter` (phone-owned)
  - 0.5 — `EmailMagicLinkAdapter` (email-owned), `MercadoPagoIdentityAdapter` (partial KYC)
  - 0.7 — `Auth0Adapter` (federated identity), `MagicLinkSdkAdapter` (Magic-managed)
  - 0.85 — `Auth0Adapter` with MFA enforcement
  - 0.95 — gov-verified (planned, blocked on AR SID rollout)

### Initial release — the RENAPER workaround pattern

Identity attestation orchestrator for AI agents. The agent doesn't verify identity directly (RENAPER closed); it orchestrates the user proving themselves via accessible providers (WhatsApp OTP, email magic-link), receives a cryptographically-signed `Attestation` with a `trustLevel` (0..1), and decides whether trust suffices for the action requested.

**Core**

- `AttestationClient` — orchestrator. HMAC-SHA256 signs every issued attestation. Pluggable storage.
- `AttestationStore` interface + `InMemoryAttestationStore` default. Implement Redis/Postgres adapters for production.
- `AttestAdapter` interface — every adapter declares its trust level + how to deliver/verify the challenge.
- Per-request expiry (default 15 min), max attempts (default 3, then `failed`), attestation TTL (default 30 days).

**Adapters shipped (v0.1)**

- `WhatsAppOtpAdapter` (trust 0.3) — uses `@ar-agents/whatsapp` (or any `WhatsAppLikeClient`) to deliver 6-digit OTP. Falls back to template message outside 24h customer service window.
- `EmailMagicLinkAdapter` (trust 0.5) — uses any `EmailSender` (Resend/SES/SMTP) to deliver magic-link email.

**Tools (5)**

- `list_verification_methods` — what's registered, with trust levels
- `request_identity_verification` — kick off a flow
- `submit_otp_code` — for OTP flows
- `check_verification_status` — for polling magic-link flows
- `get_attestation` — fetch the signed proof

**Webhook**

- `handleAttestationCallback` — wire into your `/api/identity-attest/callback` route handler for magic-link completion.

**Trust levels**

- 0.3 phone-owned (OTP)
- 0.5 email-owned (magic-link)
- 0.7 federated identity (Auth0/Cognito) — planned v0.2
- 0.85 KYC-verified (MercadoPago Identity) — planned v0.3
- 0.95 gov-verified (SID) — planned, blocked on AR rollout
- 1.0 in-person (out of agent scope)

**Tests**: 15/15 passing. Bundle: 4.44 KB ESM brotli'd. publint + arethetypeswrong all 🟢.

### Minor Changes

- Initial release. Inspección General de Justicia open data wrapped as Vercel AI SDK 6 tools.
  - `LiveCkanFetcher` against `datos.jus.gob.ar/api/3/action/datastore_search` (no auth required).
  - `MockIgjFetcher` for tests/demos. `UnconfiguredIgjFetcher` safe-by-default.
  - 6 tools: search, get entity, domicilios, autoridades, balances, asambleas.
  - Pure normalize helpers (`parseEntity`, `normalizeEntityType`, `normalizeCuit`) that work without a fetcher.
  - Resource ids overridable for resilience against dataset republishing.
  - Every result carries `coverageNote` explaining sample-dataset limitations.

### Minor Changes

- [`d7ea25d`](https://github.com/ar-agents/ar-agents/commit/d7ea25d1e9eb25770311937665b9c236e8e7d4e7) - Initial release. Zero-dependency TypeScript client for `/api/auto-incorporate`. One async `incorporate({...})` call returns the full incorporation kit (4 generated files, Vercel deploy URL, env-var manifest, legal checklist, signed audit-log reference). Plus `incorporateOrThrow`, `describe`, `fetchAudit` helpers. Works in Node 20+, Edge Runtime, Cloudflare Workers, Deno, browsers. 12 unit tests, publint + attw 🟢 across node10/node16/bundler. SLSA v1 provenance on publish.

### Minor Changes

- [`dbc2332`](https://github.com/ar-agents/ar-agents/commit/dbc23325fffe9b47954ae28ba48a723083d0a884) - Add `@ar-agents/gde-tad` to the MCP bundle. The 4 gde-tad tools (`validate_igj_inscription`, `list_domicilio_inbox`, `list_mis_tramites`, `get_critical_notifications`) are exposed to every MCP host (Claude Desktop, Cursor, Continue, Cline) alongside the 11 existing subpackages. Total exposed surface: 133 tools across 12 subpackages. The doctor CLI now reports gde-tad config + always-on tools.

### Patch Changes

- Updated dependencies [[`dbc2332`](https://github.com/ar-agents/ar-agents/commit/dbc23325fffe9b47954ae28ba48a723083d0a884)]:
  - @ar-agents/gde-tad@0.2.0

### Patch Changes

- Updated dependencies [[`4aaaecc`](https://github.com/ar-agents/ar-agents/commit/4aaaecc4bab0429f61bd034b60c0c77607562b20), [`4aaaecc`](https://github.com/ar-agents/ar-agents/commit/4aaaecc4bab0429f61bd034b60c0c77607562b20)]:
  - @ar-agents/banking@0.4.0
  - @ar-agents/facturacion@0.3.0

### Minor Changes

- [`e067a4a`](https://github.com/ar-agents/ar-agents/commit/e067a4a4f37e882b32fd0cbf6dfdb872f31d0e6e) Thanks [@naza00000](https://github.com/naza00000)! - Add `doctor` CLIs to the remaining 4 packages — completes the uniform CLI surface across the toolkit.

  ```bash
  npx @ar-agents/banking doctor       # algorithm-only tools, BCRA endpoint, 11 tools
  npx @ar-agents/facturacion doctor   # AFIP cert/key/CUIT/env/PdV check + tools
  npx @ar-agents/shipping doctor      # which carriers (Andreani/OCA/Correo) are wired
  npx -y @ar-agents/mcp doctor        # which @ar-agents/* subpackages your MCP host has wired
  ```

  The `mcp doctor` is particularly useful — it shows the full subpackage status (enabled / partial / disabled) with the always-on tools per package, so a Claude Desktop / Cursor user knows exactly what their host can do without enumerating env vars.

  All 7 published `@ar-agents/*` packages with tools now ship a uniform `doctor` subcommand. Plus `mp-doctor` from earlier still works for backward compat.

### Patch Changes

- Updated dependencies [[`e067a4a`](https://github.com/ar-agents/ar-agents/commit/e067a4a4f37e882b32fd0cbf6dfdb872f31d0e6e), [`e067a4a`](https://github.com/ar-agents/ar-agents/commit/e067a4a4f37e882b32fd0cbf6dfdb872f31d0e6e)]:
  - @ar-agents/identity@0.7.0
  - @ar-agents/banking@0.3.0
  - @ar-agents/facturacion@0.2.0
  - @ar-agents/shipping@0.2.0

### Patch Changes

- Updated dependencies [[`9b8e83c`](https://github.com/ar-agents/ar-agents/commit/9b8e83ce6f291a24e00101830a49afceb0102920)]:
  - @ar-agents/mercadopago@0.17.2

### Patch Changes

- Updated dependencies [[`687aa10`](https://github.com/ar-agents/ar-agents/commit/687aa1017a665ed9b3414b9f92db634a9329ac4e), [`687aa10`](https://github.com/ar-agents/ar-agents/commit/687aa1017a665ed9b3414b9f92db634a9329ac4e), [`687aa10`](https://github.com/ar-agents/ar-agents/commit/687aa1017a665ed9b3414b9f92db634a9329ac4e)]:
  - @ar-agents/identity@0.6.0
  - @ar-agents/mercadopago@0.17.1
  - @ar-agents/whatsapp@0.4.0
  - @ar-agents/facturacion@0.1.2
  - @ar-agents/identity-attest@0.4.2

### Patch Changes

- Updated dependencies []:
  - @ar-agents/mercadopago@0.17.0

### Patch Changes

- Updated dependencies []:
  - @ar-agents/mercadopago@0.16.0

### Patch Changes

- Add `mcpName: "io.github.ar-agents/mcp"` to `package.json` and ship `server.json` for the official MCP Registry. The `mcpName` field is the ownership-verification marker required by the registry's npm package validation. `server.json` is the registry metadata file consumed by `mcp-publisher publish`.

  This is the prerequisite for listing on https://registry.modelcontextprotocol.io. Authentication and the `mcp-publisher publish` invocation are still manual (interactive GitHub device auth), but everything else is in place: the package metadata, the registry server descriptor, and the MIT license + GitHub `repository.url` that the registry verifier expects.

  No API or runtime changes.

### Patch Changes

- [`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46) - Enable [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements) for all `@ar-agents/*` packages. From this version on, the npm registry includes a verifiable cryptographic record that the package was built from this exact GitHub commit, via the GitHub Actions `release.yml` workflow. Boosts supply-chain audit scores (Socket / Snyk / npm) and lets downstream agents verify package integrity without trusting the publisher.

  No API or runtime changes.

- Updated dependencies [[`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46)]:
  - @ar-agents/mercadopago@0.15.3
  - @ar-agents/identity@0.5.1
  - @ar-agents/identity-attest@0.4.2
  - @ar-agents/whatsapp@0.3.1
  - @ar-agents/banking@0.1.1
  - @ar-agents/facturacion@0.1.1
  - @ar-agents/shipping@0.1.1

### Patch Changes

- Picks up `@ar-agents/mercadopago@0.15.0` (`requireConfirmation` opt-in HITL
  callback, webhookDedup wired, idempotency-key collision-safe encoding,
  VercelKVRateLimiter jitter + retry cap) and
  `@ar-agents/identity-attest@0.4.0` (Auth0 + Magic.link moved to subpath
  exports for true Edge-Runtime isolation).

### Patch Changes

- Picks up `@ar-agents/mercadopago@0.14.0` (deep-audit hardening:
  browser-context guard, strict Zod on patch schemas, deterministic
  idempotency on subscriptions/preferences, HITL warnings on irreversible
  ops), `@ar-agents/whatsapp@0.3.0` (browser-context guard), and
  `@ar-agents/identity-attest@0.3.0` (Edge Runtime via Web Crypto).

### Patch Changes

- Picks up `@ar-agents/mercadopago@0.13.0` (`VercelKVRateLimiter` for
  distributed rate limiting in serverless).

### Patch Changes

- Picks up `@ar-agents/mercadopago@0.12.0` (idempotency-by-default) and
  `@ar-agents/whatsapp@0.2.0` (`scopedTo` mode for agent-hijacking
  prevention).
- **19 new registry tests** (`test/registries.test.ts`) covering both
  configured and unconfigured paths for every registry factory:
  identity, banking, mercadopago, whatsapp, shipping, facturacion,
  identity-attest. Honest coverage now at 74%/48%/92%/74% (was
  66%/26%/88%/66% with the previous threshold relaxation).
- Coverage thresholds raised to match the new floor: 70/45/90/70.

### Patch Changes

- Picks up `@ar-agents/mercadopago@0.11.0` — composability + cross-LATAM + fraud scoring:
  - **Tool middleware pattern**: `withAuditLog`, `withRateLimit`, `withMetrics`, `withRetry` + `compose()`
  - **TaxID validation cross-LATAM**: AR/BR/MX/CL/CO/UY/PE
  - **`additional_info` enrichment** on `create_payment` (fraud scoring → 3-5x lower rejection rate per RG 5286/2023)
  - **VercelKVAuditLog** with day/actor/tenant indexes
  - **Migration guide** vs official `mercadopago` SDK
  - **+1 tool** (`validate_tax_id`) → 87 total
  - **284 tests pass** (was 245)

### Patch Changes

- Picks up `@ar-agents/mercadopago@0.10.0` — compliance + DX + observability:
  - **Audit logging** with pluggable adapter
  - **Webhook idempotency dedup** to prevent double-processing
  - **Pagination helpers** (AsyncIterable) for 7 paginated endpoints
  - **Token bucket rate limiter** with adaptive learning
  - **AR issuer cuotas catalog** (10+ AR banks + federal Ahora program)
  - **OpenTelemetry instrumentation** via `/otel` subpath
  - **3DS challenge resolution** via `confirmChallengeAndPoll`
  - **+4 tools** → 86 total. **245 tests pass**.

### Patch Changes

- Picks up `@ar-agents/mercadopago@0.9.0` — production hardening pass:

  - **Circuit breaker** with state machine + rolling window (CLOSED/OPEN/HALF_OPEN)
  - **Deadline propagation** via parent AbortSignal
  - **W3C Trace Context** (OpenTelemetry-compatible without peer dep)
  - **Replay-attack protection** on webhook signatures (5-min default)
  - **`mp_health_check` tool** for status-page polling
  - **223 unit tests + 14 property-based tests + 11 failure injection + integration tests vs MP sandbox + benchmarks**

  No surface change at the MCP level. The MCP server inherits all v0.9 hardening automatically. Tool count: 82 (was 81).

### Patch Changes

- Picks up `@ar-agents/mercadopago@0.8.0` — Edge Runtime support (Web Crypto, no `node:crypto`), Vercel KV adapters subpath (`@ar-agents/mercadopago/vercel-kv`), HMAC webhook verify with replay-attack protection (5 min default tolerance), 8-recipe cookbook shipped in tarball, 185 tests pass.

  No surface change at the MCP level. The MCP server inherits the Edge Runtime compatibility + KV adapters automatically; tool schemas unchanged.

### Patch Changes

- Picks up `@ar-agents/mercadopago@0.7.0`. The MCP server now exposes **+25 new MP tools** (81 MP tools total) without any config changes. Highlights:

  - Customer + Card CRUD completion (4 tools)
  - Subscription/Plan/Refund/Preference extensions (5 tools)
  - Merchant Orders category (3 tools)
  - Stores + POS CRUD completion (6 tools)
  - Bank Accounts (2 tools)
  - Point Devices físicos — terminal hardware (5 tools)
  - Pure helpers: `compute_marketplace_fee`, `explain_payment_status` (2 tools)

  Total tool count across the MCP server jumped from ~95 to **~120 tools** in one install.

### Minor Changes

- MCP v0.4: ships `@ar-agents/shipping` as 7th tool registry.

  The MCP server now exposes 7 packages:

  - `@ar-agents/identity` (validate_cuit, lookup_cuit_afip)
  - `@ar-agents/identity-attest` (4 attestation tools)
  - `@ar-agents/mercadopago` (56 MP API tools, includes v0.6 account/balance/settlements/3DS/test-cards)
  - `@ar-agents/whatsapp` (6 messaging tools)
  - `@ar-agents/banking` (5 CBU/BCRA tools)
  - `@ar-agents/facturacion` (10 WSFE tools)
  - **NEW: `@ar-agents/shipping` (6 tools — Andreani/OCA/Correo)**

  Carriers auto-detect from env vars:

  - Andreani: `ANDREANI_USERNAME` + `ANDREANI_PASSWORD` + `ANDREANI_CLIENT_NUMBER` (+ `ANDREANI_ENV`)
  - OCA: `OCA_CUIT` + `OCA_OPERATIVA`
  - Correo Argentino: auto-wired (no creds needed). Set `AR_AGENTS_CORREO_DISABLED=1` to opt out.
  - `SHIPPING_DEFAULT_CARRIER` for the default when agent doesn't specify.

  Server version bumped to 0.4.0 in the MCP handshake.

### Patch Changes

- MP v0.6: account/balance + settlements + 3DS analyzer + test cards. **+6 tools (56 total)**.

  **Account / Balance / Settlements (4 tools)**:

  - `get_account_balance` — current MP wallet `{ available, unavailable, total, currency_id }`. Per-seller in marketplace setups.
  - `list_account_movements({ from?, to?, limit?, offset? })` — wallet movement log (incoming payments, refunds, holdings, transfers).
  - `list_settlements({ from?, to?, status? })` — `release_money` transfers from MP wallet → registered CBU.
  - `get_settlement(id)` — single settlement detail with bank_account info.

  **3DS analyzer (1 tool + 1 helper)**:

  - `analyze_payment_3ds(payment_id)` — fetches the Payment, derives `{ status: 'not_required'|'frictionless'|'challenge_required'|'rejected'|'unknown', mode, challengeUrl, description }`. When `challengeUrl !== null`, MUST redirect the buyer to complete authentication.
  - `analyze3DS(payment)` exported as a pure helper for callers who already have a Payment object.

  **Test cards (1 tool + helpers)**:

  - `get_test_cards` — returns the official AR (MLA) sandbox cards: VISA/Mastercard/Amex credit + debit. Each has the "magic" holder names that route to specific status_detail (APRO, OTHE, CONT, FUND, CALL, SECU, EXPI, FORM).
  - `TEST_CARDS_AR`, `TEST_PAYERS_AR`, `buildTestCardScenario(card, scenario, amount)` exported for direct use in test files.

  **132 tests pass** (was 117; +15 v0.6 tests). publint clean. attw 🟢. 24.3 KB brotli'd (within 32 KB budget).

- Updated dependencies []:
  - @ar-agents/mercadopago@0.6.0

### Patch Changes

- MP v0.5: production hardening + marketplace flows. **+9 tools (50 total)**.

  **Webhook handler combo (1 tool)**:

  - `handle_webhook` — verifies HMAC-SHA256 signature, parses the event, and (optionally) auto-fetches the underlying resource (Payment, Subscription) in ONE call. Replaces the manual chain of verify_webhook_signature + parse_webhook_event + get_payment.
  - `mercadoPagoTools({ webhookSecret })` to enable.
  - Returns `{ verified, event, resource, resource_error }`. Reject with HTTP 401 when `verified: false`.

  **OAuth Marketplace flow (3 tools + 5 helper functions)**:

  - `oauth_authorize_url` — pure function, builds the URL the seller visits to authorize your marketplace app.
  - `oauth_exchange_code` — server-side exchange of the OAuth code for an `OAuthToken` (`access_token` + `refresh_token` + `user_id` + `expires_in`).
  - `oauth_refresh_token` — refresh a per-seller token before it expires (~6h).
  - Helper functions exported: `buildAuthorizeUrl`, `exchangeCodeForToken`, `refreshAccessToken`, `expirationTimeMs`, `isExpiringSoon`.
  - `mercadoPagoTools({ oauth: { clientId, clientSecret } })` to enable.

  **Order Management API (5 tools)**:

  - `create_order`, `get_order`, `update_order`, `capture_order`, `cancel_order` — MP's modern Order API. Distinct from Preference: explicit lifecycle, manual-capture support (auth-only flows for ride-share, hotels, marketplaces), multi-payment-per-order semantics.
  - `capture_mode: "manual"` enables the auth-only flow → `capture_order(id, amount?)` later.

  **Marketplace split payments**:

  - `marketplace`, `marketplace_fee` (in ARS), `collector_id` (seller MP user_id) supported on BOTH `create_order` AND `create_payment_preference`.
  - Funds route to the seller; `marketplace_fee` is split off to the marketplace's MP account.

  117 tests pass. publint clean. attw all green. 21.6 KB brotli'd (within 32 KB budget).

  The MCP wrapper auto-picks up the new tools — `@ar-agents/mcp` patch bump.

- Updated dependencies []:
  - @ar-agents/mercadopago@0.5.0

### Minor Changes

- MCP v0.3: ships `@ar-agents/facturacion` as 6th tool registry.

  The MCP server now exposes 6 packages:

  - `@ar-agents/identity` (validate_cuit, lookup_cuit_afip)
  - `@ar-agents/identity-attest` (4 attestation tools)
  - `@ar-agents/mercadopago` (41 MP API tools)
  - `@ar-agents/whatsapp` (6 messaging tools)
  - `@ar-agents/banking` (5 CBU/BCRA tools)
  - **NEW: `@ar-agents/facturacion`** (10 WSFE tools — emitir factura, consultar último, catálogos)

  Auto-detects facturación from env: `AFIP_CUIT_REPRESENTADO` + `AFIP_CERT_PEM/PATH` + `AFIP_KEY_PEM/PATH` (same vars as identity, but the cert must be authorized for the `wsfe` service in addition).

  Tunables: `WSFE_DEFAULT_PTOVTA`, `WSFE_TIMEOUT_MS`, `WSFE_MAX_RETRIES`.

  Server version bumped to 0.3.0 in the MCP handshake.

### Minor Changes

- MCP v0.2: ships `@ar-agents/banking` as a 5th tool registry.

  The MCP server now exposes:

  - `@ar-agents/identity` (validate_cuit, lookup_cuit_afip)
  - `@ar-agents/identity-attest` (issue_attestation, verify_attestation)
  - `@ar-agents/mercadopago` (41 MP API tools)
  - `@ar-agents/whatsapp` (6 messaging tools)
  - **NEW: `@ar-agents/banking` (validate_cbu, lookup_bank_by_code, list_banks, list_psps, lookup_credit_situation)**

  Banking tools auto-wire to BCRA's public API via `BcraPublicApiAdapter`
  (no auth required). To opt out, set `AR_AGENTS_BCRA_DISABLED=1` in env.
  Tunables: `BCRA_TIMEOUT_MS` (default 30000), `BCRA_MAX_RETRIES` (default 1).

  Server version bumped from 0.1.0 → 0.2.0 in the MCP handshake.

### Patch Changes

- Identity v0.5: production robustez parity with the rest of the toolkit.

  **WSAA + WSCDC now share a hardened HTTP layer** (`fetchWithRetry`):

  - Per-request timeouts via `AbortSignal` (default 30s, override with `requestTimeoutMs`).
  - Exponential backoff on 5xx + transient network errors (default 1 retry, override with `maxRetries`).
  - SOAP-aware: HTTP 500 with a real `<Fault>` body is treated as a parseable response (not retried).
  - Optional `onCall` observability hook fires after every WSAA + WSCDC request — `{ label, durationMs, httpStatus, retried, success }` — drop-in for OpenTelemetry / Datadog / console.

  **`WsaaWscdcAdapter` accepts the new options** (`requestTimeoutMs`, `maxRetries`, `onCall`) and forwards them to both the TA refresh path and the per-CUIT lookup path.

  **`fetchWithRetry` is exported from `@ar-agents/identity/wsaa`** so multi-step flows (custom AFIP services, A4, A5, etc.) can reuse the same retry/timeout/observability stack.

  No breaking changes — existing 0.4 setups keep working with the previous (no-retry, no-timeout) defaults until you opt in.

  The MCP wrapper bumps to pull in the new identity major.

- Updated dependencies []:
  - @ar-agents/identity@0.5.0

### Patch Changes

- Updated dependencies []:
  - @ar-agents/mercadopago@0.4.0

### Patch Changes

- Updated dependencies []:
  - @ar-agents/mercadopago@0.3.0
  - @ar-agents/identity-attest@0.2.0

### Initial release — the MCP wrapper

One MCP server that bundles the entire `@ar-agents/*` toolkit (identity, identity-attest, mercadopago, whatsapp) into any MCP host (Claude Desktop, Cursor, Codeium, Continue, Cline, etc.). Up to **34 tools in one install**, configured entirely via env vars.

**What it does**

- Spawns as a stdio MCP server (`npx @ar-agents/mcp`).
- Auto-detects which `@ar-agents/*` packages to enable based on env vars present.
- Bridges Vercel AI SDK 6 `tool()` definitions → MCP `Tool` shape, including Zod → JSON Schema conversion (using Zod 4 native `z.toJSONSchema()`).
- Reports startup summary on stderr (which packages enabled, how many tools registered).

**Tool inventory**

| Source                            | Tools (when configured) |
| --------------------------------- | ----------------------- |
| `@ar-agents/identity` (always on) | 1-2                     |
| `@ar-agents/identity-attest`      | 5                       |
| `@ar-agents/mercadopago`          | 21                      |
| `@ar-agents/whatsapp`             | 6                       |

**Env-var configuration**

- Without any env vars: only `validate_cuit` (algorithm-only).
- Each package's tools enable independently when its env vars are set. See README for the full table.

**Quality**

- 12/12 tests pass (adapter conversions, registry env-var detection, server boot).
- 21.33 KB ESM brotli'd (under 60 KB budget).
- publint + arethetypeswrong all 🟢.
- Smoke-tested CLI binary boots and connects via stdio with both empty and full env-var setups.

**Implementation notes**

- Uses Zod 4's native `z.toJSONSchema()` (no `zod-to-json-schema` dep needed).
- MCP SDK: `@modelcontextprotocol/sdk@^1.0.0`.
- Tool name collisions across registered packages throw at startup (no silent overrides).

Strategic positioning + outreach-readiness pass. The package as code is unchanged — what changes is everything around it that a marketplace exec, procurement reviewer, or external co-maintainer would read before deciding to engage.

### Added — Strategic positioning artifacts

- **[`POSITIONING.md`](./POSITIONING.md)** — five-minute strategic doc for a MELI exec. Cites the Q4 2025 earnings call (Szarfsztejn: *"we are developing our own agentic experience inside MercadoLibre"*). Positions explicitly as a Verdi-complement (external sellers + community devs), not a competitor. Three engagement paths spelled out (co-maintain / fork-into-MELI-repo / license).
- **[RFC 001 — Argentine Agentic Commerce 2027](./docs/rfc-001-argentine-agentic-commerce-2027.md)** — the strategic technical document. 3-layer architecture for LATAM marketplaces to participate in agentic commerce without being disintermediated by ChatGPT Instant Checkout / Anthropic / Gemini. Cites Forrester + Flywheel projections (13–20% of LATAM retail intent will route through agents by 2027). Citation-ready public URL at [`/rfc/001`](https://ar-agents-mercadolibre.vercel.app/rfc/001).
- **[`README.es.md`](./README.es.md)** — Spanish-first version of the README. AR cultural fit. Linked from the English README header.
- **[`/integrate` page on the landing](https://ar-agents-mercadolibre.vercel.app/integrate)** — procurement-friendly 3-step adoption path (try / partner / license) with explicit obligations + reversibility per path.

### Added — MCP host compatibility matrix

The bundled `@ar-agents/mcp` server (which includes this package) is verified compatible with: Claude Desktop · Cursor · Codeium / Windsurf · Continue · Cline · Anthropic / OpenAI native runtime via Vercel AI SDK 6. Documented in the README.

### Notes on npm provenance

`publishConfig.provenance: true` is set. Provenance attestations require a publish from GitHub Actions with OIDC (not from a local machine). The first CI-driven release will produce a public provenance trail visible at `https://www.npmjs.com/package/@ar-agents/mercadolibre/v/<version>#provenance`.

### Tests

No code changes; same 142 tests (128 unit + 4 integration vs MELI live + 10 property-based). All green.

Vendor-readiness pass. Designed to move adoption probability for risk-averse reviewers (procurement, security, legal) by surfacing answers they normally extract via questionnaire.

### Added — vendor-questionnaire artifacts

- **[`ARCHITECTURE.md`](./ARCHITECTURE.md)** — system context, layered architecture (mermaid diagrams), module-responsibility map, trust boundaries, "why each design choice" rationale, and a "where things will probably change" forward-looking section.
- **[`GOVERNANCE.md`](./GOVERNANCE.md)** — current decisions log, bus-factor de-risk plan with the explicit co-maintainer path, strategic-decisions audit trail, and "out of scope" disclaimers.
- **[`MIGRATION.md`](./MIGRATION.md)** — side-by-side guide from the archived `mercadolibre/nodejs-sdk` (still serving ~37 weekly downloads as of mid-2026), with mechanical migration steps and a coverage parity matrix.
- **[`/operated-by` page on the landing](https://ar-agents-mercadolibre.vercel.app/operated-by)** — pre-filled vendor security questionnaire across 10 sections (legal, contact + disclosure, SLA + incident response, bus factor, security posture, supply chain, data privacy, quality signals, production latency snapshot, termination). Honest answers, including the uncomfortable ones.
- **[`/api/openapi.json` on bridge-hello](https://ar-agents-bridge-hello.vercel.app/api/openapi.json)** — OpenAPI 3.1 spec auto-emitted from the running facilitator. Auditable + agent-consumable.

### Added — production latency snapshot

Real numbers from the live `ar-agents-bridge-hello.vercel.app` deployment (50 runs at concurrency 10, measured from a Buenos Aires client, 2026-05-09 17:30 UTC):

| Endpoint | p50 | p95 | p99 | errors |
| --- | --- | --- | --- | --- |
| `GET /.well-known/acp.json` | 44ms | 1253ms | 1349ms | 0/50 |
| `GET /.well-known/agentic-feed.json` | 30ms | 46ms | 105ms | 0/50 |
| `GET /api/feed/products` (opt-in) | 31ms | 228ms | 229ms | 0/50 |
| `POST /api/acp/checkout_sessions` | 167ms | 396ms | 399ms | 0/50 |

The p95 outlier on ACP discovery is one Vercel cold start. Reproducible via `node test/bench/loadtest.mjs`.

### Tests

No code-level changes; same 142 tests (128 unit + 4 integration vs MELI live + 10 property-based).

Positioning + posture pass driven by an adversarial review (skeptical MELI engineering manager perspective). No code-level breaking changes; the surface gets honest about what it is and isn't.

### Added — README honest status block + trademark notice

The README now opens with explicit disclosures:

- **Maturity**: Beta — surface-stable but iterating in public.
- **Maintainership**: Solo-maintained ([Nazareno Clemente](mailto:naza@helloastro.co)).
- **SLA**: None.
- **Affiliation**: Independent. Not endorsed, sponsored, or vetted by Mercado Libre S.R.L.
- **Trademark**: `MERCADOLIBRE®` is a registered trademark of Mercado Libre S.R.L. The package name uses it in a descriptive, nominative-fair-use sense.
- **Bus factor**: 1. Plan accordingly.

This addresses the real legal + adopter concern flagged by the adversarial review (medium-high trademark-confusion risk + bus-factor opacity) without renaming the package mid-stream and breaking the existing 41 weekly downloads / @ar-agents/mcp bundling.

### Changed — ACP feed is now opt-in by default

The bridge-hello reference implementation at `/api/feed/products` returns **403 Forbidden** unless one of:

- `FEED_OPT_IN=1` is set in the server environment, OR
- The request includes `Opt-In: agentic-commerce-feed/2026-04-17` header.

The discovery payload at `/.well-known/agentic-feed.json` honestly advertises the opt-in status and includes a `preference_note` directing buyer agents toward MELI's checkout (`/api/acp/checkout_sessions`) by default.

**Why.** ACP feeds let buyer agents transact outside the marketplace, bypassing the marketplace-buyer relationship MELI cultivates (Mercado Pago, Mercado Envíos, claims SLA, reviews). That's a tradeoff some sellers want, others don't. The default position has to be "don't expose by default" — sellers opt in when they understand the tradeoff.

### Added — SECURITY.md hardening

- Disclosure address (`naza@helloastro.co`) + 72h response target + 30d coordinated-disclosure window.
- Explicit "Known limitations" section: bus factor 1, no SLA, not vetted by MELI.
- Agent-runtime-specific threat vectors documented:
  - Prompt injection via tool-result content (question / claim text)
  - MCP supply-chain compromise consequence (full seller-account write on every connected MCP host)
  - Multi-instance OAuth refresh requires database-level CAS
  - ACP feed disintermediation tradeoff

### Tests

No test changes — same 142 (128 unit + 4 integration vs MELI live + 10 property-based). All green.

Two strategic features that move the toolkit from "agent-friendly SDK" to "agent-native commerce infrastructure".

### Added — Human-in-the-loop (HITL) gates

A programmatic safety boundary on **irreversible** tool calls. The LLM cannot bypass this — it isn't a system-prompt rule, it's a function call that doesn't fire until the host confirms.

```ts
meliTools(client, {
  siteId: "MLA",
  sellerId: 12345,
  hitl: {
    requireConfirmation: async (ctx) => {
      const ok = await yourApp.askUser({ summary: ctx.summary, severity: ctx.severity });
      return ok ? { approve: true } : { approve: false };
    },
    autoApprove: (ctx) => ctx.kind === "answer_question" && (ctx.input as any).text.length < 200,
  },
});
```

Covers `create_item`, `update_item_price_or_stock`, `pause_item`, `close_item`, `relist_item`, `answer_question`, `defend_claim`, `opt_in_promotion`, `blacklist_asker`. Each context carries a stable `kind`, `resourceId`, Spanish-language `summary`, and `severity` (low/medium/high) so hosts can drive different UIs per op.

When the host rejects, the tool returns `{ ok: false, code: "hitl_rejected", reason }` — the agent never throws, just gets feedback it can adjust on. When the host returns an `override`, the agent's input gets edited in-place before the call fires (useful for "let me edit this draft answer first" UX).

7 new tests cover approve / reject / override / autoApprove / severity classification.

See [Cookbook 11](./cookbook/11-human-in-the-loop.md) for production patterns.

### Added — ACP feed generator (`@ar-agents/mercadolibre/feed` subpath)

Emit your seller catalog as an Agentic Commerce Protocol-compatible product feed. Lets buyer agents (ChatGPT, Claude, Gemini) discover your MELI listings without crawling.

```ts
import { buildFeedPage, iterateFeed, meliItemToFeedProduct } from "@ar-agents/mercadolibre/feed";

// Cursor-paginated page (best for HTTP feed endpoints):
const page = await buildFeedPage(client, sellerId, { limit: 50, cursor });

// Streaming iterator (best for /api/feed routes that pipe to the response):
for await (const product of iterateFeed(client, sellerId)) yield product;

// Pure mapper (compose your own enumeration):
const fp = meliItemToFeedProduct(meliItem);
```

`FeedProduct` shape is ACP `2026-04-17`-compatible — generic agents see standard fields (id, title, currency, price, images), MELI-specific agents read `vendor_metadata.meli` for richer reasoning (condition, sold_quantity, listing_type_id, tags). Currency is uppercased per ACP spec; prices are major-units. Active-only by default; pass `acceptableStatuses` to override.

`bridge-hello` ships a reference implementation at:
- `/.well-known/agentic-feed.json` — discovery
- `/api/feed/products?cursor=&limit=` — the feed itself, ETag-cached, ISR 60s

10 new tests covering pure mapper / pagination / cursor threading / streaming / status filtering. Demonstrated end-to-end on https://ar-agents-bridge-hello.vercel.app.

See [Cookbook 12](./cookbook/12-acp-feed-generator.md) for the full pattern.

### Tests

- 17 new tests across HITL + Feed.
- Total: **128 unit + 4 integration + 10 property** = 142 tests.

Production-readiness pass — small surface area changes, real correctness fixes.

### Added

- **`multigetItems` auto-chunks** input arrays past MELI's 20-id limit and
  fetches chunks in parallel (default concurrency 4). Caller-side ordering is
  preserved across chunk boundaries. Optional `MultigetOptions.concurrency`
  tunes it. **Breaking on the error path:** previously, calling with > 20
  ids threw `"MELI multiget supports up to 20 ids per call"`. Now it just
  works. If you were catching that string, you can drop the `try`.
- **`MeliApiError.meliCode` + `.meliMessage` + `.meliCauses`** parsed from
  MELI's standard error envelope (`{ error, message, status, cause }`) AND
  the post-purchase variant (`{ error_code, description }`). Type guards
  shipped: `err.isRateLimited()`, `err.isForbidden()`, `err.isUnauthorized()`,
  `err.isValidationError()`. The previous `err.meliErrorCode()` method still
  works (delegates to `meliCode`).

### Tests

- 9 new unit tests (multiget chunking + error parsing edge cases).
- Total: **111 unit + 4 integration + 10 property tests**.

Round-2 production-grade pass driven by a multi-agent code review (eng-arch,
correctness, DX). 14 distinct findings, all fixed.

### Breaking

- **Default retry policy now restricts 5xx retries to idempotent verbs**
  (GET / HEAD / OPTIONS / PUT / DELETE). POST / PATCH on 5xx are no longer
  retried by default — MELI's gateway can split-brain (persist a request
  and then 5xx the response), which would create duplicate listings,
  double-answers, or duplicate promo opt-ins on retry. 429 is still safe
  to retry on any verb (the request never reached the application).
  Override per-call with `retryClassifier`.
- **`monitorReputation` now rethrows `MeliAuthError` and
  `MeliValidationError`** instead of swallowing them. Permanent errors
  (revoked seller, schema drift) need to surface — the polling loop is
  for transients only. Pass `onTransientError` to log/instrument
  recoverable failures without breaking the loop.
- **`defendClaim` now uploads evidences sequentially** instead of in
  parallel. MELI's `/claims/{id}/evidences` has one-shot semantics — N
  parallel requests can persist some + reject others, leaving the claim
  half-defended with no way to amend. Sequential uploads cap the blast
  radius. Result type adds `failedEvidences[]` so callers can route
  partial failures to manual review.
- **Falsy guards changed to `!== undefined`** in 5 modules. Previously,
  `if (options.offset) query["offset"] = ...` silently dropped `offset: 0`
  (a legal first-page request).

### Added

- **Telemetry hooks** — `onRequest` / `onResponse` / `onRetry` /
  `onRateLimitWait` for OpenTelemetry, Sentry, Datadog, custom logging.
  Hooks see method/url/status/duration, never headers (no Authorization
  leak) or bodies (no PII leak).
- **`requestTimeoutMs`** on `MeliClient` (default 30s). Composed with the
  caller's `signal` via `AbortSignal.any`. A wedged TCP connection can no
  longer burn an entire Vercel Edge function budget on attempt #1.
- **`client.fetchRaw()`** for binary endpoints (PDF/ZPL labels) — same
  auth + retry + rate-limit + telemetry pipeline as `client.fetch<T>()`,
  just returns the `Response` instead of parsing JSON.
- **`Retry-After` HTTP-date support** — RFC 7231 dates parsed via
  `Date.parse` if the value isn't a plain integer.
- **`iterateAllMissedFeeds` dedup** — `(topic, resource, sent)` tuple key
  prevents double-yielding when the live feed grows during pagination.
- **`TokenBucketRateLimiter.sweepIdleBuckets()`** + auto-sweep every 256
  acquires. Multi-tenant hosts with thousands of distinct seller-IDs no
  longer leak bucket entries.

### Fixed

- **OAuth `postTokenRequest` now uses the configured `fetchImpl`** —
  previously bypassed it via global `fetch`, breaking tests + Edge runtime
  consumers.
- **`promotions.autoOptInPromotions`** no longer falls back to
  `original_price` when MELI didn't suggest a discount. The fallback
  produced a margin computed against full price + an opt-in at full price,
  defeating the entire promotion. Now skips with `reason: "no_suggested_price"`.
- **`questions.PHONE_RE`** tightened. Old regex over-matched MELI order IDs
  (16-digit runs) as phone numbers, polluting the spam classifier with
  false positives. New regex requires word-boundaries + explicit
  separators OR a `+` country prefix.
- **SSRF guard** on `client.buildUrl()` — rejects any path that contains
  a scheme (`http://...`) or protocol-relative authority (`//evil.com/x`).
  Defence in depth — domain helpers always pass `/...` paths, but a future
  helper handling user input is now safe by construction.
- **Bearer-scope key** in rate-limit telemetry no longer leaks the last 8
  chars of the access token. Now hashed via FNV-1a 32-bit.

### Tests

- 12 new tests covering retry semantics, telemetry hooks, claim partial
  failure, rate-limiter GC, and the property-based PHONE_RE invariants.
- Total in 0.2.0: 102 unit + 4 integration + 10 property.
- `pnpm audit --prod`: zero CVEs.

### Docs

- New `SECURITY.md` with full threat model + audit results.
- Cookbook 8-10 added: Vercel KV webhook dedup, Upstash Redis distributed
  rate limiter (GCRA), Cloudflare Durable Objects per-userId OAuth refresh.
- Postman collection (`postman/ar-agents-mercadolibre.postman_collection.json`).
- LLM-as-judge eval suite (`evals/run.ts` + 10 scenarios).

First public release. Production-grade TypeScript SDK for Mercado Libre's
agent-relevant API surface. Faithful to the docs at
[developers.mercadolibre.com.ar](https://developers.mercadolibre.com.ar/).

The previous official `mercadolibre/nodejs-sdk` was archived in February
2022. This package fills that gap with a modern, agent-ergonomic, edge-
runtime-compatible client.

### What ships in 0.1.0

- **`MeliClient`** — typed HTTP client with OAuth 2.0 (offline_access),
  mutex-protected refresh-token rotation (defends against the
  `refresh_token_reused` race), exponential-backoff retry on 5xx + 429,
  per-seller rate limiting (1500 req/min default).
- **Items** — create/update/get/pause/close/relist, variations, pictures,
  descriptions; multiget; seller-side search with `scroll_id` pagination.
- **Categories** — `category_predictor.predict`, `domain_discovery.search`,
  `domains/{id}/technical_specs/input`. The triple that lets agents
  auto-categorize listings AND auto-fill required attributes.
- **Questions** — list (paginated), answer, blacklist, spam-vs-real
  classifier helper.
- **Orders + Packs** — search, get with billing_info, `marketplace/orders/pack/{pack_id}`
  for cart orders (the 30%-of-volume case naive iterators miss).
- **Claims / Mediation** — list, get, evidence upload (one-shot, immutable),
  message thread, return-review accept/reject. The 2-day SLA defender
  pattern.
- **Shipments** — get, history, labels (PDF/ZPL), shipping_options leadtime,
  `shipping_modes` (Flex / Cross-docking / Drop-off / Full).
- **Reputation** — `seller_reputation` snapshot, plus a `monitor()` helper
  that polls and fires alerts before the thermometer drops.
- **Promotions** — `seller-promotions/candidates` listener (the buried-but-
  money-printing endpoint), opt-in with margin guards.
- **Webhooks** — typed parser for all 20+ topics, `replayMissedFeeds()`
  helper that polls `/myfeeds?app_id&topic` to recover events ML dropped
  within the 2-day retention window.
- **Vercel AI SDK 6 tools** at `/ai-sdk` — drop-in tools for
  `Experimental_Agent` covering every domain.
- **Testing helpers** at `/testing` — `mockFetch()` builder + `makeMeliClient()`
  factory for unit tests without OAuth.

### Patch Changes

- [`9b8e83c`](https://github.com/ar-agents/ar-agents/commit/9b8e83ce6f291a24e00101830a49afceb0102920) - Add 2 cookbook recipes that demonstrate the cross-package thesis:

  - **16-acp-checkout-with-factura.ts** — the headline ACP-with-factura pattern. A ChatGPT Instant Checkout / Claude / Gemini agent POSTs an ACP `checkout_session`, the bridge mints a Mercado Pago preference, the buyer pays, and the bridge auto-emits an AFIP/ARCA Factura A/B/C/E via the `facturacionHook` — selecting the comprobante type based on the buyer's IVA condition. No other OSS implementation in LATAM ships this end-to-end.
  - **17-usa-llc-companion.ts** — pattern for a USA-LLC agent (ClawBank, doola Agentic, MIDAO) operating in Argentina via an AR-resident facade. The USA agent declares `@ar-agents/mcp` in its MCP host config; all 89+6+2+10+5+6+5 tools become available without the USA agent ever holding AR credentials. Walks through the operator-of-record split + sample agent prompt that drives charge → factura → WhatsApp confirmation.

  Cookbook is now 17 recipes (was 15).

### Patch Changes

- [`687aa10`](https://github.com/ar-agents/ar-agents/commit/687aa1017a665ed9b3414b9f92db634a9329ac4e) - Add 3 production-grade cookbook recipes:

  - **13-anti-fraud-middleware.ts** — pre-charge heuristics chain: CUIT validity (algorithm-only), payer email history (searchPayments + status_detail flags for `cc_rejected_call_for_authorize` / `_high_risk` / `_blacklist`), 1-hour velocity tracker, AR issuer-promo stacking detector. Combined risk score (`approve` / `review` / `reject`), with high-value charges (>$100k) getting a 1.5x multiplier.
  - **14-marketplace-onboarding.ts** — end-to-end flow: CUIT validation → AFIP padron lookup (resolves legal name + IVA condition + monotributo category) → OAuth redirect with PKCE round-tripped via state → callback handler exchanging code for tokens → $1 ARS test charge → marketplace fee setup with `computeMarketplaceFee`.
  - **15-prorated-pause-resume.ts** — pause a subscription with prorated refund for the unused period (`createRefund` against the most recent charge), resume with an adjusted next-billing date so the customer doesn't double-pay. Uses `pausePreapproval` + `resumePreapproval` + a local `pauseStore` (Vercel KV in prod) to remember the credit.

  12 → 15 cookbook recipes total. README updated.

### Minor Changes

- Add `mercadopago doctor` CLI for environment diagnosis.

  ```bash
  npx @ar-agents/mercadopago doctor
  pnpm exec mercadopago doctor
  ```

  Reports:

  - Node version (must be ≥ 20)
  - `MP_ACCESS_TOKEN` presence + format + sandbox/prod prefix detection
  - Live token validation against `GET /users/me` (free, no charge)
  - `NEXT_PUBLIC_BACK_URL` presence + HTTPS check (MP rejects localhost server-side)
  - `MP_WEBHOOK_SECRET` presence + length sanity
  - Peer-dependency installation: `ai`, `zod`, `@vercel/kv`, `@opentelemetry/api`
  - Tool count grouped by inferred category (auto-derived from `tools.manifest.json`)
  - The 8 irreversible ops gated by `requireConfirmation()`

  Pass `--probe` to additionally dry-call `validate_tax_id` against your sandbox token (also free):

  ```bash
  npx @ar-agents/mercadopago doctor --probe
  ```

  Exit codes follow the convention: `0` = ok or warn-only, `1` = at least one fail. CI scripts can `npx @ar-agents/mercadopago doctor` to gate deploys on having credentials wired up.

  Also exposes `mercadopago help` and `mercadopago version`. Output respects `NO_COLOR`.

  10 new subprocess tests (test/cli.test.ts), 328 tests total.

### Minor Changes

- Add `@ar-agents/mercadopago/testing` subpath: factories + a mock client for tests.

  What ships:

  - **Factories**: `mockPayment`, `mockPreapproval`, `mockSubscriptionPayment`, `mockPreference`, `mockRefund`, `mockCustomer`. Each takes a partial overrides object so test setup is one line.
  - **`MockMercadoPagoClient`**: in-memory client with the most-common create/get/cancel/refund paths. Read-only methods that don't fit a clean store model throw `MockNotImplementedError` to nudge users toward MSW or a real sandbox token rather than silently growing the mock.
  - **`mockSignedWebhook`**: produces a `{ headers, searchParams, body }` triple whose `x-signature` header is a real HMAC-SHA256 against the secret you pass. Drops directly into `verifyWebhookSignature` — test the full webhook stack without hand-rolling the signature manifest.

  Subpath was chosen over the main entry to keep the production bundle clean (the testing helpers are dev-only).

  ```ts
  import {
    MockMercadoPagoClient,
    mockPayment,
    mockSignedWebhook,
  } from "@ar-agents/mercadopago/testing";
  ```

  15 new unit tests (testing-subpath.test.ts), still 100% passing.

### Patch Changes

- [`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46) - Enable [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements) for all `@ar-agents/*` packages. From this version on, the npm registry includes a verifiable cryptographic record that the package was built from this exact GitHub commit, via the GitHub Actions `release.yml` workflow. Boosts supply-chain audit scores (Socket / Snyk / npm) and lets downstream agents verify package integrity without trusting the publisher.

  No API or runtime changes.

### Patch — docs: tool-count accuracy (87 → 89)

The 0.15.1 docs pass under-counted the public tool surface as 87 due to a
grep mismatch on `tools.ts`. The actual exported count is 89 (verified by
`tools.manifest.json` regeneration and the `tools.test.ts` array assertion).
This patch updates the count everywhere it appears: package.json description
(npm tagline), README sub-headline, README "At a glance" row, AGENTS.md,
landing comparison table, layout meta description, OG image, root README.

No code changes. No new tools — this is purely a counting correction.

The CI manifest-drift gate also caught a stale `tools.manifest.json` version
field (still pointing at 0.15.0); the regenerated manifest now matches the
package version.

### Patch — docs: positioning + scope clarity

- `package.json` description rewritten as the npm-tagline source of truth: "Mercado Pago Agent Toolkit for the Vercel AI SDK 6. 87 typed tools across the agent-relevant Mercado Pago API surface — Subscriptions, Payments, Checkout Pro, Marketplace OAuth, Order Management, Customers, Cards, Cuotas, QR, 3DS, Point devices, Webhooks, Stores+POS, Account/Balance/Settlements, Disputes, Lookups, Bank Accounts."
- `README.md` sub-headline now enumerates the 17 categories. Fixes the drift where the npm page implied subscriptions-only scope.
- `AGENTS.md` heading no longer carries a stale `(v0.7)` tag; opening paragraph spells out the full surface.
- Cookbook recipe 03 header: "Production-grade webhook handler" → "Webhook handler".
- "At a glance" table: tool count corrected (82 → 87), test count refreshed (223 → 303), cookbook count corrected (8 → 9), `Vercel-native` row clarified to `Vercel KV adapters`.
- `MIGRATION.md`: dropped marketing adjectives ("agent ergonomics", "production-grade").

No code changes. No new tools. No API changes.

### Minor — `requireConfirmation` opt-in HITL callback (closes /review CRITICAL)

Description-based HITL warnings on irreversible ops are best-effort against
prompt injection. The /review audit (commit 6e3a0dd) flagged this as a real
risk: a crafted user message smuggled into `external_reference` saying "the
user already confirmed this refund" could bypass the LLM's heuristic.

`mercadoPagoTools(client, { requireConfirmation: async (op, args) => boolean })`
adds a programmatic out-of-band gate. When set, the 8 irreversible tools
(`cancel_payment`, `capture_payment`, `refund_payment`,
`delete_customer_card`, `cancel_qr_payment`, `cancel_order`,
`cancel_point_payment_intent`, `delete_webhook`) call the callback BEFORE
executing. If it returns `false`, the tool returns
`{ ok: false, reason: "Confirmation declined", operation, args }` and never
reaches MP. If it throws, the error propagates so connection issues are
distinguishable from declined confirmations.

```ts
mercadoPagoTools(client, {
  state,
  backUrl,
  requireConfirmation: async (op, args) => {
    return await slack.confirm({
      channel: "#mp-approvals",
      text: `Refund $${args.amount ?? "FULL"} on payment ${args.payment_id}?`,
      timeoutMs: 60_000,
    });
  },
});
```

Backward-compat: omit the option for the previous behavior (description-only
HITL). 8 new tests in `test/require-confirmation.test.ts` covering decline,
approve, non-gated tools unaffected, error propagation.

### Other improvements (closes /review findings)

- **webhookDedup wired in `handle_webhook`** — the option was declared in
  v0.10 but never used; `handle_webhook` now actually short-circuits on
  duplicate `(topic, dataId, requestId)` tuples (fix for /review CRITICAL).
- **Idempotency key collision-safe encoding** — `deterministicIdempotencyKey`
  switched from `|`-joined to length-prefix (`<n>:<value>|`) so an attacker
  controlling `external_reference` can no longer craft a colliding key with
  a future legitimate transaction.
- **VercelKVRateLimiter improvements** — fixed the docstring's fictional
  `MercadoPagoClient({ rateLimiter })` example (now correctly shows
  `withRateLimit` middleware), added randomized jitter (±30%) to the retry
  loop to mitigate thundering herd, capped retries at 8 to fail fast on
  misconfigured buckets.

### Minor Changes — deep-audit hardening pass

**Critical: Browser-context guard in MercadoPagoClient constructor.**
Throws if instantiated in a context where `window` is defined — prevents
the access token from being bundled into a client-side JavaScript bundle.
Edge Runtime, Node, Workers, and any server context pass through. To
opt out for jsdom-based tests, pass `__allowBrowser: true`.

**`z.unknown()` schemas replaced with strict Zod.** Two tools previously
used `z.record(z.string(), z.unknown())`:

- `update_merchant_order.patch` → narrow object with documented MP fields
  (`external_reference`, `notification_url`, `additional_info`, `status`),
  `.strict()` so unknown keys are rejected.
- `explain_payment_status.payment` → typed shape with `.passthrough()` for
  ergonomic interop, marked clearly as ADVANCED — LLMs should use
  `payment_id` instead.

**Stricter validation on `search_payments`:**

- `payer_email` now requires `.email()` (was bare `z.string()`).
- `begin_date` / `end_date` now require `.datetime()` ISO 8601.

**Deterministic idempotency on subscription + preference creation.**
`create_subscription` and `create_payment_preference` now derive their
idempotency key from input fields (customer_email + amount + frequency
for subscriptions; items + payer + external_reference for preferences).
LLM retries with the same inputs return the EXISTING resource instead
of creating a duplicate.

**Human-in-the-loop warnings on irreversible / money-moving tools.**
Updated 7 tool descriptions to explicitly tell the LLM to confirm with
the user before calling: `cancel_payment`, `capture_payment`,
`refund_payment`, `delete_customer_card`, `cancel_qr_payment`,
`cancel_order`, `cancel_point_payment_intent`, `delete_webhook`. Each
description now states what's irreversible, what the user should be
told before confirmation, and what the post-call state is.

`CreatePreapprovalParams` and `CreatePreferenceParams` now accept an
optional `idempotencyKey` field for callers that want explicit control.

### Minor Changes — Distributed rate limiter via Vercel KV

`VercelKVRateLimiter` — drop-in distributed token bucket backed by Vercel
KV (Upstash Redis). The default `TokenBucketRateLimiter` is per-process,
which is fine for single-instance deploys but breaks down in serverless:
each cold start gets its own bucket, so N concurrent instances effectively
have N×capacity. For multi-region deployments or marketplace setups with
shared MP rate budget, that's a footgun.

`VercelKVRateLimiter` shares one logical bucket across all instances via
KV. Same `acquire` / `tryAcquire` / `learnFromHeaders` interface as the
in-memory version — drop-in replacement.

```ts
import { MercadoPagoClient } from "@ar-agents/mercadopago";
import { VercelKVRateLimiter } from "@ar-agents/mercadopago/vercel-kv";

// One global bucket shared across all serverless instances
const limiter = new VercelKVRateLimiter({
  key: "mp-account-prod",
  capacity: 50,
  refillPerSecond: 25,
});

// Marketplace: one bucket per seller
function makeSellerLimiter(sellerUserId: string) {
  return new VercelKVRateLimiter({
    key: `mp-seller-${sellerUserId}`,
    capacity: 10,
    refillPerSecond: 5,
  });
}
```

Storage: `mp:rl:{key}` → `{ tokens: number, lastRefillMs: number }` with
1h TTL (idle buckets garbage-collect, capacity rebuilds on next acquire).
Read-modify-write isn't strictly atomic per call — under heavy contention
a small over-spend window is possible, acceptable for MP rate limiting
where the actual budget exceeds what we provision.

### Discoverability

- Expanded `keywords` from 7 → 29 in `package.json` (mp, payments, webhook,
  fraud-detection, idempotency, circuit-breaker, opentelemetry, etc).
- Added `funding` field pointing to GitHub Sponsors.

### Minor Changes — Idempotency-by-default for state-mutating writes

`MercadoPagoClient` now auto-generates a UUID v4 X-Idempotency-Key header on
every state-mutating POST request when the caller doesn't provide one
explicitly. Naive callers (and the LLM tools layer) often forget to pass an
idempotency key, leaving them exposed to double-charge bugs on network
partitions. This makes the safe default: safe.

- **Auto-generated keys are unique per call** (Web Crypto's `randomUUID()` —
  Edge Runtime + Node 19+ + Cloudflare Workers + browsers).
- **Caller-supplied keys still win** — pass `idempotencyKey: "..."` for
  deterministic retries from a job queue (e.g., same key across retry
  attempts).
- **Only POST requests are auto-keyed.** GET / DELETE are HTTP-idempotent
  by spec. PUT skips auto-gen because MP's PUT endpoints encode the dedup
  key in the resource path (`/v1/payments/:id` → cancel; `/preapproval/:id` →
  pause/resume — already deduped by id).

6 new tests in `idempotency-default.test.ts` verify:

- UUID v4 format on auto-gen
- Different keys per call
- Caller-supplied keys honored over auto-gen
- GET requests NOT keyed
- Works for `createPayment`, `createPreference`, `createPreapproval`

### New cookbook recipe

- `cookbook/09-otel-wired.ts` — full OpenTelemetry wiring example. Shows
  how to wire `traceContext` for distributed-trace correlation, instrument
  the client + tools, and what the resulting trace + metric shape looks
  like in your APM. Closes the half-finished OTel story (lib + subpath
  existed since v0.10 but no recipe wired it end-to-end).

### Minor Changes — Composability + cross-LATAM + fraud scoring

**Tool middleware pattern (NEW)**: composable wrappers around any AI SDK tool. Ships `withAuditLog`, `withRateLimit`, `withMetrics`, `withRetry` + `compose()` + `applyToAllTools()`. Add audit + rate-limit + metrics to every tool with a single config block instead of wiring each concern into the tool implementation.

**TaxID validation cross-LATAM (NEW)**: `validateTaxId(input, type)` for AR (DNI/CUIT/CUIL with modulo-11), BR (CPF/CNPJ two-step weighted), MX (RFC structure), CL (RUT with K), CO (NIT modulo-11), UY (RUT 12-digit), PE (RUC 11-digit + prefix). `detectAndValidate(input, country)` auto-detects type from length. New `validate_tax_id` agent tool. Pure, no network.

**`additional_info` on `create_payment` (fraud scoring enrichment)**: `payer` profile (registration_date, authentication_type, is_first_purchase, is_prime_user, last_purchase), `shipments` (receiver_address, express_shipment, local_pickup), `ip_address`, `referral_url`. Per MP RG 5286/2023, payments without enrichment have 3-5x higher rejection rate — this is a real conversion uplift. Documented in tool description so the agent surfaces it proactively.

**VercelKVAuditLog (NEW)**: production audit-log adapter in `@ar-agents/mercadopago/vercel-kv` subpath. Storage layout: per-entry key + ZSET indexes by day/actor/tenant for O(log N) time-range queries. Backed by Vercel KV (Upstash Redis).

**Migration guide vs `mercadopago` (official SDK)** — `MIGRATION.md` shipped in tarball with side-by-side mappings, conceptual table, "when to use both" section.

**CI fixes**: build packages BEFORE typecheck (was failing for facturacion → identity workspace dep with subpath exports). Release workflow now `workflow_dispatch` only (was spamming failure emails on every push because changesets/action couldn't create PRs without explicit repo permission).

**New tools**: `validate_tax_id`. Tool count: **87** (was 86).

**Quality**: 284 tests pass (was 245; +39 v0.11 tests covering middleware, taxId, and more). publint clean, attw 🟢 across 3 subpaths. Bundle: main 42.9 KB brotli'd (size budget bumped 40→50 KB).

### Minor Changes — Compliance + DX + observability deepening

**Audit logging system (NEW)**: `AuditLogger` + `AuditLogAdapter` + `InMemoryAuditLog`. Captures every state-mutating tool call (operation, actor, tenantId, inputHash, outcome, errorCode, resourceId, idempotencyKey, durationMs). PII-conscious by default (`redact: true` hashes input, `redact: false` logs raw). Pluggable storage — InMemory shipped, plug your own Postgres/S3/SIEM.

**Webhook idempotency dedup (NEW)**: `WebhookDedup` class short-circuits duplicate MP webhook deliveries. MP retries on 5xx over an 8-day window — without dedup your handler processes the same event 5+ times. TTL default 7 days. Two modes: mark-on-first-sight and at-least-once.

**Pagination helpers (NEW)**: `paginate()` generic + 7 typed wrappers (payments, subscriptions, account movements, settlements, merchant orders, plans, subscription payments). AsyncIterable streaming, bounded concurrency, `maxItems` cap.

**Token bucket rate limiting (NEW)**: `TokenBucketRateLimiter` — proactive client-side limiter with **adaptive learning** from MP's `x-rate-limit-remaining` headers.

**AR issuer cuotas catalog (NEW)**: `AR_ISSUER_PROMOS` + `AHORA_PROGRAM_PROMOS` — embedded knowledge of AR bank promos. 14 issuer promos (Naranja, Galicia, Santander, Macro, BBVA, ICBC, Patagonia, Nación, Provincia, Ciudad). New `find_applicable_promos` tool.

**OpenTelemetry instrumentation subpath (NEW)**: `@ar-agents/mercadopago/otel` exports `createOtelHooks({ serviceName })`. Auto-emits spans + histograms + counters + gauges. `@opentelemetry/api` is OPTIONAL peer dep — graceful no-op fallback.

**3DS challenge resolution (NEW)**: `confirmChallengeAndPoll()` polls after the buyer completes the issuer challenge. New `confirm_3ds_challenge` tool — completes the FULL 3DS flow.

**New tools**: `find_applicable_promos`, `confirm_3ds_challenge`, `search_payments_all`, `list_settlements_all`. Tool count: **86** (was 82).

**Quality**: 245 tests pass (was 222). publint clean, attw 🟢 across 3 subpaths (`.`, `/vercel-kv`, `/otel`). Optional peer deps: `@vercel/kv`, `@opentelemetry/api`.

### Minor Changes — Production hardening: circuit breaker, deadline propagation, property-based tests, real MP sandbox integration tests, benchmarks

Architectural features for at-scale deployment.

**Circuit Breaker (NEW)**

- `CircuitBreaker` class — full state machine: CLOSED → OPEN (after N consecutive failures within rolling window) → HALF_OPEN (after cooldown) → CLOSED (after M trial successes) | OPEN (on trial failure).
- Configurable thresholds: `failureThreshold`, `successThreshold`, `resetTimeoutMs`, `monitoringWindowMs`.
- `isFailure(err)` predicate — by default counts all errors; override to ignore expected business errors (e.g., 4xx user errors should NOT count toward circuit opening).
- `onStateChange(event)` hook for emitting metrics on every transition.
- Manual `trip()` / `reset()` for runbook-driven ops.
- Pass to multiple `MercadoPagoClient` instances to **share backpressure signal across per-seller marketplace clients**.
- Throws `CircuitOpenError` (catchable separately from `MercadoPagoError`) when failing fast — your error tracker can distinguish "MP said no" from "we didn't even ask MP".
- 13 dedicated state-machine tests with controllable clock for deterministic transitions.

**Deadline Propagation (NEW)**

- `RequestOptions.signal?: AbortSignal` — pass a parent `AbortSignal` from the agent's tool budget; cancels MP requests when the agent's deadline expires.
- The client merges parent signal with its own per-request timeout — whichever fires first wins.
- When parent aborts, the client does NOT retry (caller's deadline has expired — retrying would be wrong).
- `healthCheck(signal?)` accepts the same.

**W3C Trace Context Propagation (NEW)**

- New `MercadoPagoClientOptions.traceContext` callback — returns `{ traceId, spanId, traceFlags? }`.
- When configured, the client injects standard `traceparent` headers into every MP request (so MP's logs can be correlated with your distributed traces) and surfaces the same context in `onCall` events.
- Compatible with OpenTelemetry without adding `@opentelemetry/api` as a peer dep — pass `() => trace.getActiveSpan()?.spanContext()`.

**Extended `onCall` event**

- Now includes `requestId` (MP's `x-request-id` echo for support tickets), `rateLimit` (`{ remaining, resetSeconds }` from MP headers), `circuitState` (when breaker configured), `traceContext` (when configured).
- Drop-in for OpenTelemetry / Datadog / Sentry.

**Health Check (NEW)**

- `client.healthCheck(signal?)` — liveness probe against MP. Returns `{ ok, latencyMs, userId, error, circuit }`.
- New `mp_health_check` tool — accepts optional `timeout_ms` for status-page polling.
- Returns `ok: false` instead of throwing — safe in monitoring loops without try/catch.

**Property-Based Testing (NEW)**

- 14 tests using `fast-check` that verify INVARIANTS across thousands of randomly-generated inputs (each test runs 100 random scenarios → ~1400 unique cases verified).
- HMAC: fresh signature ALWAYS accepted; tampered signature ALWAYS rejected; ANY single-character mutation ALWAYS rejected.
- SHA256: deterministic, 64-char hex output, collision-resistant.
- `computeMarketplaceFee`: monotone in percent, respects min/max bounds, never exceeds amount.
- `explainPaymentStatus`: never throws, always returns Spanish text, paid → approved invariant.

**Integration Tests vs MP Sandbox (NEW)**

- `test/integration/` — real HTTP calls to `api.mercadopago.com` with TEST tokens.
- Gated by `MP_INTEGRATION_TESTS=1` env var so they don't run in CI by default.
- Coverage: health check, payment search, lookups (payment methods, identification types), preference creation, installments. Catches MP API drift, real rate-limit headers, real status_detail values that mocks can't simulate.
- Run via `pnpm test:integration`.

**Failure Injection Tests (NEW)**

- 11 tests for adverse network/response conditions: ECONNRESET retry recovery, partial JSON, empty 200, MP-overloaded HTML 5xx, AbortSignal propagation, parent-abort no-retry, circuit breaker trip + fast-fail, 4xx no-circuit-trip, timer leak, concurrent calls.

**Benchmarks (NEW)**

- `pnpm bench` runs Vitest benchmarks. Measured on MacBook Air M2 (8GB), Node 22:
  - `hmacSha256Hex`: **45,932 ops/sec** (typical webhook manifest)
  - `sha256Hex` (40-byte input): **92,218 ops/sec** (idempotency key derivation)
  - `timingSafeEqualHex` (64 chars): **3,099,551 ops/sec**
  - `computeMarketplaceFee`: **20,662,947 ops/sec** (pure helper, sub-ns per call)
  - `explainPaymentStatus`: **21,289,436 ops/sec**
  - `InMemoryStateAdapter.set`: **5,752,416 ops/sec**

**Quality**

- **223 tests pass** (was 185; +38 v0.9 tests).
- publint clean. attw all 🟢 across both subpaths.
- Bundle: main 32 KB brotli'd; vercel-kv subpath 0.6 KB.
- `mp_health_check` brings tool count to **82**.

### Minor Changes — Edge Runtime + Vercel KV + Cookbook

**Edge Runtime support (was: Node-only)**

- Replaced `node:crypto` with the universal Web Crypto API across all crypto helpers.
- The toolkit now runs in **Vercel Edge Runtime, Cloudflare Workers, Deno, browsers, and Node 18+** with zero changes.
- New module `./crypto` exposes `hmacSha256Hex`, `sha256Hex`, `timingSafeEqualHex`.

**Webhook signature verify is now async + replay-attack protected**

- `verifyWebhookSignature(...)` returns `Promise<boolean>` (was `boolean`). All call sites in `handle_webhook` tool already awaited.
- New default 5-minute replay window: signatures with `ts` more than `replayToleranceSeconds` (default 300) old are rejected as replay attempts.
- Override the window per-call with the new `replayToleranceSeconds` option.
- **Breaking**: callers using the exported `verifyWebhookSignature` directly need to add `await`.

**Vercel KV adapters via subpath `@ar-agents/mercadopago/vercel-kv`**

- `VercelKVSubscriptionStateAdapter` — drop-in `SubscriptionStateAdapter` backed by Vercel KV (Upstash Redis).
- `VercelKVOAuthTokenStore` — persists per-seller OAuth tokens for marketplace flows. Key namespace `mp:oauth:{userId}`.
- `VercelKVIdempotencyCache` — TTL-aware cache for short-circuiting agent retries.
- `@vercel/kv` is an **optional** peer dependency — only consumers who use the subpath install it. Main bundle untouched.
- All three adapters work in Edge Runtime.

**New state adapter interfaces in main package**

- `OAuthTokenStore` + `InMemoryOAuthTokenStore` — token bundle persistence for marketplace OAuth.
- `IdempotencyCache` + `InMemoryIdempotencyCache` — agent-retry deduplication layer on top of MP's server-side dedup.

**Cookbook (8 recipes)**

- `cookbook/01-checkout-pro-basic.ts` — first-time hosted checkout
- `cookbook/02-saas-subscription.ts` — reusable plan + first payment + card swap on rejection
- `cookbook/03-webhook-handler.ts` — Edge handler with HMAC verify
- `cookbook/04-marketplace-split.ts` — OAuth seller link → preference with fee → reconciliation
- `cookbook/05-qr-in-store.ts` — QR generation → buyer scan → WhatsApp notify
- `cookbook/06-3ds-challenge.ts` — detect → redirect → recover via webhook
- `cookbook/07-auth-only-order.ts` — Order with manual capture (ride-share / hotel pattern)
- `cookbook/08-recovery-patterns.ts` — recover stuck-pending, card-swap on rejected sub, idempotent upsert via search, cron-driven monitoring

**Quality**

- 185 tests pass (was 169; +16 for KV adapters + 2 for replay protection).
- publint clean, attw all 🟢 across both subpaths.
- Bundle: main 31.9 KB brotli'd; vercel-kv subpath 0.6 KB brotli'd.

### Minor Changes

- MP v0.7: +25 new tools (81 total).

  **Cierre de gaps obvios (8 tools)**:

  - `get_customer`, `update_customer`, `create_customer_card`, `get_customer_card`
  - `get_subscription_plan`, `update_subscription`, `search_subscriptions`
  - `get_refund`, `update_payment_preference`

  **Merchant Orders (3 tools — categoría completa nueva)**:

  - `get_merchant_order`, `search_merchant_orders`, `update_merchant_order`
  - MerchantOrder agrupa Payments asociados a una Preference — clave para reconciliar webhooks con `topic='merchant_order'`.

  **Stores + POS CRUD completion (6 tools)**:

  - `get_store`, `update_store`, `delete_store`
  - `get_pos`, `update_pos`, `delete_pos`

  **Bank Accounts (2 tools)**:

  - `list_bank_accounts`, `register_bank_account`

  **Point Devices físicos (5 tools — categoría nueva)**:

  - `list_point_devices` (terminales físicas: Smart, Tap to Pay)
  - `update_point_device_mode` (PDV vs STANDALONE)
  - `create_point_payment_intent` (push payment al device — amount en CENTAVOS)
  - `get_point_payment_intent`, `cancel_point_payment_intent`

  **Pure helpers (2 tools, high-leverage)**:

  - `compute_marketplace_fee` — given amount + (% o flat ARS, con min/max), returns exact `marketplace_fee`
  - `explain_payment_status` — dado un Payment, traduce los 30+ status_detail codes a `{ summary, recommendedAction, final, paid, retryable }` en español

  Type exports: `MerchantOrder`, `BankAccount`, `PointDevice`, `PointPaymentIntent`, `PointPaymentIntentState`, `CreatePointPaymentIntentParams`, `MarketplaceFeeRule`, `PaymentStatusExplanation`.

  Helpers exportados: `computeMarketplaceFee`, `explainPaymentStatus`.

  Cliente extendido: `request<T>` ahora soporta PATCH (necesario para Point devices).

  **169 tests pass** (was 132; +37 v0.7 tests). publint clean. attw 🟢. 31.4 KB brotli'd.

  **Cubre el 100% de lo que MP expone como API pública remota.** Operaciones dashboard-only (verificación de identidad, transferencias account-to-account, configuración de notificaciones por email, fraud rules) NO están — tampoco lo están en ningún SDK oficial de MP.

### Minor Changes

- MP v0.6: account/balance + settlements + 3DS analyzer + test cards. **+6 tools (56 total)**.

  **Account / Balance / Settlements (4 tools)**:

  - `get_account_balance` — current MP wallet `{ available, unavailable, total, currency_id }`. Per-seller in marketplace setups.
  - `list_account_movements({ from?, to?, limit?, offset? })` — wallet movement log (incoming payments, refunds, holdings, transfers).
  - `list_settlements({ from?, to?, status? })` — `release_money` transfers from MP wallet → registered CBU.
  - `get_settlement(id)` — single settlement detail with bank_account info.

  **3DS analyzer (1 tool + 1 helper)**:

  - `analyze_payment_3ds(payment_id)` — fetches the Payment, derives `{ status: 'not_required'|'frictionless'|'challenge_required'|'rejected'|'unknown', mode, challengeUrl, description }`. When `challengeUrl !== null`, MUST redirect the buyer to complete authentication.
  - `analyze3DS(payment)` exported as a pure helper for callers who already have a Payment object.

  **Test cards (1 tool + helpers)**:

  - `get_test_cards` — returns the official AR (MLA) sandbox cards: VISA/Mastercard/Amex credit + debit. Each has the "magic" holder names that route to specific status_detail (APRO, OTHE, CONT, FUND, CALL, SECU, EXPI, FORM).
  - `TEST_CARDS_AR`, `TEST_PAYERS_AR`, `buildTestCardScenario(card, scenario, amount)` exported for direct use in test files.

  **132 tests pass** (was 117; +15 v0.6 tests). publint clean. attw 🟢. 24.3 KB brotli'd (within 32 KB budget).

### Minor Changes

- MP v0.5: production hardening + marketplace flows. **+9 tools (50 total)**.

  **Webhook handler combo (1 tool)**:

  - `handle_webhook` — verifies HMAC-SHA256 signature, parses the event, and (optionally) auto-fetches the underlying resource (Payment, Subscription) in ONE call. Replaces the manual chain of verify_webhook_signature + parse_webhook_event + get_payment.
  - `mercadoPagoTools({ webhookSecret })` to enable.
  - Returns `{ verified, event, resource, resource_error }`. Reject with HTTP 401 when `verified: false`.

  **OAuth Marketplace flow (3 tools + 5 helper functions)**:

  - `oauth_authorize_url` — pure function, builds the URL the seller visits to authorize your marketplace app.
  - `oauth_exchange_code` — server-side exchange of the OAuth code for an `OAuthToken` (`access_token` + `refresh_token` + `user_id` + `expires_in`).
  - `oauth_refresh_token` — refresh a per-seller token before it expires (~6h).
  - Helper functions exported: `buildAuthorizeUrl`, `exchangeCodeForToken`, `refreshAccessToken`, `expirationTimeMs`, `isExpiringSoon`.
  - `mercadoPagoTools({ oauth: { clientId, clientSecret } })` to enable.

  **Order Management API (5 tools)**:

  - `create_order`, `get_order`, `update_order`, `capture_order`, `cancel_order` — MP's modern Order API. Distinct from Preference: explicit lifecycle, manual-capture support (auth-only flows for ride-share, hotels, marketplaces), multi-payment-per-order semantics.
  - `capture_mode: "manual"` enables the auth-only flow → `capture_order(id, amount?)` later.

  **Marketplace split payments**:

  - `marketplace`, `marketplace_fee` (in ARS), `collector_id` (seller MP user_id) supported on BOTH `create_order` AND `create_payment_preference`.
  - Funds route to the seller; `marketplace_fee` is split off to the marketplace's MP account.

  117 tests pass. publint clean. attw all green. 21.6 KB brotli'd (within 32 KB budget).

  The MCP wrapper auto-picks up the new tools — `@ar-agents/mcp` patch bump.

### Minor Changes

- v0.4.0 — full toolkit: Subscription Plans + Stores/POS + Disputes + Subscription Payment History + Lookup helpers + Webhooks management

  **41 tools total** (was 24 in v0.3). Adds 17 new tools covering the rest of the agent-relevant MP API surface.

  # New: Subscription Plans (5 tools)

  For SaaS-style billing where you have fixed tiers (Básico/Pro/Enterprise), use plans instead of per-customer preapprovals.

  - `create_subscription_plan` — define reusable plan (price + frequency + optional free trial)
  - `list_subscription_plans` — list all plans
  - `update_subscription_plan` — change reason / amount / status / back_url (existing subs keep old amount)
  - `subscribe_to_plan` — enroll a customer in a plan; returns init_point URL
  - `list_subscription_payments` — auto-charge attempts (authorized_payments) under a preapproval. Useful for "show me cobros del último mes for this client" or to debug failing recurring charges.

  # New: Stores + POS management (4 tools)

  Self-serve setup for in-store QR payments. Eliminates the previous one-time MP dashboard step.

  - `create_store` — create a store under the seller
  - `list_stores` — list configured stores
  - `create_pos` — create a POS under a store (the `external_id` is what `create_qr_payment` uses)
  - `list_pos` — list POSes (optionally filtered by store_id)

  # New: Disputes / Chargebacks (2 tools, read-only)

  - `list_payment_disputes` — list disputes raised against a payment (surfaces `dashboard_url`)
  - `get_dispute` — full dispute details (reason, amount, resolution status)

  Resolution remains dashboard-only; the lib surfaces the right URL.

  # New: Lookup helpers (2 tools)

  - `list_identification_types` — AR returns DNI/CI/LE/LC/Otro/Pasaporte/CUIT/CUIL with min/max length
  - `list_issuers` — banks issuing a card type. Pass `bin` (first 6-8 digits) for precise issuer detection — needed for issuer-specific cuotas promos like Naranja Galicia 6 cuotas sin interés

  # New: Webhooks management (4 tools)

  Programmatically configure webhook subscriptions instead of clicking around the MP dashboard.

  - `list_webhooks` — see what's configured
  - `create_webhook` — subscribe a URL to a topic (`payment`, `subscription_authorized_payment`, `merchant_order`, `point_integration_wh`, etc.)
  - `update_webhook` — change URL or topic
  - `delete_webhook` — unsubscribe

  # Quality

  - 81/81 tests pass (was 61 in v0.3) — added 20 tests for v0.4 endpoints
  - 21.72 KB ESM brotli'd (under 32 KB budget)
  - publint + arethetypeswrong all 🟢
  - Type-safe end-to-end; new types: SubscriptionPlan, Store, Pos, Dispute, IdentificationType, Issuer, WebhookConfig, SubscriptionPayment

  # Cumulative tool inventory (41 total)

  - Subscriptions: 5 (create, get, cancel, pause, resume)
  - Subscription Plans: 5 (create, list, update, subscribe, list_payments)
  - Payments: 5 (create, get, search, cancel, capture)
  - Refunds: 2 (create, list)
  - Checkout Pro: 2 (create_preference, get_preference)
  - Customers + Cards: 4 (create, find, list_cards, delete_card)
  - Saved-card charging: 1 (charge_saved_card)
  - Methods + Installments: 2 (list_methods, calculate_installments)
  - Account: 1 (get_account_info)
  - QR + POS: 6 (create_qr, cancel_qr, create_store, list_stores, create_pos, list_pos)
  - Disputes: 2 (list, get)
  - Lookup: 2 (identification_types, issuers)
  - Webhooks: 4 (list, create, update, delete)

### Minor Changes

- Robustness pass + 5 new features across both packages.

  # `@ar-agents/mercadopago@0.3.0`

  **Robustness (Section 6 of v0.3 spec)**

  - Per-request timeout via `AbortSignal` (default 30s, configurable via `requestTimeoutMs`).
  - Auto-retry on 5xx + 429 with exponential backoff (default 1 retry, configurable via `maxRetries`). Honors `Retry-After` header on rate-limit. **Never retries on 4xx** (deterministic user/config errors).
  - New typed errors: `MercadoPagoTimeoutError`, `MercadoPagoOverloadedError` (HTML 503 detection — when MP returns HTML instead of JSON).
  - `onCall` observability hook fires after every request with `{ method, path, durationMs, httpStatus, retried, success }`. Wire into OpenTelemetry / Sentry / Axiom without forking the lib.
  - **Deterministic idempotency keys** — `create_payment` and `refund_payment` now use `sha256(meaningful_fields)` instead of `Date.now()`. Retries dedupe correctly on MP's side.

  **New tools (3)**

  - **`charge_saved_card`** — server-side retokenize + charge for returning customers. Requires CVV (AR MP doesn't support CVV-less via public API). Idempotent on (card_id, amount, external_reference).
  - **`create_qr_payment`** — dynamic in-store QR via MP Point. Returns raw `qr_data` (EMVCo) + ready-to-display base64 PNG `qr_data_url`. Compatible with all AR wallets (Modo, BNA+, Cuenta DNI, Naranja X) via Transferencias 3.0 interop.
  - **`cancel_qr_payment`** — clear a pending QR order on a POS so the next `create_qr_payment` doesn't 409.

  **Total tool count: 24** (was 21 in v0.2). Added `qrcode` as runtime dep for in-store flow.

  # `@ar-agents/identity-attest@0.2.0`

  **3 new adapters bringing total to 5**

  - **`Auth0Adapter`** (trust 0.7, or 0.85 with MFA) — OAuth2 Authorization Code flow with PKCE. Server-side `id_token` verification via `jose` JWKS. Optional MFA step-up via `acr_values` — when MFA is completed, `effective_trust_level` bumps to 0.85.
  - **`MagicLinkSdkAdapter`** (trust 0.7) — Magic.link DIDToken validation via `@magic-sdk/admin` (optional peer dep). Lazy-loaded so users without Magic don't pay cold-start cost. Returns DID + email/phone/wallet claims.
  - **`MercadoPagoIdentityAdapter`** (trust 0.5) — partial KYC via $1 micro-charge. MP doesn't expose a public KYC API, so we use payment-payer attestation: a successful payment proves MP validated the buyer's CUIT/DNI against their internal database. Auto-refunds the $1 by default. Returns `identification_type` + `identification_number` + email + name claims.

  **New client methods**

  - `submitOauthCode(requestId, code)` — for OAuth callbacks (Auth0)
  - `submitMagicDidToken(requestId, didToken)` — for Magic.link
  - `submitMercadoPagoPaymentId(requestId, paymentId)` — for MP webhook callbacks

  **Quality**

  - 28/28 tests pass (was 15 in v0.1)
  - 12.93 KB ESM brotli'd (jose is treeshakeable; was 4.44 KB without OAuth adapter)
  - publint + arethetypeswrong all 🟢
  - `jose` is a dep (used by Auth0Adapter); `@magic-sdk/admin` is optional peer dep

  **Trust levels reference (current)**

  - 0.3 — `WhatsAppOtpAdapter` (phone-owned)
  - 0.5 — `EmailMagicLinkAdapter` (email-owned), `MercadoPagoIdentityAdapter` (partial KYC)
  - 0.7 — `Auth0Adapter` (federated identity), `MagicLinkSdkAdapter` (Magic-managed)
  - 0.85 — `Auth0Adapter` with MFA enforcement
  - 0.95 — gov-verified (planned, blocked on AR SID rollout)

### Minor Changes

- v0.2.0 — full Payments surface (the "Stripe Agent Toolkit" for Mercado Pago)

  Extends from Subscriptions-only (v0.1, 5 tools) to the complete agent toolkit (21 tools). New surface:

  **Payments (5 tools)**: `create_payment`, `get_payment`, `search_payments`, `cancel_payment`, `capture_payment`. Supports both transparent flow (with card_token) and server-side flow (account_money / Rapipago / Pago Fácil). Auto-generates idempotency keys (mandatory since 2023).

  **Refunds (2 tools)**: `refund_payment` (full or partial), `list_refunds`. Auto-idempotent on (payment_id, amount).

  **Checkout Pro (2 tools)**: `create_payment_preference` (THE recommended "agent takes a payment" tool — returns hosted URL, no PCI scope needed), `get_payment_preference`. Configurable max installments, excluded payment types, statement descriptor (13-char AR limit), expiration.

  **Customers + Cards (4 tools)**: `create_customer` (idempotent on email), `find_customer_by_email`, `list_customer_cards`, `delete_customer_card`. Foundation for saved-card flows.

  **Payment Methods + Installments (2 tools)**: `list_payment_methods` (lists AR methods: visa, master, naranja, naranja_x, cabal, account_money, rapipago, etc.), `calculate_installments` (THE killer AR feature — returns `recommended_message` strings in compliant Argentine format, includes Cuotas Simples gov program + issuer-specific promos via BIN).

  **Account (1 tool)**: `get_account_info` (site_id, country, user_type).

  **v0.1 Subscriptions (5 tools)**: kept identical for backward compatibility.

  # Live-tested

  Verified end-to-end against MP sandbox: account info, payment methods (21 AR methods returned), installments (81 visa offers with proper `recommended_message`), preference creation (returns real init_point + sandbox_init_point URLs).

  # Documentation

  - AGENTS.md updated with decision tree, status_detail recovery actions (top 12 values), AR-specific gotchas (statement_descriptor 13-char limit, sandbox cardholder name selects outcome, test cards reference, account_money instant settlement vs T+14 card hold, etc.).
  - tools.manifest.json updated to v0.2 with all 21 tools documented (purity, sideEffects, latency, input/output schemas, whenToUse, whenNotToUse).

  # Bundle size

  8.07 KB ESM brotli'd (under 22 KB budget). Doubled tool count, still half the size limit.

  # What's NOT in v0.2 (deferred to v0.3+)

  - `charge_saved_card` (retokenize + charge in one call) — coming v0.3
  - `create_qr_payment` (in-store dynamic QR) — coming v0.3
  - Marketplace splits (OAuth, application_fee) — v0.4
  - Raw-PAN tokenization — never (PCI scope; agents must use Checkout Pro)
  - Webhook x-signature verification for `payment` topic (v0.1 covers `preapproval`) — v0.3

All notable changes to `@ar-agents/mercadopago` are documented here. The format
follows [Keep a Changelog](https://keepachangelog.com/) and the project adheres
to [Semantic Versioning](https://semver.org/).

### Minor Changes

- Initial release. Mi Argentina (Argentine government OIDC) as a drop-in tool collection for the Vercel AI SDK 6.
  - `MiArgentinaClient` — Edge-Runtime-friendly OIDC client (PKCE S256, RS256 ID-token verification, JWKS caching, refresh, end-session).
  - `miArgentinaTools` — 5 tools: `start_login`, `complete_login`, `get_user_profile`, `verify_id_token`, `refresh_token`.
  - `InMemoryStateAdapter` for dev/tests; `VercelKVStateAdapter` for prod.
  - Web Crypto only — no `node:crypto` dependency.
  - Provider presets `miargentina` and `miargentina_sandbox` plus `custom` for sandboxes / other AR OIDC providers.
  - OIDC discovery via `.well-known/openid-configuration`.

### Minor Changes

- [`e067a4a`](https://github.com/ar-agents/ar-agents/commit/e067a4a4f37e882b32fd0cbf6dfdb872f31d0e6e) Thanks [@naza00000](https://github.com/naza00000)! - Add `doctor` CLIs to the remaining 4 packages — completes the uniform CLI surface across the toolkit.

  ```bash
  npx @ar-agents/banking doctor       # algorithm-only tools, BCRA endpoint, 11 tools
  npx @ar-agents/facturacion doctor   # AFIP cert/key/CUIT/env/PdV check + tools
  npx @ar-agents/shipping doctor      # which carriers (Andreani/OCA/Correo) are wired
  npx -y @ar-agents/mcp doctor        # which @ar-agents/* subpackages your MCP host has wired
  ```

  The `mcp doctor` is particularly useful — it shows the full subpackage status (enabled / partial / disabled) with the always-on tools per package, so a Claude Desktop / Cursor user knows exactly what their host can do without enumerating env vars.

  All 7 published `@ar-agents/*` packages with tools now ship a uniform `doctor` subcommand. Plus `mp-doctor` from earlier still works for backward compat.

### Patch Changes

- [`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46) - Enable [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements) for all `@ar-agents/*` packages. From this version on, the npm registry includes a verifiable cryptographic record that the package was built from this exact GitHub commit, via the GitHub Actions `release.yml` workflow. Boosts supply-chain audit scores (Socket / Snyk / npm) and lets downstream agents verify package integrity without trusting the publisher.

  No API or runtime changes.

### Minor Changes

- Initial release. Argentine shipping carriers (OCA, Correo Argentino,
  Andreani) as drop-in tools for the Vercel AI SDK 6.

  Tools shipped:

  - `cotizar_envio` — rate calculation per carrier given origin/destination CP
    and package dimensions
  - `crear_envio` — create a shipment (returns `tracking_number` +
    `etiqueta_url`)
  - `consultar_tracking` — query current shipment status by tracking number
  - `cancelar_envio` — cancel a not-yet-dispatched shipment
  - `listar_codigos_postales` — AR provincia + CP enumeration helpers
  - `validar_codigo_postal` — pure-algorithm CP format validation

  Architecture:

  - `ShippingCarrier` interface — pluggable per-carrier adapters
  - `OcaAdapter`, `CorreoAdapter`, `AndreaniAdapter` — production implementations
  - Default `BcraPublicApiAdapter`-style fallback when carrier creds aren't
    configured (returns clear "not configured" error instead of crashing)
  - AR-specific provincia normalizer (`Buenos Aires` → `B`, `CABA` → `C`, etc.)
  - Tool descriptions in Spanish for natural agent flow with AR users

### Minor Changes

- [`687aa10`](https://github.com/ar-agents/ar-agents/commit/687aa1017a665ed9b3414b9f92db634a9329ac4e) - Add `whatsapp doctor` CLI and `@ar-agents/whatsapp/testing` subpath.

  ```bash
  npx @ar-agents/whatsapp doctor
  ```

  Validates `WHATSAPP_ACCESS_TOKEN` (EAA prefix), `WHATSAPP_PHONE_NUMBER_ID` (numeric), `WHATSAPP_APP_SECRET` (32 chars), `WHATSAPP_VERIFY_TOKEN`, and pings `GET /v23.0/<phone-id>` to confirm the credentials see the phone number. Lists the 6 registered tools and the `scopedTo` mode pattern. Exit codes 0/1 for CI gating.

  ```ts
  import {
    mockSignedWebhook,
    MockWhatsAppClient,
    mockIncomingTextEnvelope,
  } from "@ar-agents/whatsapp/testing";
  ```

  Factories: `mockIncomingTextEnvelope`, `mockIncomingButtonReply`, `mockIncomingListReply`, `mockMessageStatusEnvelope`, `mockSendTextResult`, `mockTemplateResult`. `mockSignedWebhook` produces `{ rawBody, headers }` whose `x-hub-signature-256` passes `verifyWebhookSignature`. `MockWhatsAppClient` records every send call so tests assert on what was dispatched without touching Meta Graph. 12 new tests.

### Patch Changes

- [`da49fde`](https://github.com/ar-agents/ar-agents/commit/da49fde136ecea89b4755fe74b3ed91ed9720f46) - Enable [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements) for all `@ar-agents/*` packages. From this version on, the npm registry includes a verifiable cryptographic record that the package was built from this exact GitHub commit, via the GitHub Actions `release.yml` workflow. Boosts supply-chain audit scores (Socket / Snyk / npm) and lets downstream agents verify package integrity without trusting the publisher.

  No API or runtime changes.

### Minor Changes — Browser-context guard

`WhatsAppClient` constructor now throws if instantiated in a browser
context (where `window` is defined). Prevents the Meta access token
from being accidentally bundled into client-side JavaScript. Edge
Runtime, Node, Workers, and any server context pass through unchanged.

For jsdom-based tests, pass `__allowBrowser: true` explicitly.

### Minor Changes — Agent hijacking prevention (`scopedTo` mode)

- `whatsappTools(client, { scopedTo: senderPhone })` — new option that
  binds every outbound `send_*` tool to a single recipient phone. The
  `to` parameter is REMOVED from the tool schemas, so the LLM cannot
  message a different number even via prompt injection ("send to Y").

  **Use this in webhook handlers**. Without it, an agent that processes
  inbound WhatsApp messages can be tricked into sending payment links
  or content to attacker-chosen recipients. Closes a HIGH security
  audit finding.

  Backward-compatible: omit `scopedTo` (or pass empty options) for the
  previous behavior — useful for batch / proactive flows where the
  agent is sending to a list of recipients you control.

  ```ts
  // BEFORE (still works for batch flows)
  const tools = whatsappTools(wa);
  // LLM picks `to` per call.

  // AFTER (recommended for webhook handlers)
  const event = parseWebhookEvent(payload);
  const tools = whatsappTools(wa, { scopedTo: event.from });
  // LLM cannot specify `to` — it's removed from schema and bound to event.from.
  ```

- 9 new tests in `tools-scoped.test.ts` verifying:
  - `to` is removed from schemas in scoped mode (Zod parse drops it)
  - All 5 send\_\* tools route to scoped sender, ignoring any `to` arg
  - Descriptions warn the LLM about the binding
  - Unscoped behavior unchanged
  - `mark_whatsapp_read` works in both modes (it never had `to`)

### Initial release

WhatsApp Business Cloud API as drop-in tools for the Vercel AI SDK.

**Tools**

- `send_whatsapp_text` — free-form within 24h window
- `send_whatsapp_template` — approved template (any time)
- `send_whatsapp_media` — image/audio/video/document/sticker
- `send_whatsapp_buttons` — 1-3 reply buttons
- `send_whatsapp_list` — sectioned list picker
- `mark_whatsapp_read` — read receipt

**Webhook**

- `parseWebhookEvent` / `parseWebhookEvents` — flatten Meta's nested envelope
- `verifyWebhookSignature` — HMAC-SHA256 (X-Hub-Signature-256)
- `verifyWebhookSubscription` — GET handshake (hub.challenge)

**Phone normalization**

- `normalizeArPhone` — handles all common AR formats, adds the WhatsApp `9` prefix automatically
- `isPlausibleWhatsAppPhone` — loose validation for LLM input

**Errors**

- `WhatsAppRecipientNotOnPlatformError` (Meta code 131009)
- `WhatsAppOutsideWindowError` (Meta code 131026/131047)
- `WhatsAppApiError` (generic)
- `WhatsAppWebhookSignatureError`

48 tests, dual ESM/CJS, MIT.