E-commerce
Developer PlatformEcommaps is a unified commerce ecosystem — APIs, SDKs, AI-powered sales agents, logistics integrations, and storefront builder — designed for developers building modern online stores and for merchants who want to manage everything from one platform.
npm install @ecommaps/client @ecommaps/storefront-kit @ecommaps/ai-sales-agentExplore the Docs
Getting Started
Environment setup, authentication, API keys, onboarding, and first Storefront API calls.
Storefront API
Public buyer-facing endpoints — products, cart, orders, auth, pages, blogs, coupons, and store metadata.
MCP
Merchant MCP transport and tool catalog for AI editors, agents, and commerce automation.
SDK & Packages
@ecommaps/client, storefront-kit, ai-sales-agent — typed SDKs with runtime compatibility tables.
AI Development
Sales agent principles, tool contracts, prompt engineering, scope guard, and MCP editor integrations.
Open Source
GitHub repos, npm packages, GenAI Starter template — free tools for storefront engineering.
Logistics
Shipment APIs & carrier integration
Analytics
Event tracking & conversion funnels
Store Builder
Visual page composition & themes
Package Ecosystem
All packages are published on npm under the @ecommaps scope and follow strict semver.
| Package | Layer | Runtime | Description |
|---|---|---|---|
@ecommaps/client (opens in a new tab) | API Transport | Node / Edge / Browser | Typed HTTP client for the Storefront API |
@ecommaps/storefront-kit (opens in a new tab) | Business Logic | Node / Edge | Variant resolution, normalizers, promotion classification |
@ecommaps/ai-sales-agent (opens in a new tab) | AI Runtime | Node + React | Sales agent server factories + React chat UI |
@ecommaps/mcp (opens in a new tab) | Tool Bridge | Node CLI | MCP protocol bridge for editor/AI integrations |
Architecture at a Glance
┌──────────────────────────────────────────────────┐
│ Your Storefront / Agent App │
├──────────────────────────────────────────────────┤
│ @ecommaps/ai-sales-agent │ ← AI runtime + React UI
│ (server tools + ChatPanel component) │
├──────────────────────────────────────────────────┤
│ @ecommaps/storefront-kit │ ← Pure commerce logic
│ (resolveVariant, normalizeProduct, classify) │
├──────────────────────────────────────────────────┤
│ @ecommaps/client │ ← API transport
│ (EcommapsClient → typed HTTP + error handling) │
├──────────────────────────────────────────────────┤
│ Ecommaps Storefront API │ ← FastAPI backend
│ POST /api/v1/storefront/* (x-api-key auth) │
└──────────────────────────────────────────────────┘Quick Example
import { EcommapsClient } from '@ecommaps/client'
const client = new EcommapsClient({
apiUrl: process.env.NEXT_PUBLIC_ECOMMAPS_API_URL!,
apiKey: process.env.ECOMMAPS_API_KEY!,
})
// Fetch all products
const { products } = await client.products.list()
// Create a cart and add items
const cart = await client.cart.create()
await client.cart.addItem(cart.id, {
product_id: products[0].id,
quantity: 1,
})Documentation Standards
📋 Contract-First
Every endpoint doc is aligned with backend route decorators and Pydantic schemas — no stale examples.
🚀 Production-Oriented
Auth models, payload contracts, error codes, and rate limits — documented per endpoint.
🔗 Ecosystem-Aware
SDK pages include compatibility matrices, package boundaries, and runtime requirements.
🤖 AI-Ready
Dedicated AI development track with tool contracts, prompt strategies, and MCP integrations.