Gifts

Get one gift by ID, including its full notes. Resolve the ID with gifts_queryGifts first.

List/search gifts, newest first, and resolve gift IDs before a write. Filter by personId (who it's for), occasionId, status, or direction. ALWAYS pass from/to (on the given date) when the question concerns a period, 'what did I give Mom last year' is personId + from/to. Rows are compact summaries (id, title, status, recipients, occasion, price, given date, notes preview); use gifts_getGift for a gift's full notes.

Create or update one gift. Omit record.id to create (title required); include a real record.id from gifts_queryGifts to update, sent fields merge. Example: record { title 'ceramic pour-over', recipientPersonIds ['<mom id>'], occasion 'birthday', status 'idea', priceCents 4200 }. Never invent a price/status the user didn't give.

{
  "record": {
    "title": "Le Creuset dutch oven",
    "recipientPersonIds": [
      "person_mom"
    ],
    "occasion": "Mom's birthday",
    "status": "idea",
    "priceCents": 38000,
    "currency": "USD"
  }
}

Move one gift along the pipeline (idea → planned → purchased → wrapped → given, or skipped). 'given'/'purchased' auto-stamp their date. Resolve the ID with gifts_queryGifts first.

{
  "giftId": "gift_dutch_oven",
  "status": "purchased"
}

Permanently delete one gift. Only for explicit removal requests. Resolve the ID with gifts_queryGifts first.

Get one occasion by ID with its gift progress and budget. Resolve the ID with gifts_listOccasions first.

List occasions (gift lists) with per-occasion gift counts, bought counts, and dates. Use for 'what am I shopping for?' and upcoming occasions; pass from/to on the occasion date for a period. Rows are compact summaries; resolve occasion IDs here before linking gifts.

Create or update one occasion (a gift list). Omit record.id to create (title required); include a real record.id from gifts_listOccasions to update, sent fields merge. Example: record { title 'Christmas 2026', type 'christmas', date '2026-12-25' }.

{
  "record": {
    "title": "Christmas 2026",
    "type": "christmas",
    "date": "2026-12-25",
    "budgetCents": 150000,
    "budgetCurrency": "USD"
  }
}

Permanently delete one occasion. Its gifts are kept and their occasion link is cleared. Only for explicit removal requests. Resolve the ID with gifts_listOccasions first.

Get a person's gift profile: sizes, interests, favorite brands, and the don't-gift/allergies list, to reason about gift ideas. Returns { profile: null } when none is set.

Set a person's gift profile. Arrays (interests, favoriteBrands, avoid) REPLACE the stored set, read with gifts_getRecipientProfile first and resend the full list to add one. Keyed by person; durable across years.

Note: interests, favoriteBrands, and avoid replace the stored lists; read the profile first and send the full list.