# CookieSun — Full Agent Guide

> CookieSun is an Israeli bakery selling fresh-baked cookies and cakes — including
> gluten-free, vegan and kosher options — with pickup from the bakery in Kiryat Ata, Israel.

This document gives AI agents a complete, single-shot picture of how to read the
CookieSun catalog and place orders. For a short index, see [/llms.txt](https://cookiesun.com/llms.txt).

## About CookieSun
CookieSun is a home bakery based in קרית אתא, Israel. It bakes cookies
and cakes to order for pickup from the bakery. Prices are in ILS (₪). The storefront
is at [cookiesun.com](https://cookiesun.com) and the public API is under [cookiesun.com/api](https://cookiesun.com/api).

## Surfaces an agent can use
- **HTML storefront** — server-rendered pages with Product JSON-LD on each product page.
- **Public catalog API** — JSON, no authentication. See "API" below.
- **MCP server** — [cookiesun.com/mcp](https://cookiesun.com/mcp) (Streamable HTTP), tools `list_products`,
  `get_product`, `search_products`. Read-only tools are public.
- **NLWeb /ask** — POST [cookiesun.com/ask](https://cookiesun.com/ask) with `{ "query": "..." }`.
- **Product feed** — Google Merchant Center feed at [cookiesun.com/feeds/products.xml](https://cookiesun.com/feeds/products.xml).

## API
Base URL: [cookiesun.com/api](https://cookiesun.com/api)
OpenAPI 3.0 spec: [cookiesun.com/api/v3/api-docs](https://cookiesun.com/api/v3/api-docs)
API catalog (RFC 9727): [/.well-known/api-catalog](https://cookiesun.com/.well-known/api-catalog)

### Public (no auth) endpoints
- `GET /catalog/products` — list all active products.
- `GET /catalog/products/{id}` — one product with allergen info and images.
- `GET /catalog/products/{id}/packages` — purchasable offerings (package type, unit count, price, availability).
- `GET /catalog/products/gluten-free` — gluten-free products.
- `GET /catalog/products/vegan` — vegan products.
- `GET /catalog/products/search?q=...` — search.
- `GET /catalog/categories` and `GET /catalog/categories/with-products`.
- `GET /catalog/package-types`.
- `GET /fulfillment-availability` — available pickup slots.

### Authenticated (OAuth) endpoints
Cart and orders act on behalf of a signed-in customer and require a bearer token.
- `GET /cart`, `POST /cart/items`, `PUT /cart/items/{id}`, `DELETE /cart/items/{id}`.
- `POST /orders`, `GET /orders/my`, `GET /orders/{id}`.

### Admin (OAuth + ROLE_ADMIN) endpoints
In-store POS and order management for staff.
- `GET/DELETE /admin/orders/draft`, `POST /admin/orders/draft/items`, `PUT/DELETE /admin/orders/draft/items/{itemId}`, `PUT /admin/orders/draft/preferences`.
- `POST /admin/orders` — create order from admin draft (walk-in `userId` optional; `createdByAdminId` set on order).
- `GET /admin/orders`, `GET /admin/orders/{id}`, `GET /admin/orders/pickup/{date}`, `PUT /admin/orders/{id}/status`.
- Orders include `createdByAdminId`: `null` = customer-initiated; non-null = admin/in-store sale.

## Authentication
CookieSun uses OAuth 2.0 (Authorization Code + PKCE) via a Keycloak issuer.
- Authorization server metadata (RFC 8414): [/.well-known/oauth-authorization-server](https://cookiesun.com/.well-known/oauth-authorization-server)
- Protected-resource metadata (RFC 9728): [/.well-known/oauth-protected-resource](https://cookiesun.com/.well-known/oauth-protected-resource)
- JWKS: [/.well-known/jwks.json](https://cookiesun.com/.well-known/jwks.json)
- Step-by-step guide: [auth.md](https://cookiesun.com/auth.md)
Read actions are public; write actions require `Authorization: Bearer <token>`.
Unauthenticated calls to protected endpoints return `401` with a
`WWW-Authenticate: Bearer resource_metadata="..."` header.

## Errors and rate limits
- Errors are RFC 7807 `application/problem+json` with `type`, `title`, `detail`,
  `request_id`, and (for transient errors) `retry_hint` seconds.
- Successful responses carry `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset`.
- On `429`, honor `Retry-After`.
- Order/checkout creation accepts an `Idempotency-Key` header so retries are safe.

## Ordering / payments for agents
- Commerce discovery (ACP): [/.well-known/acp.json](https://cookiesun.com/.well-known/acp.json)
- Payment methods (MPP): [/.well-known/mpp](https://cookiesun.com/.well-known/mpp)
- Payment settles in ILS via the merchant's card/fiat provider.

## Constraints
- Israel only. Currency ILS.
- Respect product availability from `/catalog/products/{id}/packages`.
- Do not place orders without explicit user confirmation of items, address, and total.

Last verified: 2026-07-07.