9.0.0 • Published 3d ago

@ar-agents/agentic-commerce-bridge

Licence

MIT

Version

9.0.0

Deps

Size

1.2 MB

Vulns

Weekly

Summary Dependency Versions

@ar-agents/agentic-commerce-bridge

The first open-source merchant facilitator for the Agentic Commerce Protocol (ACP) in LATAM. Bridges ChatGPT Instant Checkout, Claude, Gemini, and other agentic-commerce clients to MercadoPago + MercadoLibre, with AR-fiscal compliance (auto-issued AFIP/ARCA Factura A/B/C/E) baked in.

pnpm add @ar-agents/agentic-commerce-bridge zod

What it is

ACP, maintained by OpenAI + Stripe, defines how AI agents talk to merchants on behalf of users: discover products, build a cart, finalize a checkout, settle payment, and confirm fulfillment — all over a small REST surface (5 endpoints + /.well-known/acp.json discovery) with HMAC-signed webhooks.

Today, when ChatGPT or Claude wants to buy something from a LATAM seller, there is no on-ramp: MercadoLibre and MercadoPago don't ship ACP endpoints; the official MELI/MP MCP servers expose only documentation search. This package fills that gap. It's a drop-in facilitator that:

Implements all 5 ACP 2026-04-17 endpoints + discovery
Signs and verifies webhooks per spec (HMAC-SHA256, Merchant-Signature)
Enforces idempotency (Idempotency-Key, replay detection, conflict)
Negotiates ACP versions (rejects unsupported, surfaces supported_versions)
Plugs into MercadoPago checkout (preference creation + payment lookup
- webhook bridge)
Plugs into MercadoLibre catalog (item lookup + UCP-style feed)
Auto-issues AR-fiscal Factura A/B/C/E via AFIP WSFE on order confirmation, embedding the CAE in the order metadata
Runs on Edge Runtime (WebCrypto-only, no Node-only imports)
Pluggable state adapter — InMemoryStateAdapter for dev, VercelKVStateAdapter for production, BYO for anything else

Why now

Standard	Status (2026-05)	LATAM coverage
ACP (OpenAI + Stripe)	Production at ChatGPT Instant Checkout	None
UCP (Google + Shopify + Amazon + Microsoft + Stripe)	NRF 2026 launch	None
AP2 (Google → FIDO Alliance)	v0.2 + FIDO donation Apr 2026	None
Visa Trusted Agent Protocol	Pilots in AR/BR/CL/MX/UY	MercadoPago absent
Mastercard Agent Pay LATAM	Live transactions Mar 2026	MercadoPago absent
x402 (Coinbase + Stripe + Cloudflare)	169M txns	None

When ChatGPT Shopping expands into LATAM (Q3-Q4 2026 per OpenAI partner trajectory), MELI sellers without an ACP bridge will be invisible to agent-driven commerce. Stripe is positioning to ship LATAM ACP in 12-18 months; this package gives you a head start, on open-source terms.

Quickstart

import {
  createFacilitator,
  InMemoryStateAdapter,
  createMercadoPagoPaymentProvider,
  mercadoPagoPaymentHandler,
  createMeliCatalogProvider,
  createFacturacionHook,
} from "@ar-agents/agentic-commerce-bridge";
// You bring your own MELI + MP + AFIP clients (or use ar-agents siblings):
import { mlClient } from "./meli-client";
import { mpClient } from "./mp-client";
import { wsfeClient, arcaPadron } from "./afip-client";

const mp = createMercadoPagoPaymentProvider({
  createPreference: (p) => mpClient.preferences.create({ body: p }),
  lookupPayment:    (id) => mpClient.payments.get({ id }),
});

const facilitator = createFacilitator({
  state: new InMemoryStateAdapter(),
  catalog: createMeliCatalogProvider({
    getItem: (id) => mlClient.items.get(id),
  }),
  paymentProviders: { [mp.handlerId]: mp },
  paymentHandlers: [mercadoPagoPaymentHandler({})],
  webhookSecret: process.env.ACP_WEBHOOK_SECRET,
  hooks: createFacturacionHook({
    seller: {
      cuit: "20123456786",
      punto_venta: 1,
      regime: "monotributo",
      legal_name: "Naza Clemente",
    },
    wsfe: wsfeClient,
    arcaPadronLookup: arcaPadron.lookup,
  }),
});

// Next.js App Router catch-all route:
//   app/api/acp/[...slug]/route.ts
export async function POST(req: Request, ctx: { params: { slug: string[] } }) {
  const acpResponse = await facilitator.dispatch({
    method: "POST",
    path: "/" + ctx.params.slug.join("/"),
    headers: Object.fromEntries(req.headers.entries()),
    rawBody: await req.text(),
  });
  return new Response(JSON.stringify(acpResponse.body), {
    status: acpResponse.status,
    headers: acpResponse.headers,
  });
}

That's it. Your store is now ACP-discoverable from any agent that follows the spec. ChatGPT, Claude, Gemini, Walmart Sparky, Microsoft Copilot, and any Vercel AI SDK agent can transact against you.

What ships

Module	Purpose
`schemas/*`	Zod schemas for every ACP `2026-04-17` shape — CheckoutSession, LineItem, Buyer, Address, FulfillmentOption (4 variants), PaymentData, Order, Cart, Capabilities, Discount, Webhook, Error
`webhook`	`signWebhook` / `verifyWebhook` — HMAC-SHA256, `Merchant-Signature: t=<unix>,v1=<64hex>`, 300s tolerance per spec
`idempotency`	`Idempotency-Key` validation + body-hash + state interface
`state`	`InMemoryStateAdapter` (dev) + `StateAdapter` interface
`vercel-kv` (subpath)	`VercelKVStateAdapter` — Redis-shape adapter (Vercel KV / Upstash / ioredis duck-typed)
`version`	API version negotiation (`API-Version` header)
`handlers/*`	The 5 ACP endpoint handlers + discovery + dispatcher + facilitator factory
`integrations/mp`	`createMercadoPagoPaymentProvider` + `sessionToPreferencePayload` + payment-handler declaration
`integrations/mp-webhook`	`parseMpPaymentIdFromWebhook`, `mpStatusToAcpOrderStatus`, `buildAcpEventFromMpWebhook` — translate MP notifications → ACP webhooks
`integrations/meli`	`createMeliCatalogProvider` + `buildMeliFeed` (UCP-compatible) + `meliItemToFeedProduct`
`integrations/facturacion`	`createFacturacionHook` — auto-emit Factura A/B/C/E via AFIP WSFE on order confirmation
`totals`	`buildLineItemTotals`, `buildOrderTotals`, helpers for fulfillment + tax + discount rollups
`ids`	`generateSessionId`, `generateOrderId`, `generateCartId` (UUID-backed)

ACP endpoints implemented

Method	Path	Status
`POST`	`/checkout_sessions`
`POST`	`/checkout_sessions/{id}`	(update)
`GET`	`/checkout_sessions/{id}`
`POST`	`/checkout_sessions/{id}/complete`
`POST`	`/checkout_sessions/{id}/cancel`
`GET`	`/.well-known/acp.json`	(discovery, RFC 8615)

Per-spec features:

Idempotency-Key mandatory on POSTs, replay detection (Idempotent-Replayed: "true"), in-flight (409 + Retry-After), and body-hash conflict (422 idempotency_conflict).
API-Version header negotiation; rejects unsupported with supported_versions echo.
Cached responses for replay across restarts (when using VercelKVStateAdapter).
Catalog / payment / fulfillment hooks — fully framework-agnostic.

AR-fiscal compliance — the moat

createFacturacionHook is the unique-to-LATAM piece. When an ACP order completes:

The buyer's IVA condition is resolved either explicitly (host-supplied resolveBuyer) or automatically via ARCA padrón lookup (@ar-agents/identity's ws_sr_constancia_inscripcion).

The factura type is selected from a normative matrix:

Seller regime	Buyer condition	Factura
`monotributo`	any	C
`responsable_inscripto`	`responsable_inscripto` / `monotributista`	A
`responsable_inscripto`	`consumidor_final` / other	B
any	`extranjero` (cross-border)	E

WSFE solicitarCAE is invoked with the correct totals + IVA breakdown (21% default for RI, 0% for monotributo Factura C).

The CAE, vencimiento, número, and IVA breakdown are embedded in Order.metadata:

{
  "factura_type": "C",
  "factura_cae": "70123456789012",
  "factura_cae_vencimiento": "20260520",
  "factura_numero": 42,
  "factura_punto_venta": 1,
  "factura_cuit_emisor": "20123456786",
  "factura_importe_total": 1210,
  "factura_importe_iva": 0,
  "factura_importe_neto": 1210
}

If WSFE rejects or padron lookup fails, the order still persists (payment was already authorized) — the error is captured in metadata.factura_error so the seller can re-emit out-of-band.

No competitor in the LATAM ACP/UCP/AP2 space ships this. Stripe Tax doesn't cover Argentine fiscal nuance and won't.

How it compares

	This package	Stripe ACP	Shopify Storefront ACP	MELI/MP MCP (official)
ACP `2026-04-17` schemas			partial	n/a (docs-only)
Hosted-agent on Edge Runtime				n/a
Webhook HMAC + replay protection				n/a
MercadoPago bridge				partial
MercadoLibre catalog				partial
AR-fiscal Factura A/B/C/E
Argentine padrón lookup	(via `@ar-agents/identity`)
MIT, open source		(since Apr 2026)	partial	(docs only)

Hosting

Works in:

Vercel (Edge or Node runtime) — pair with VercelKVStateAdapter for state
Cloudflare Workers — pair with KV / Upstash Redis
Deno Deploy / Bun
Node 20+ (HTTP server, Express, Hono, Fastify, Next.js)

WebCrypto-only (no node:crypto imports). The bundle is < 30KB gzip.

Phase 2 (planned)

AP2 mandate verifier/signer — ES256 SD-JWT VC, mandate chains (~~-separated), constraint evaluation (payment.amount_range, checkout.allowed_merchants, payment.budget), receipts (Checkout + Payment) signed per FIDO Alliance Agentic Auth WG profile.
MELI Q&A + claims tools as ACP extension types — agent-driven pre-sale answer-fetch + post-sale evidence upload.
PIX / Transferencias 3.0 / SPEI bridges — AP2 mandates settling to LATAM bank rails when card networks aren't the right fit.

Tests

pnpm test          # 160 tests across schemas, webhook, idempotency, state,
                   # version, handlers, MP, MELI, facturacion, vercel-kv
pnpm test:coverage # full coverage report
pnpm typecheck     # strict TS, no `any`, exactOptionalPropertyTypes

Specs we follow

ACP — agentic-commerce-protocol/agentic-commerce-protocol (2026-04-17 is the targeted version; older versions are recognized in version negotiation but new sessions emit 2026-04-17)
AP2 — ap2-protocol.org (Phase 2)
AFIP/ARCA WSFE — wsfev1 SOAP spec, factura A/B/C/E

License

MIT. Built by Naza Clemente / Hello Astro for the LATAM agent ecosystem.

@ar-agents/mercadopago — Mercado Pago Agent Toolkit (89 tools)
@ar-agents/identity — CUIT/CUIL + ARCA padrón
@ar-agents/facturacion — AFIP WSFE factura electrónica
@ar-agents/banking — CBU/CVU + BCRA Central de Deudores
@ar-agents/whatsapp — WhatsApp Business Cloud
@ar-agents/shipping — Andreani / OCA / Correo Argentino
@ar-agents/mcp — MCP server bundling all the above