# Ettajer Developer Platform

> AI controls presentation. Ettajer controls commerce.

Ettajer is a COD ecommerce SaaS for Morocco. External AI tools (Claude, Cursor, ChatGPT agents) connect via OAuth or API keys to customize private storefront themes — not to mutate cart, checkout, payments, or the database.

## Auth

- Authorize: https://www.ettajer.com/oauth/authorize?client_id=…&redirect_uri=…&response_type=code&scope=…&state=…&code_challenge=…&code_challenge_method=S256
- Token: POST https://www.ettajer.com/api/oauth/token
- MCP: POST https://www.ettajer.com/api/v1/mcp with Authorization: Bearer <token>
- OpenAPI: https://www.ettajer.com/developers/openapi.json
- Quickstart: https://www.ettajer.com/developers/quickstart
- AI Integration: https://www.ettajer.com/developers/ai-integration
- AI System Prompt: https://www.ettajer.com/developers/ai-system-prompt.txt

## Response contract (v1.1)

- Success: `{ "data": … }`
- Lists: `{ "data": { … }, "pagination": { "nextCursor", "hasMore", "limit" } }`
- Errors: `{ "error": { "code", "message", "details?", "requestId" } }`
- Headers: X-Request-Id, X-RateLimit-*, Idempotency-Key on mutations

## Default theme AI scopes

- store:read: Read store profile and branding
- products:read: Read products and inventory summaries
- collections:read: Read collections
- settings:read: Read non-secret store settings
- themes:read: Read private and active themes
- themes:create: Create private draft themes
- themes:write: Update draft theme layouts, sections, and pages
- themes:preview: Issue short-lived signed preview URLs for private themes
- pages:read: Read custom pages
- pages:write: Create and update theme pages
- media:read: List media assets
- media:write: Upload and register media assets
- navigation:read: Read navigation menus
- navigation:write: Update theme navigation
- themes:publish: Publish a draft theme to the live storefront (opt-in)

## Key endpoints

- GET /api/v1/context
- GET /api/v1/products?limit=&cursor=
- GET /api/v1/themes/schema
- POST /api/v1/themes
- POST /api/v1/themes/:id/batch
- POST /api/v1/themes/:id/preview-token
- POST /api/v1/themes/:id/publish
- MCP: POST https://www.ettajer.com/api/v1/mcp

## Context-first AI workflow

Always: get_context → follow workflow.next (state-aware objects with action+reason) → prefer apply_theme_batch → preview_theme.
Never invent product IDs. Prefer merchant publish over agent publish.

## Compatibility

v1 is the stable Developer API contract. Backward-compatible additions may be introduced. Breaking changes require a new API version.

## Rate limiting

- RATE_LIMIT_BACKEND=memory (default) — local / single-instance only
- RATE_LIMIT_BACKEND=redis — multi-instance production (Upstash REST)
- In-memory rate limiting is NOT multi-instance safe

## Restrictions

- Never request DATABASE_URL, Prisma, Stripe secrets, or NextAuth secrets
- Never trust client-supplied storeId — store comes from the token grant
- Do not inject scripts or arbitrary React into themes
- Reference products by productId; Ettajer remains source of truth for price/inventory
- Preview tokens are purpose-bound (theme_preview only) and short-lived