CommerceBackend v0.2.2 — Public Sandbox Live

CommerceBackend v0.2.2 — Public Sandbox Live

CommerceBackend v0.2.2 takes the agent-commerce loop from a local project to a
live, hardened, public sandbox. The API surface and boundaries are unchanged
from v0.2.1; this release is about deployment, operations, and abuse
resistance.

Highlights

• Public sandbox live at https://api.commercebackend.com (Stripe test mode
  only). Run the full loop — agent registration, listing discovery, offers and
  counter-offers, Stripe-backed checkout, webhook-confirmed orders, and
  fulfillment tracking — with no local setup.
• Containerized deploy. A multi-stage Docker image runs the API on Cloud
  Run, Railway, or any container platform, applying migrations on boot. See
  docs/deploy/.
• Operational hardening. Per-IP rate limiting (with /health, /ready, and
  the Stripe webhook exempt), a configurable CORS allowlist, constant-time
  operator-key comparison, a request body-size limit, and a strict cap on
  unauthenticated agent registration and on search.
• Proxy-correct limits. trustProxy is enabled so per-IP limits key on the
  real client address behind the hosting proxy — verified enforcing on the live
  domain, not just deployed.
• Weekly cadence. Development now runs on a public weekly roadmap
  (docs/weekly-roadmap.md); new capabilities ship every week through review.

Unchanged boundaries

• The hosted sandbox is Stripe test mode only.
• No Stripe Connect seller payouts.
• No refunds, disputes, tax calculation, or human-first marketplace UI.

Verification

pnpm lint, pnpm typecheck, pnpm build, and NODE_ENV=test pnpm test
(49/49) all pass. The full sandbox smoke suite passes against the live domain,
and the registration cap and body limit were confirmed returning 429/413.

CommerceBackend is owned and maintained by Seeed LLC. Seeed LLC is unrelated to
Seeed Studio.

CommerceBackend v0.2.1 — Post-v0.2 Hardening

Summary

CommerceBackend v0.2.1 is a post-v0.2 hardening release for the public agent-native marketplace foundation. It includes release-readiness guardrails and discovery verification before broader live-project promotion.

What changed

• Added a production startup guard that rejects BYPASS_STRIPE_SIGNATURE=true.
• Capped the temporary in-memory listing search scan at 1,000 rows until DB-level search lands in v0.3.
• Fixed query logging so resultCount records the true match total, not only the sliced page size.
• Emitted structured critical JSON logs for CHECKOUT_PERSISTENCE_FAILED reconciliation events.
• Added discovery asset verification for public agent-readable surfaces.

Verification

• PR #34 checks passed before merge: CI, CodeQL, Vercel preview, local build/lint/typecheck/tests.
• PR #33 checks passed before merge: CI, CodeQL, Vercel preview.
• Public discovery files verified live: /llms.txt, /llms-full.txt, and /.well-known/commercebackend.json.

Scope boundary

v0.2.1 does not add refunds, disputes, tax calculation, Stripe Connect payouts, shipping labels, merchant connectors, auctions, or multi-seller carts. Connector imports and semantic search remain v0.3+ roadmap work.

CommerceBackend v0.2.0 — Offers for Agent-Native Commerce

CommerceBackend v0.2.0 — Offers for Agent-Native Commerce

We are pleased to announce the release prep for CommerceBackend v0.2.0, introducing an agent-native marketplace negotiation layer ("Offers"), hardened checkout failure handling, and structured agent-discovery metadata.

---

Summary

CommerceBackend v0.2.0 extends the core API features of v0.1.1 by allowing autonomous AI agents to negotiate prices and quantities transactionally. It also hardens the Stripe checkout intent lifecycle against database connectivity issues and introduces machine-readable metadata discovery standards (llms.txt and .well-known/commercebackend.json) to streamline integrations for software-agent procurement networks.

---

What's New

1. Offers API (Agent-Native Negotiation)

Enables buyers and sellers to negotiate listing terms before moving to Stripe checkout:

• Creation: Buyers submit offers with specific prices, quantities, and expiration dates.
• Negotiation: Sellers can accept, reject, or submit counter-offers with updated price, quantity, and counter-expiration dates.
• Accept Counter: Buyers can accept the counter-offer terms, completing the negotiation loop.
• Cancellation: Buyers can cancel pending or countered offers at any time.
• Audit Trail: Every state transition generates a detailed history audit record in OfferHistory.

2. Checkout Failure Hardening

Prevents reuse of accepted offers and handles failure states robustly:

• Checkout Reuse Protection: Once a checkout intent is created for an accepted offer, the offer transitions to checkout_pending.
• Stripe Session Error Isolation:
  • If Stripe session creation fails before a session exists, the offer is reverted to accepted so the agent can retry.
  • If Stripe session creation succeeds but database persistence fails afterward, the offer is kept checkout_pending and logs a critical reconciliation alert (CRITICAL RECONCILIATION NEEDED) to prevent checkout reuse and duplicate intents.

3. Agent Discovery Metadata

Allows AI agents to locate and understand API capabilities:

• /llms.txt: A text-based configuration outlining project ownership, current capabilities, disambiguation, and roadmap.
• /.well-known/commercebackend.json: A machine-readable JSON structure describing current and planned capabilities, documentation entry points, and owner metadata.
• /docs/agent-discovery.md: Detailed integration guidance for autonomous agents.

---

Offers API Endpoints

• POST /v1/listings/:id/offers — Submit a new offer (Buyer)
• GET /v1/offers — List offers filtered by role and status
• GET /v1/offers/:id — View specific offer details with audit history
• POST /v1/offers/:id/accept — Accept offer terms (Seller)
• POST /v1/offers/:id/reject — Reject offer/counter-offer (Buyer or Seller)
• POST /v1/offers/:id/counter — Submit a counter-offer (Seller)
• POST /v1/offers/:id/accept-counter — Accept seller's counter-offer terms (Buyer)
• POST /v1/offers/:id/cancel — Cancel pending or countered offer (Buyer)

---

Checkout Integration

Buyers can purchase via accepted offers by passing an optional offerId parameter when creating a checkout intent:

POST /v1/checkout-intents
{
  "listingId": "lst_xyz789",
  "quantity": 2,
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "offerId": "off_123"
}

The intent validates that the quantity matches the accepted offer, locks the price to the accepted offer amount, and transitions the offer status to checkout_pending.

---

Database Migration Notes

The database schema updates are defined in packages/db/prisma/migrations/20260524090000_offers/migration.sql:

• Added OfferStatus enum.
• Created the Offer and OfferHistory tables.
• Added offerId column to CheckoutIntent.
• Enforces PostgreSQL CHECK constraints for positive quantities and prices:
  • priceAmount > 0
  • counterPriceAmount IS NULL OR counterPriceAmount > 0
  • counterQuantity IS NULL OR counterQuantity > 0

---

Backward Compatibility

• Legacy Checkout: Creating Checkout Intents without an offerId continues to work at the standard listing price, preserving all v0.1.1 features.
• Stripe Webhook Idempotency: Stripe webhook processes remain untouched, preserving webhook idempotency and inventory checking behaviors.

---

Known Limitations

• Database-level CHECK constraints are not executed during test suite runs because of database mocked environments.
• Offers are not automatically deleted or swept; expiration checks occur transactionally inline during mutations.

---

Verification Results

• Linting (pnpm lint): [PASS]
• Type-Checking (pnpm typecheck): [PASS]
• Unit & Integration Tests (pnpm test): [36/36 PASS]
• Build Compilation (pnpm build): [PASS]

---

Upgrade Notes

1. Run pnpm install to download updated dependencies.
2. Run pnpm db:migrate to apply the Offers table structures, indexes, and custom DB check constraints.
3. Restart the API server.

---

CommerceBackend is owned and maintained by Seeed LLC.
Copyright ©️ 2026 Seeed LLC. Licensed under Apache License 2.0.
Made with ♥️ by Seeed.

v0.1.1

This release contains hardening and reliability improvements for CommerceBackend:

• Database Constraints & Indexing: Added PostgreSQL CHECK constraints for pricing, quantity, and amount fields to prevent corrupt values. Added index optimization on key fields like agent IDs, stripe checkout session IDs, and status columns for performant queries.
• Idempotent Payments: Enabled idempotency key support in Stripe checkout session creation to avoid double charges.
• Timing Attack Mitigation: Added timingSafeCompare utility for API key authorization checks to prevent timing attacks.
• Schema & API Enhancements: Allow free listings with priceAmount of 0. Enhanced catalog search filters with support for offsets and updated default search limits. Added payment_inventory_conflict status to handle checkout issues gracefully when stock is unavailable.