# Girlfriend Gifts — agent instructions

Base: use the deployed `NEXT_PUBLIC_SITE_URL` (https://girlfriendgifts.vercel.app).

MCP (Streamable HTTP): https://girlfriendgifts.vercel.app/api/mcp — see docs/mcp.md and /skill.md. Canonical host only (not girlfriend-gifts.vercel.app).

**Require `marketplace` + `locale` on every shopping call.** Example US: `marketplace=amazon.com&locale=en`. Not .se-only.

List storefronts: `GET /api/v1/marketplaces`.

This API is for **building gift lists, recommendation lists, shopping lists, and wishlists** for a girlfriend or wife.

## Two flows

### A) Shopper asks for gift ideas / a shortlist
1. `GET /api/v1/search?q=pearl%20earrings&marketplace=amazon.com&locale=en&occasion=anniversary&budgetBand=300-700&styleTag=jewelry&limit=5`
2. Skim `GET /api/v1/catalog?styleTag=romantic&occasion=valentines&marketplace=amazon.se&locale=sv` — **170+ real amazon.se `/dp` ASINs**
3. Present titles + `buyUrl` (product `/dp/` when ASIN known for that storefront; else search deep-link)
4. Optionally `POST /api/v1/agent/create-and-fill` with marketplace + locale to save a shortlist and return `shopUrl`

### B) She publishes a wishlist
1. `POST /api/v1/wishlists` with `recipientName`, `occasion`, `budgetBand`, `styleTags`, `relationship`, `marketplace`, `locale`
2. Give her `ownerUrl` (edit with `X-Edit-Token` / `?edit=`)
3. She adds wishes via UI or `POST /api/v1/wishlists/{id}/items`
4. Give him `shopUrl` to buy

## Tags
- amazon.se: `?tag=sw-girlfriend-21` when configured via `NEXT_PUBLIC_AMAZON_TAGS_JSON`
- Other storefronts may stay untagged until enrolled — still pass marketplace + locale
- Never invent placeholders or reuse Santa `santawishli03-21`
- Health exposes `trackingTag` for the default storefront

## Stability note
Token storage rotates IDs on mutation. For durable share links set Upstash Redis (`UPSTASH_REDIS_REST_URL` + `UPSTASH_REDIS_REST_TOKEN`).

## Catalog
Curated catalog holds **100+ verified amazon.se product ASINs** across fashion, beauty, tech, experience, personalized, home, jewelry. Prefer `/dp` on amazon.se; use search on other markets.

CORS `*` on `/api/v1/*`. Gift list-building tool with curated buy links — may earn from qualifying purchases.