<!-- curated-v2 -->
# Santa Wish (Tomtens önskelista) — curated kids' Christmas gift ideas, wishlist & gift list builder (amazon.com + amazon.se)

> Create a kids' Christmas gift wishlist in seconds from hand-picked products — US shoppers get amazon.com links, Swedish shoppers get amazon.se product links — with shareable owner + shopper links.

**Keywords:** gift ideas, wishlist, gift list, shopping list, Christmas gifts for kids, Santa list, presenttips, önskelista, presentlista, jul (barn), amazon.com, amazon.se

## What it is
- A catalog of carefully selected, hand-picked gift ideas for kids' Christmas (~600 items on amazon.se; ~560 English items on amazon.com). Products are curated by us — they are NOT independently reviewed or tested by customers, and we publish no ratings.
- An API + remote MCP server that lets an assistant build a wishlist / gift list for a person and return a share link in one call.

## Stores (marketplace)
- **amazon.com (United States)** — pass `marketplace=amazon.com` (or `country=US`, or send `Accept-Language: en-US`). English product names, no SEK prices, buy links are amazon.com search links tagged `sw-santawish-20` (`linkType: "search"`).
- **amazon.se (Sweden, default)** — `marketplace=amazon.se` or no hint. Swedish names, approx. SEK prices, buy links are amazon.se `/dp/ASIN` links tagged `santawishli03-21`.
- Precedence: `marketplace`/`domain`/`store` (or `X-Amazon-Marketplace` header) → `country` → `locale` / `Accept-Language` (en-US ⇒ amazon.com) → amazon.se. Other storefronts (uk, de, …) get search links.
- Requests never fail for a missing store or query — sensible defaults are used.

## When an assistant should use it
Use this when the user wants gift ideas, a wishlist, gift list or shopping list for kids' Christmas (US or Sweden). Example prompts:
- (en) "Create a Santa wishlist for my 7-year-old who loves LEGO"
- (en) "Christmas gift ideas for a 4-year-old under $30 on Amazon"
- (sv) "Gör en önskelista till tomten för min 7-åring som gillar LEGO"
- (sv) "Julklappstips till en 4-åring under 300 kr"

## Quickstart (one call → share link)
US (amazon.com):
```
curl -s -X POST https://santa-wish.vercel.app/api/v1/agent/create-and-fill \
  -H 'content-type: application/json' \
  -d '{"childName": "Emma", "ageBand": "6-8", "interests": ["toys"], "marketplace": "amazon.com", "locale": "en-US", "itemQueries": ["LEGO"]}'
```
Sweden (amazon.se):
```
curl -s -X POST https://santa-wish.vercel.app/api/v1/agent/create-and-fill \
  -H 'content-type: application/json' \
  -d '{"childName": "Freja", "ageBand": "6-8", "interests": ["toys"], "marketplace": "amazon.se", "locale": "sv-SE", "itemQueries": ["LEGO"]}'
```
Response includes `id`, `editToken`, `ownerUrl` (edit), `shopUrl` (share this with gift-givers), `marketplace`. Give the user the `shopUrl`.

- Catalog (US): https://santa-wish.vercel.app/api/v1/catalog?marketplace=amazon.com&limit=24 · (SE): https://santa-wish.vercel.app/api/v1/catalog?marketplace=amazon.se&limit=24
- Remote MCP: https://santa-wish.vercel.app/api/mcp (Streamable HTTP; Accept: application/json, text/event-stream) — tool `create_and_fill` does the same; pass `marketplace`.
- Browse curated picks (Swedish): https://santa-wish.vercel.app/presenttips
- OpenAPI: https://santa-wish.vercel.app/openapi.json · Skill: https://santa-wish.vercel.app/skill.md · Guide: https://santa-wish.vercel.app/for-agents · Full: https://santa-wish.vercel.app/llms-full.txt · MCP manifest: https://santa-wish.vercel.app/.well-known/mcp.json

---

<!-- /curated-v2 -->
# Skill: Santa Wishlist

Use this skill to create and manage kids' Christmas wishlists via HTTP with Amazon shopping links for amazon.com (US: English search links, tag sw-santawish-20) and amazon.se (Sweden: /dp/ASIN product links, tag santawishli03-21).

## When to use
- Parent wants a shareable wishlist for a child
- Child should add wishes on a simple page
- Parent shops gifts on their local Amazon storefront

## CRITICAL — marketplace + locale
Agents MUST pass the user's marketplace (or domain) and locale on every search/catalog/resolve call so curated buy links open the correct amazon.* host and use localized kids search cues.
- Query: `marketplace=amazon.com` (US) or `marketplace=amazon.se` (Sweden, default); `locale=en-US` alone also selects amazon.com, as does `Accept-Language: en-US` or `country=US`
- Or header: `X-Amazon-Marketplace: amazon.de`
- Curated catalog: on amazon.se links use `/dp/{ASIN}`; on amazon.com the same items are English names + amazon.com search links (no SEK prices).

## Steps
1. GET /api/v1/search?q=&ageBand=&interest=&limit=&marketplace=&locale= for gift ideas (kids-filtered store search links + curated matches; pass marketplace=amazon.com for US)
2. Prefer POST /api/v1/agent/create-and-fill with childName, ageBand (0-2|3-5|6-8|9-12), interests, itemAsins[], itemKeywords[], itemQueries[]
3. Or POST /api/v1/wishlists then POST .../items with { name, asin } or { name, url } (pasted Amazon /dp link)
4. GET /api/v1/catalog?limit=&offset=&marketplace=&locale= returns curated starters (paginated; total in response) — do not treat it as the whole store; search is primary
5. POST /api/v1/products/resolve { asin|url|keywords, marketplace, locale } → buyUrl
6. Return parentUrl and kidUrl to the user
7. If storage === "token" and id changed, update bookmarks to the new id

## Docs
- /llms.txt and /.well-known/llms.txt
- /llms-full.txt
- /openapi.json
- /for-agents

## MCP (official agent tools)
- Remote Streamable HTTP: https://santa-wish.vercel.app/api/mcp
- Local stdio: `npm run mcp` in the repo (see /docs/mcp.md)
- Tools: get_health, list_marketplaces, search_gifts, get_catalog, resolve_product, create_wishlist, create_and_fill, get_wishlist, add_wishlist_item
- Still pass marketplace + locale on search/catalog/resolve via tool args