cope-sdk 0.0.1-reserved.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to `cope-sdk` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+`cope-sdk` is the new-architecture copy of `@copecart/sdk` 0.3.0 (`svcs/cart-sdk`, whose changelog holds the history
+before the copy). `@copecart/sdk` is unchanged and keeps serving the pages that already load it.
+
+## [Unreleased] — 0.1.0
+
+### Added
+
+- **`cope-sdk/mcp`**: an MCP endpoint a store mounts on its own server so a buyer's AI agent can look up products,
+  build a cart and get a checkout URL (`createCopeMcpHandler`, `generateCartRefKey`; `createCopeMcpNodeHandler` from
+  `cope-sdk/mcp/node`). Server-only; needs `@modelcontextprotocol/server` and `zod` as peers, plus
+  `@modelcontextprotocol/node` for the Node entry. The browser build does not include it.
+- **Ids in request paths are URL-encoded**, so an id such as `../promo_code` cannot aim a request carrying the cart
+  secret at another route.
+- **`persistence: 'none'`** keeps the cart only in memory, for a server that serves many buyers from one process; the
+  default stays `'localStorage'`; a server needs one client per buyer. **`cart: { id, secret }`** acts on a cart whose
+  credentials the caller holds, and never touches stored carts.
+- **`checkout(cartId, payload, { idempotencyKey })`**: a repeated call with the same key and payload returns the
+  checkout already created instead of `cart_not_active` (409 `idempotency_conflict` while the first call is still
+  in flight).
+- **`CopeApiError.retryAfter`**: the server's `Retry-After`, in seconds, or null.
+
+### Changed
+
+- **Published as `cope-sdk`**, not `@copecart/sdk`.
+- **MIT-licensed** (`@copecart/sdk` was `UNLICENSED`), so merchants may use, modify and redistribute it in their
+  own sites.
+- **Default `baseUrl` is `https://app.cope.com`.** Requests go to `https://app.cope.com/api/cart/v1/...`, the checkout
+  block cope-edge serves; the old default `https://app.cope.com/gateway/cart_api` pointed at the old estate's gateway,
+  which the new estate does not have. The hosted checkout origin (the `checkoutBaseUrl` default) stays `app.cope.com`.
+- **`baseUrl` must be an origin.** A value with a path, such as `@copecart/sdk`'s documented
+  `https://app.cope.com/gateway/cart_api`, throws `CopeError('Invalid baseUrl...')` instead of 404ing on every call.
+- **The cart is stored under `cope_sdk_cart`**, not `cope_cart`, so `cope-sdk` never reads or clears a cart
+  `@copecart/sdk` stored on the same page.
+
+### Fixed
+
+- **`cope-sdk/mcp` failed every `create_cart` and `get_cart` against the real cart API** (staging, 2026-09-26). cope-core
+  answers `POST /carts` without `lines` or `buyer_identity`, and reprice and the promo-code routes without
+  `buyer_identity`; the MCP projection read both unconditionally and answered `internal_error`. `createCart` now
+  returns `lines: []` and `buyer_identity: null` (a new cart has neither), `Cart.buyer_identity` is optional (absent
+  where the response does not report it), and the MCP result leaves `buyer` out rather than claiming none.
+- **`Cart.promo_code` never existed.** cope-core sends `applied_promo_code`, an object with the code and the discount;
+  the type now says so, and the MCP result's `promoCode` reads it.
+- **`get_product` quoted plan prices 100 times too low.** The cart API's plan amounts are display strings in major
+  units despite their `_cents` names (`"999.00"`); the MCP projection read them as minor units. It converts them now,
+  so `firstPaymentMinorUnits` matches what the cart charges.
+- **A refused promo code was never recognised.** The cart API answers 422 with the validator's reason (`not_found`,
+  `expired`, `exhausted`, ...), never `invalid_promo_code`; `ApiErrorCode` lists the real reasons, and
+  `apply_promo_code` answers `promo_code_not_accepted` with the API's code as `reason`.
+- The MCP tests' cart API fake had the same four shapes wrong, which is why they passed; it now follows
+  `CartBlueprint` and `PaymentPlanBlueprint`.
+
+- **Promo codes 404ed.** `applyPromoCode` and `removePromoCode` sent `POST`/`DELETE /carts/:id/promo-codes`; the cart
+  API has only ever drawn `/carts/:id/promo_code` (singular, underscore). They now send `promo_code`. The old unit tests
+  asserted the wrong path, so they agreed with the bug; `tests/edge-route-agreement.test.ts` now checks every request
+  the SDK sends against cope-edge's own route table.
+- **The docs promised an unbounded prefilled replay.** A replay returns the stored handoff only within the cart API's
+  24-hour idempotency TTL; after it the same `externalReference` creates a new cart and checkout. README and the
+  `externalReference` doc comment now say so (plan 30 W2-16).
+- **`cart_id_mismatch` was documented as 422.** The cart API answers it with 403.
+- **Two external references could share an Idempotency-Key.** The prefilled key replaced characters outside
+  `[A-Za-z0-9._:-]` with `-` and cut at 120, so `INV/2026/1` and `INV-2026-1` collided and the second checkout got
+  422 `idempotency_body_mismatch` for 24 hours. A safe reference of up to 120 characters keeps its readable key
+  (`prefilled:<reference>:cart`); any other is SHA-256'd whole (`prefilled#<hex>:cart`).
+- **Errors cope-edge answers itself surfaced as `unknown`.** Edge's checkout-block refusals (413 `payload_too_large`,
+  429 `rate_limited`, 502 `upstream_unavailable`, 504 `gateway_timeout`) use `{error, request_id}`, not core's
+  `{errors: [...]}`. `CopeApiError.code` now carries edge's code with a readable `message`, and `requestId` falls back to the
+  body's `request_id` (plan 30 W2-47). An `error` that is prose rather than a code becomes `code: 'unknown'`.
+- **A cart write could be applied twice.** `createCart`, `addLine`, `reprice` and `applyPromoCode` were resent after a
+  5xx, a timeout or a network error, but the cart API deduplicates none of them — so a write edge timed out on (504
+  `gateway_timeout`) but core committed was applied again. Only GETs and `createPrefilledCheckout`, which the server
+  does deduplicate, are resent after an ambiguous failure; a 429 is still retried everywhere it was, because it is
+  refused before processing.
+- **`baseUrl` validation let a query, fragment or credentials through**, and a malformed URL threw a bare `TypeError`.
+  It must now equal its own origin, and anything else throws `CopeError`.
+- **Typecheck failed on a fresh install.** The iframe timer ids were typed `ReturnType<typeof window.setInterval>`,
+  which resolves to Node's `Timeout` once `@types/node` is present; they are typed as the DOM's `number`.