# Girlfriend Gifts — full agent guide

Product: romantic partner gift **lists** — recommendation lists, shopping lists, and shareable wishlists (girlfriend / wife / fiancée / partner).
For humans and AI agents. Not kids. Not Christmas/Santa.

## Architecture
- Next.js 14 App Router, TypeScript, Tailwind
- Storage: compressed token IDs (default) or Upstash Redis (stable 8-char IDs — recommended for share links)
- **Multi-marketplace** Amazon buy links via `marketplace` + `locale` (default storefront amazon.se until overridden)
- Tracking: amazon.se uses `?tag=sw-girlfriend-21` when configured via NEXT_PUBLIC_AMAZON_TAGS_JSON; other storefronts may omit ?tag=. Prefer `buyUrl` / `trackingTag`. Never invent placeholders or reuse santawishli03-21.
- Catalog: **170+ real amazon.se `/dp` ASINs** (fashion, beauty, tech, experience, personalized, home, jewelry)
- Optional PA-API 5 on default storefront; without keys (or other markets) search returns romantic deep-link cards + catalog matches
- Weekly cron stub: GET /api/cron/refresh-catalog (Vercel Monday 06:00 UTC)
- MCP remote: https://girlfriendgifts.vercel.app/api/mcp (Streamable HTTP); local stdio: npm run mcp — tools require marketplace + locale
- May earn from qualifying purchases.

## Marketplace + locale (required)
Pass `marketplace` (id like `us`/`se` or domain like `amazon.com`) and `locale` (e.g. `en`, `sv`) on search, catalog, resolve, and agent flows.
- US example: `marketplace=amazon.com&locale=en`
- SE example: `marketplace=amazon.se&locale=sv`
- Discover: GET /api/v1/marketplaces
- Curated catalog ASINs are verified for amazon.se; non-SE storefronts prefer search deep-links unless a pasted /dp URL ASIN is present
- Tags: TAGS_JSON per storefront. amazon.se → sw-girlfriend-21 when configured. Other markets may stay untagged. Never invent girlfriendgift-21 or reuse santawishli03-21.

## Roles
| Role | Who | URL |
|------|-----|-----|
| wishlistOwner | She builds/publishes the list | /w/{id}?edit=TOKEN → ownerUrl |
| shopper | He (or agent) shops & buys | /w/{id}/shop?edit=TOKEN → shopUrl |

## API (list-building)

### GET /api/v1/health
Returns ok, service (`girlfriend-gifts`), storage, paapi, trackingTag, affiliateTag (compat), defaultMarketplace, marketplaces count, catalogCount.

### GET /api/v1/marketplaces
Lists supported Amazon storefronts (id, domain, defaultLocale, currencyHint).

### GET /api/v1/search?q=&marketplace=&locale=&occasion=&budgetBand=&styleTag=&limit=
Open Amazon search on the chosen storefront. Query rewritten with romantic/partner cues for locale. Results include `buyUrl`. Use to grow a gift recommendation list.

### GET /api/v1/catalog?q=&occasion=&budgetBand=&styleTag=&styleTags=&marketplace=&locale=
**170+ real amazon.se `/dp` ASINs** — curated starters for building shopping lists and wishlists. Prefer these on amazon.se.

### POST /api/v1/wishlists
Body: { recipientName?, occasion?, budgetBand?, styleTags?, relationship?, items?, marketplace?, locale? }
Response: { id, editToken, ownerUrl, shopUrl, wishlist, storage }
Creates an empty gift list / wishlist.

### GET /api/v1/wishlists/:id
### PATCH /api/v1/wishlists/:id  (X-Edit-Token)
### POST /api/v1/wishlists/:id/items  (X-Edit-Token)
### DELETE /api/v1/wishlists/:id/items/:itemId  (X-Edit-Token)

### POST /api/v1/agent/create-and-fill
Preferred one-shot: create a wishlist and fill it with ASINs / keywords / queries.
Body: recipientName, occasion, budgetBand, styleTags, relationship, itemAsins[], itemKeywords[], itemQueries[], marketplace, locale

### POST /api/v1/products/resolve
Body: { asin? , url? , keywords? , occasion? , budgetBand? , styleTag? , marketplace , locale }
→ `buyUrl`

## Enums
occasion: anniversary | birthday | valentines | just-because | apology | wedding | other
budgetBand: under-300 | 300-700 | 700-1500 | 1500-plus
styleTags: romantic | practical | luxury | experience | jewelry | beauty | home | fashion | tech | personalized
relationship: girlfriend | wife | fiancée | partner

## Token caveat
Mutations under token storage may return a new id. Always use the latest id/URLs. Prefer Redis in production.

## CORS
Access-Control-Allow-Origin: * on /api/v1/*

## Discovery
/llms.txt /.well-known/llms.txt /llms-full.txt /openapi.json /.well-known/ai-plugin.json /skill.md /agents.md /for-agents