cope-sdk 0.0.1-reserved.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,157 @@
+# 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.
+
+## [0.1.1] — 2026-10-05
+
+0.2.0 is reserved for the release that reads only the consistent integrator fields (plan 72 S12). A `^0.1.0` range
+takes 0.1.1 on its next install, so everything a 0.1.0 caller can notice is listed under **Behaviour changes**.
+
+### Behaviour changes
+
+Measured against the published 0.1.0 (`cope-sdk@0.1.0` on npm, published from `4b0bd1abad`), not against
+`@copecart/sdk`. Retries, `baseUrl` validation and every request path are unchanged from 0.1.0: 0.1.0 already
+retried only reads and `createPrefilledCheckout`, and already refused a `baseUrl` that is not a bare origin (a query,
+a fragment, a path, or a doubled trailing slash, whose path is `//`).
+
+- **`CartLine.id` is typed `number`.** The API always sent a number, so nothing changes at runtime, but code that
+  stores a line id in a `string`-typed variable stops compiling. `updateLine` and `removeLine` still accept a string.
+- **An asctime `Retry-After` (`Sun Nov  6 08:49:37 1994`) is read as GMT**, where 0.1.0 read it in the host's time
+  zone, so `CopeApiError.retryAfter` changes by the host's UTC offset. A value that is neither delay-seconds nor an
+  HTTP-date (an ISO 8601 string, say) is now `null`, where 0.1.0 passed it to `Date.parse`.
+- **The insecure-page error reads `COPE SDK requires HTTPS...`** (was `CopeCart SDK requires HTTPS...`). Code that
+  matches the message text needs the new wording.
+- **`createPrefilledCheckout` returns `fieldErrors`** when the API attaches any, and sends
+  `collect_buyer_identity_at_checkout` when `collectBuyerIdentityAtCheckout` is set. Both are absent otherwise.
+- **The MCP endpoint (`cope-sdk/mcp`):** `update_line` and `remove_line` take the number `get_cart` returns (0.1.0
+  refused it); `get_cart` returns the lines with `totalsPending` instead of failing when the cart has no buyer
+  location; `start_checkout` returns `buyerNext`; the handshake reads its version from `package.json` (it was hard-coded).
+
+### Changed
+
+- **The class is `Cope`**, after the brand: `import { Cope } from 'cope-sdk'` and `new Cope({ publishableKey })`. Its
+  options type is `CopeOptions`.
+- **The CDN build defines the global `Cope`**, the class itself, so a script tag reads `new Cope({...})`. The global
+  `CopeCart` namespace is unchanged and still carries every export.
+- The insecure-page error reads `COPE SDK requires HTTPS...` (was `CopeCart SDK requires HTTPS...`).
+- `CheckoutPayload.consents` is optional: creating a checkout does not require them. The hosted checkout page requires
+  `buyer_tos` when the buyer starts paying.
+
+### Added
+
+- `UpdateBuyerIdentityPayload` takes `phone` and `locale`, which the API already accepted. A malformed phone is dropped,
+  not refused, and the cart carries `field_errors`.
+- `createPrefilledCheckout` takes `collectBuyerIdentityAtCheckout` (hosted checkout only) and returns `fieldErrors`
+  when the API attaches any.
+- The MCP `start_checkout` result carries `buyerNext`: the buyer accepts the terms, and for a digital product waives
+  the right of withdrawal, on the checkout page; an agent cannot do either. `ApiErrorCode` gains
+  `missing_withdrawal_waiver`, and `CheckoutPayload.consents` and the README say a digital product needs it.
+- `ApiErrorCode` declares every code the endpoints this SDK calls can answer — 21 were missing, among them
+  `invalid_sdk_key`, `price_changed`, `mixed_seller_cart` and `idempotency_conflict` — and the README table lists them.
+
+### Fixed
+
+- **A cart line's `id` is a number.** The API renders it as an integer and `CartLine.id` was typed `string`, so the
+  MCP tools refused the line id they had just returned (`expected string, received number`): `update_line` and
+  `remove_line` could not act on any line. `CartLine.id` is `number`; `updateLine`/`removeLine` take a number (a
+  string of its digits is still accepted), and the MCP tools return it as a number and take a number or a string of
+  its digits.
+- **The MCP `get_cart` failed on a cart with no buyer location** (`missing_tax_location`), so an agent could not show
+  the cart without first asking for the buyer's country and postal code. It now returns the lines with
+  `totalsPending`.
+- **An asctime `Retry-After` was read in the host's time zone.** `CopeApiError.retryAfter` now reads it as GMT, as
+  RFC 9110 defines it, and ignores a value that is neither delay-seconds nor an HTTP-date.
+- The MCP endpoint's handshake reports the package's version (it said `0.1.0`), and tells an agent to set the buyer's
+  country and postal code on `missing_tax_location`.
+
+### Removed
+
+- `missing_code` from `ApiErrorCode`: no endpoint answers it (an empty promo code is `not_found`).
+
+### Deprecated
+
+- **`CopeCart` and `CopeCartOptions`**: aliases of `Cope` and `CopeOptions`, kept so code written against 0.1.0 —
+  `new CopeCart({...})`, and `new CopeCart.CopeCart({...})` on a script tag — runs unchanged. `CopeCart` is the same
+  class, so `instanceof` agrees across both names. `CopeCartExpiredError` is not deprecated: it names an expired
+  cart.
+
+## [0.1.0] — 2026-09-28
+
+### 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`.