# Reponse — AI-Native Commerce OS

> Reponse is a headless commerce platform with native AI support (conversational sales, support inbox, lead qualification) and built-in checkout. It provides a TypeScript SDK, React hooks, a Next.js starter template, and an MCP server for AI agent integration.

## Architecture

Reponse follows a headless, API-first architecture:
- **Backend**: Next.js API routes + Supabase (PostgreSQL + Auth + Realtime)
- **Storefront**: Fully decoupled — use the SDK from any frontend framework
- **AI Layer**: Native chat widget, support inbox, and MCP server for agents
- **Payments**: Stripe (Checkout redirect + Payment Intents)
- **Multi-market**: Per-market currency, tax, shipping, and locale

## SDKs

- [@reponseai/sdk](https://www.npmjs.com/package/@reponseai/sdk): TypeScript SDK for headless commerce. Covers catalog, cart, checkout, orders, collections.
- [@reponseai/react](https://www.npmjs.com/package/@reponseai/react): React hooks (SWR-based) — useProducts, useProduct, useCollections, useCart. Wrap your app with `<ReponseProvider apiKey="...">`.
- [OpenAPI Spec](https://reponse.ai/openapi.yaml): Full REST API specification (OpenAPI 3.0)

## API Reference (v1)

All endpoints require `x-api-key` header. Base URL: `https://<your-store>.reponse.ai`

### Products
- `GET /api/v1/products` — List products (filterable by query, slug, limit, cursor)
- `GET /api/v1/products/:id` — Get product with variants, images, option definitions

### Collections
- `GET /api/v1/collections` — List collections with product counts

### Carts
- `POST /api/v1/carts` — Create a cart (pass workspace_id, currency, optional items)
- `GET /api/v1/carts/:id` — Get cart with line items, subtotal, discounts
- `POST /api/v1/carts/:id/items` — Add items to cart (product_id, variant_id, quantity)
- `PUT /api/v1/carts/:id/items/:lineId` — Update line item quantity
- `DELETE /api/v1/carts/:id/items/:lineId` — Remove line item

### Checkout
- `POST /api/v1/checkout/stripe` — Create a Stripe Checkout session from a cart. Returns `{ url, sessionId }`. Supports automatic discounts, market-aware shipping/tax, subscriptions.

### Orders
- `POST /api/v1/orders` — List orders for a workspace
- `POST /api/v1/orders/:orderId/cancel` — Cancel an order with optional refund
- `POST /api/v1/orders/:orderId/fulfill` — Mark order as fulfilled with tracking info
- `POST /api/v1/orders/:orderId/refund` — Refund an order (full or partial)
- `PATCH /api/v1/orders/:orderId/shipping-address` — Update shipping address
- `POST /api/v1/orders/:orderId/resend-confirmation` — Resend confirmation email
- `POST /api/v1/orders/:orderId/resend-invoice` — Resend invoice PDF

### Discounts
- `GET /api/v1/discounts` — List discount codes
- `POST /api/v1/discounts` — Create a discount code (percentage, fixed_amount, free_shipping, BXGY)
- `POST /api/v1/discounts/validate` — Validate a discount code against a cart

### Inventory
- `GET /api/v1/inventory` — Get inventory levels for products
- `POST /api/v1/inventory` — Update stock quantities

### Gift Cards
- `GET /api/v1/gift-cards` — List gift cards
- `POST /api/v1/gift-cards` — Create a gift card
- `POST /api/v1/gift-cards/redeem` — Redeem a gift card

### Loyalty
- `GET /api/v1/loyalty` — Get loyalty program config and customer balance
- `POST /api/v1/loyalty/redeem` — Redeem loyalty points for a reward
- `GET /api/v1/loyalty/referral` — Get referral stats and code

### Subscriptions
- `PATCH /api/v1/subscriptions/:id` — Update subscription (pause, resume, cancel)

### Tickets (Support)
- `GET /api/v1/tickets` — List support tickets
- `POST /api/v1/tickets` — Create a support ticket
- `GET /api/v1/tickets/:id` — Get ticket details
- `POST /api/v1/tickets/:id/reply` — Reply to a ticket

### Approvals
- `POST /api/v1/approvals/:approvalId/execute` — Execute a pending approval
- `POST /api/v1/approvals/:approvalId/reject` — Reject a pending approval

### Utilities
- `GET /api/v1/utils/geocode` — Geocode an address

## Storefront Starter

A production-ready Next.js 15 storefront: [starters/nextjs-storefront/](https://github.com/supernebuleux/Reponse/tree/main/starters/nextjs-storefront)

### Pages
- `/` — Product grid with add-to-cart, sale badges, out-of-stock indicators
- `/products` — Product catalog
- `/products/[slug]` — Product detail page with image gallery, variant selector, add-to-cart
- `/collections/[id]` — Collection page
- `/cart` — Full cart with qty +/-, remove, order summary
- `/checkout` — Stripe Checkout redirect
- `/order/success` — Order confirmation

### Key Components
- `VariantSelector` (364 lines) — Interactive variant picker with option matching, live price, stock indicator, add-to-cart with loading/success states
- `ImageGallery` — Product image gallery with zoom
- `Header` — Sticky header with cart count badge

### Environment Variables
```
REPONSE_API_KEY=rp_live_...
NEXT_PUBLIC_REPONSE_API_URL=https://your-store.reponse.ai
NEXT_PUBLIC_REPONSE_API_KEY=rp_live_...
NEXT_PUBLIC_WORKSPACE_ID=your-workspace-uuid
```

## Key Patterns

### Cart Flow
1. `ensureCart(currency)` — Get cart ID from localStorage or create new
2. `addItemToCart(cartId, productId, variantId, quantity)` — Add item via API
3. Cart page shows all items with qty controls
4. `/checkout` calls `reponse.cart.createCheckout()` → redirects to Stripe
5. Stripe webhook (`checkout.session.completed`) → creates Order

### Variant Resolution
Products have `option_definitions: [{ name, position, values }]` and variants have `option_values: string[]`. Match by iterating option_definitions and comparing `variant.option_values[idx] === selectedValue`.

### Market-Aware Pricing
Each workspace has `markets` (domestic + international). Markets define:
- `base_currency` (EUR, USD, etc.)
- `prices_include_tax` (TTC vs HT)
- `shipping_flat_rate` / `shipping_free_threshold`
- `countries` (allowed shipping countries)
- `fulfillment_driver` (manual, supplier_api, shopify_proxy)

Always pass `market_id` to the checkout endpoint for correct currency/tax/shipping.

### Discount Engine
The discount combinator (`lib/discount-combinator.ts`) supports:
- Percentage, fixed_amount, free_shipping, BXGY
- Automatic discounts (applied at checkout without code)
- Code-based discounts
- Combination rules (max 1 per kind: product/order/shipping)
- Tier-based eligibility (cold/warm/hot/vip)

## AI & Support

### Chat Widget
Embeddable JavaScript widget (`public/assets/sdk/reponse-widget.js`):
```html
<script src="https://reponse.ai/assets/sdk/reponse-widget.min.js"
  data-workspace-id="your-workspace-uuid"
  data-campaign-id="optional-campaign-uuid"
  data-locale="fr">
</script>
```

### MCP Server
Model Context Protocol server for AI agent integration. Supports tools for product search, order lookup, customer management, cart operations, and support ticket handling.

### Conversational Sales
Each campaign (`/c/[id]`) is an AI-powered landing page with:
- Product context (price, stock, description)
- Incentives (discount codes, free shipping, returns)
- Lead qualification steps
- Email automation

## Data Model (Key Tables)

- `workspaces` — Merchant accounts (name, branding, Stripe keys, custom domain)
- `products` — Product catalog (title, description, price, images, variants, translations)
- `product_variants` — SKU-level data (price, inventory, option_values, subscriptions)
- `collections` — Product groupings
- `carts` / `cart_lines` — Shopping carts with line items
- `orders` / `order_line_items` — Completed orders
- `contacts` — Customer/lead profiles
- `campaigns` — AI conversation configurations
- `discount_codes` — Promo codes and automatic discounts
- `markets` — Multi-market config (currency, tax, shipping, countries)
- `loyalty_programs` / `loyalty_transactions` — Points and rewards
- `tickets` / `ticket_messages` — Support system
- `reviews` — Product reviews and ratings