# AURA

> AURA is a premium beauty marketplace serving West Africa (CFA franc, XOF). We curate skincare, fragrance, makeup, and bodycare from established and indie brands. Product pages, brands, and the catalog are public; cart, checkout, and account pages are user-private.

Currency is XOF (Franc CFA). Primary language is French (fr-FR); some surfaces also render English.

## How to read this site

- Every product page emits **schema.org `Product` JSON-LD** with `name`, `brand`, `sku`, `category`, `image`, `description`, `offers` (`price`, `priceCurrency: XOF`, `availability`, `itemCondition`), and `aggregateRating` when reviews exist. Use this as the source of truth.
- The home page emits a **`WebSite`** schema with a `SearchAction` template at `/shop?q={search_term_string}` and an **`Organization`** schema.
- The full catalog is enumerated in [/sitemap.xml](https://aurabeautycosmetic.com/sitemap.xml).
- Crawler rules in [/robots.txt](https://aurabeautycosmetic.com/robots.txt). Account, checkout, and admin paths are disallowed for indexing.

## Public surfaces

- [Home](https://aurabeautycosmetic.com/) — featured products and editorial.
- [Shop](https://aurabeautycosmetic.com/shop) — full catalog with category and brand filters. Search via `?q=`.
- [Brands](https://aurabeautycosmetic.com/brands) — list of stocked brands. Each brand page lives at `/brand/{slug}`.
- [Atelier](https://aurabeautycosmetic.com/atelier) — fragrance discovery / scent profiling.
- [Coffrets](https://aurabeautycosmetic.com/coffret) — curated product bundles.

## Product page contract

URL pattern: `/product/{id}` where `{id}` is a UUID. The page server-renders both Open Graph metadata and `Product` JSON-LD before any client-side hydration, so headless reads do not require JavaScript execution.

Fields you can rely on from the JSON-LD:
- `sku` — stable product id (matches the URL).
- `category` — one of: Skincare, Fragrance, Makeup, Body, Hair.
- `offers.price` — current selling price (sale price if a promotion is active, otherwise list price).
- `offers.availability` — `InStock` or `OutOfStock` reflecting tracked stock at render time.
- `additionalProperty` — when present, includes `Skin types`, `Concerns`, and `Key actives`.

## Private / disallowed

The following paths are user-private and must not be crawled or summarised: `/cart`, `/checkout`, `/profile`, `/orders`, `/saved`, `/notifications`, `/settings`, `/admin`, `/auth`, `/onboarding`, `/pochette`, `/api/`. Honour the directives in `/robots.txt`.

## Programmatic access

### MCP server — `/api/mcp`

A Model Context Protocol endpoint at `https://aurabeautycosmetic.com/api/mcp` (HTTP POST, JSON-RPC 2.0). Connect from Claude Desktop, Cursor, ChatGPT-with-tools, or any MCP client. Read tools work without auth; write tools require an agent token.

Read-only tools (no auth):
- `search_products(query?, category?, brand?, max_price?, on_sale?, limit?)`
- `get_product(id)`
- `list_brands()`
- `list_categories()`
- `recommend_for_skin(skin_type, concerns?, limit?)`

Token-gated tools (Authorization: Bearer aura_pat_…):
- `cart_get` (scope: read)
- `cart_add` / `cart_remove` / `cart_clear` (scope: cart_write)
- `orders_list` (scope: read)

### REST API — `/api/v1`

Same operations exposed as plain REST for non-MCP integrations. All endpoints require `Authorization: Bearer aura_pat_…`. Write requests support an optional `Idempotency-Key` header for safe retries.

- `GET    /api/v1/cart`            — list cart items
- `POST   /api/v1/cart`            — add item `{product_id, quantity?, variant_id?}`
- `PATCH  /api/v1/cart/{itemId}`   — update quantity (`{quantity}`; `0` removes)
- `DELETE /api/v1/cart/{itemId}`   — remove single line
- `DELETE /api/v1/cart`            — clear cart
- `GET    /api/v1/orders`          — list orders
- `GET    /api/v1/orders/{id}`     — order detail with line items

Currency throughout is XOF (integer, no decimals). Errors return JSON `{error: string}` with appropriate HTTP status.

### Tokens

Users provision agent tokens at `/profile/agent-tokens`. Each token carries a scope set (`read`, `cart_write`, `checkout`) and may have a per-token spend cap and expiry. Tokens look like `aura_pat_<32 hex chars>`; the plaintext is shown once at creation. Revoke at any time from the same page.

Checkout (placing orders on behalf of a user) is not yet enabled — the scope exists but there is no endpoint. Contact the team if you have a use case.

## Contact

- Site: https://aurabeautycosmetic.com
- Repository: aurabeauticosmetics-dot/aura