# Coverly — full LLM context

> Buyer-paid package protection and a claims inbox for OpoShop stores. A 'Protect your order' toggle on the cart adds a real, merchant-priced protection line; the merchant self-insures, keeps the fee, and works a claims inbox when a buyer reports a lost, stolen or damaged parcel. Coverly records the promise and never moves money.

## 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.heycoverly.com/openapi.json.
3. MCP: a hosted, public endpoint at https://app.heycoverly.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 Coverly settings
- PUT /api/settings — Save settings and re-sync the app-owned protection products
- POST /api/settings/setup — Finish the first-run wizard and create the protection products
- POST /api/protection-products — Rebuild the app-owned protection products now
- GET /api/store — Store identity, currency, claim URL and protection health
- GET /api/dashboard — Real protected-order counts, fee revenue and open claims
- GET /api/claims — The claims queue
- GET /api/claims/{id} — One claim with its order and timeline
- PATCH /api/claims/{id} — Approve, deny, resolve, or annotate a claim
- GET /api/orders — Every protected order, with its fee reconciliation
- POST /api/orders/sync — Pull recent orders now instead of waiting for the background sweep
- GET /api/storefront/config — PUBLIC — what the storefront widget should render (or nothing)
- GET /api/storefront/quote — PUBLIC — THE MONEY BOUNDARY: which app-owned variant to add, and how many
- POST /api/storefront/event — PUBLIC — PII-free usage beacon (widget shown / protection added / removed)
- POST /api/public/claims/lookup — PUBLIC — prove you own a protected order and get a short-lived claim token
- POST /api/public/claims — PUBLIC — file a claim using the token from /lookup
- POST /api/public/claims/status — PUBLIC — check a claim you filed (reference + the email on the order)
- POST /api/webhooks/everbee — PUBLIC — OpoShop order webhook receiver (order.created / updated / delivered)
- GET /api/auth/install — Begin the OpoShop OAuth authorize redirect
- POST /api/auth/embedded — Mint a session for the embedded app — ONLY after proven store ownership
- GET /api/auth/callback — OAuth code exchange — the real security boundary
- POST /api/auth/uninstall — Uninstall hook — pauses the store, retains 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
- GET /api/release-notes/latest — The most recent release note only
- GET /api/release-notes/rss.xml — The release notes as an RSS feed

## 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>.