# Insertly — full LLM context

> Branded, print-ready package inserts for your OpoShop orders — thank-you cards, care cards and reorder offers with scannable QR codes.

## 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.tryinsertly.com/openapi.json.
3. MCP: a hosted, public endpoint at https://app.tryinsertly.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
- POST /api/auth/login — Email/password login, returns access + refresh tokens
- GET /api/auth/me — Current authenticated user + store
- POST /api/auth/uninstall — Uninstall webhook — marks the store uninstalled and clears its setup flag
- GET /api/onboarding — First-run setup status; when pending, returns brand autofill suggestions from the store theme
- POST /api/onboarding/complete — Save the brand, seed the three starter templates, and mark setup complete
- GET /api/insert-settings — Get the store's insert brand (creates defaults from the store on first read)
- PUT /api/insert-settings — Update the store's insert brand (upsert)
- POST /api/insert-settings/reset — Clear the first-run flag so the setup wizard runs again
- GET /api/insert-templates/options — The design vocabulary: print sizes (with exact point dimensions), themes, layouts, QR kinds, merge fields
- GET /api/insert-templates — List this store's insert templates
- POST /api/insert-templates — Create an insert template
- GET /api/insert-templates/{id} — Get one insert template
- PUT /api/insert-templates/{id} — Update an insert template
- DELETE /api/insert-templates/{id} — Archive a template (soft delete — already-printed cards stay re-renderable)
- POST /api/insert-templates/{id}/default — Make this the template used when a generate call doesn't name one
- POST /api/insert-templates/{id}/duplicate — Duplicate a template
- POST /api/insert-templates/{id}/restore — Restore an archived template
- GET /api/inserts/orders — List this store's orders, live from OpoShop (newest first)
- GET /api/inserts/orders/{id} — One order's full detail
- GET /api/inserts/orders/{id}/insert.pdf — Print-ready insert PDF for one order
- POST /api/inserts/preview — Render an unsaved design as a PDF, using the store's most recent real order
- POST /api/inserts/generate — Generate inserts for a chosen list of orders (one combined PDF)
- GET /api/inserts/bulk/preview — How many orders a date range covers — check before generating
- POST /api/inserts/bulk — Generate inserts for every order in a date range (one combined PDF)
- GET /api/inserts/codes — Every reorder discount code this app created in the store
- GET /api/analytics/dashboard — Counts of templates and reorder codes for this store
- GET /api/release-notes — Release notes generated from git history

## Auth
POST /api/auth/login → { accessToken }. Send Authorization: Bearer <token>.