# GiftBow — full LLM context

> Gift wrapping and gift messages for OpoShop stores. A 'This is a gift' toggle beside the buy button adds a real paid gift-wrap line to the cart and lets the shopper type a note; the note rides onto the order, and the merchant works a Gift Queue showing every order that needs wrapping and exactly what to write on the card.

## How it works
OpoShop installs this app via OAuth. The app backend exchanges the code
for an access token, stores it per-store, and calls the OpoShop API on the
seller's behalf. Everything the UI can do is also an HTTP endpoint (below),
described in OpenAPI and exposed as MCP tools.

Layers (kept in lockstep — product → API → MCP):
1. Product: the React admin + Express backend.
2. API: documented at https://app.trygiftbow.com/openapi.json.
3. MCP: a hosted, public endpoint at https://app.trygiftbow.com/mcp — natural-language tools
   over that API, one per operation. Connect any LLM client and authenticate
   with your own store token; you only ever touch your own store's data.

## Endpoints
- GET /health — Liveness probe
- GET /api/settings — Read this store's GiftBow settings
- PUT /api/settings — Save settings and re-sync the gift-wrap product
- POST /api/settings/setup — Finish first-run setup and create the gift-wrap product
- POST /api/wrap-product — Rebuild the gift-wrap product on this store
- GET /api/store — Store identity, currency, and gift-wrap health
- GET /api/dashboard — Gift counts and wrap revenue over a window
- GET /api/catalog/collections — Collections, for the giftable-collections picker
- GET /api/catalog/products — Search products, for the giftable-products picker
- GET /api/gifts — The Gift Queue — orders that bought gift wrapping
- GET /api/gifts/{orderId} — One gift order in full
- PATCH /api/gifts/{orderId} — Mark a gift order wrapped, or put it back in the queue
- POST /api/gifts/sync — Pull the newest orders into the queue right now
- GET /api/storefront/config — PUBLIC — what the gift-wrap widget should render on this page
- GET /api/storefront/message — PUBLIC — restore the note saved against this cart
- POST /api/storefront/message — PUBLIC — save the gift message as the shopper types
- POST /api/storefront/bind — PUBLIC — record that this cart became this order
- POST /api/webhooks/everbee — PUBLIC — OpoShop order webhook receiver
- POST /api/auth/embedded — Mint a session for the OpoShop iframe (ownership-verified)
- GET /api/auth/install — Begin the OpoShop OAuth install (302 to the authorize page)
- GET /api/auth/callback — OAuth callback — exchanges the code and mints the session
- POST /api/auth/uninstall — OpoShop uninstall hook — pauses the store, keeps its data for reinstall
- GET /api/auth/uninstall — Uninstall hook (GET form)
- GET /api/auth/me — The signed-in user and their store
- POST /api/auth/refresh — Exchange a refresh token for a new access token
- GET /api/release-notes — Generated release notes for the What's New page

## Auth
No password login exists. A merchant session is minted only after OpoShop's OAuth proves
store ownership (GET /api/auth/install → /api/auth/callback, or POST /api/auth/embedded
from inside the OpoShop iframe). For /mcp, send your own store token as
Authorization: Bearer <token>.