@01.software/sdk 0.44.0 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,361 @@
 # @01.software/sdk
 
+## 0.45.0
+
+### Minor Changes
+
+- f5837fb: Add cart discount-code list APIs and public cart discount-code types so storefront clients can manage multiple discount codes on a cart.
+- 4b99c7b: BREAKING (0.x minor): replace the singular Cart line `admission` input and
+  snapshot with the canonical `admissions[]` bundle. Existing callers must wrap
+  their admission tuple in an array and read the corresponding bundled response.
+
+  Also add Cart revision and public attribute support, tenant-scoped client
+  references, and the Cart attribute replacement API to the commerce SDK.
+  Cart responses now expose only the required canonical minor-unit shape;
+  creation returns `{ cart, cartToken, warnings }`, every mutation including
+  `clear` returns `{ cart, warnings }`, and the legacy `applyDiscount` /
+  `removeDiscount` helpers and routes are removed.
+
+  The CLI now accepts canonical admission bundles, validates Cart mutations
+  locally for both dry-run and execution, and uses the plural discount-code
+  replacement command.
+
+- f66c5c7: Add customer refresh-token storage and refresh request support so SDK clients can
+  use rotating customer refresh-token sessions while preserving legacy bearer
+  refresh compatibility.
+- a48daf0: BREAKING (0.x minor): Remove structurally dead ecommerce fields from generated
+  Payload types (#1901): `Order.completedAt`, `Order.cartToken`,
+  `InventoryAdjustment.metadata`, `PaymentSession.metadata`, and the denormalized
+  `DraftOrderItem.productTitle` / `variantTitle` / `sku` fields. These columns had
+  no writer and are dropped from the Console schema by migration.
+- ad068d7: BREAKING (0.x minor): Remove the dead `Discount.discountMode` field from the generated collection types; the `code | automatic` toggle was never implemented and is no longer part of the Discounts schema (#1427).
+- 6a546de: Add event admission availability DTOs and a public `events.getAdmissionAvailability` helper.
+- c54f927: Add hosted customer OAuth helpers under `client.customer.oauth` for PKCE
+  authorization URLs, code exchange, refresh rotation, and hosted logout.
+- 4abb974: BREAKING (0.x minor): browser product detail reads now return the public-safe
+  catalog detail shape, including per-variant `availableForSale` and resolved
+  market price metadata while omitting private inventory fields such as `stock`
+  and `reservedStock`. Product selection helpers accept catalog details without
+  re-exposing private stock fields; trusted server detail reads continue to
+  preserve full variant inventory fields.
+- 45bf6b3: Add a `client.markets` / `server.markets` discovery namespace (`list()` for active markets and `default()` for the primary market) plus the client-safe `MarketDTO` type, so storefronts can discover Shopify-like markets and resolve market context without receiving server-only FX, pricing, or provider fields.
+- 288c6cd: Add SDK client market defaults for market-aware commerce helpers. Browser and
+  server clients now accept `market`, expose `withMarket(market)`, and apply that
+  default to supported product and cart calls unless the individual request
+  provides its own market.
+- f441af9: BREAKING (0.x minor): the generated `Market` type replaces the `roundingIncrement`
+  number field with a `roundingRule { increment, ending }` group (Shopify-style price
+  endings). `roundingRule` stays server-only and is omitted from the public
+  `MarketDTO`; storefront discovery is unaffected.
+- 085c121: Expose editable market target countries and widened market country/currency types.
+- 846ba1f: Allow successful cancel-refund resolution responses to keep `transactionStatus:
+"paid"` when an occurrence-scoped partial refund does not fully refund the
+  captured payment transaction.
+- 91d7502: Add Product read locale options for detail, listing groups, listing pages, React
+  query hooks, and query keys. Storefronts can request `locale: 'ko' | 'en' |
+'all'` with optional fallback disabling, and `locale: 'all'` response types now
+  model localized Product copy objects.
+- a911751: Accept `markets` on `commerce.product.upsert` product fields. The canonical
+  upsert contract previously had no `markets` key, so passing one failed with an
+  `unknown_field` error and every product created through the upsert path landed
+  with an empty market list — silently excluded from market-aware catalogs.
+  Products created without an explicit market now inherit the tenant's primary
+  active market server-side; the update path is unchanged, so clearing markets
+  stays an explicit operator choice.
+- 8fbe821: BREAKING (0.x minor): Remove the dead `EventOccurrence.checkInWindow` (`opensAt`/`closesAt`) field group from the generated collection types; check-in never read or enforced the window, so it is no longer part of the event-occurrences schema (#1892).
+- 3e24e53: Align the return surface with the Shopify Return model (#1857): `ReturnReason`
+  gains Shopify granularity (`size_too_large`, `size_too_small`, `color`, `style`,
+  `not_as_described`, `wrong_item`, `unknown`) and `updateReturn` accepts the new
+  terminal `canceled` status. Both are additive; existing reason codes and
+  statuses are unchanged.
+- d29ca1b: BREAKING (0.x minor): replace the legacy provider-paid Order flow with the
+  canonical Cart -> Checkout -> PaymentSession -> Order resource model.
+  - Rename `commerce.cart.*` to `commerce.carts.*`, rename `get` to `retrieve`,
+    require canonical `admissions[]`, and add replace-style Cart attributes and
+    discount-code mutations.
+  - Add browser/server `commerce.checkouts` and Toss-only
+    `commerce.paymentSessions` APIs with required idempotency keys, strict
+    responses, capability-safe create results, and typed commerce errors.
+    Unavailable providers remain quarantined pending their conformance evidence.
+  - Split all trusted Cart, Checkout, and PaymentSession writes onto
+    resource-owned `/server/` transport paths so every OpenAPI operation has one
+    exact credential policy even when public and server bodies match.
+  - Require durable idempotency for every Cart mutation and optimistic
+    `expectedRevision` preconditions for token-keyed writes; expose the stable
+    `cart_revision_conflict` reason for refetch flows.
+  - Replace the legacy public Order projection with required minor-unit money,
+    immutable line snapshots, and independent financial, fulfillment, return,
+    confirmation, and derived primary-display status axes. Snapshot-only custom
+    Order lines expose `product: null` and `variant: null`.
+  - Remove provider-paid `orders.create`, `orders.confirmPayment`, and ordinary
+    `orders.updateTransaction` SDK/CLI/MCP surfaces.
+  - Remove raw Payload commerce documents from the SDK root and remove the
+    deprecated inline provider-refund cancel response; public reads use canonical
+    DTOs and refund completion stays on its dedicated resolution flow.
+  - Remove the specialized `01 order get` raw-document command. Customer Order
+    reads use the canonical Order projection; explicit server collection tooling
+    remains the trusted operational escape hatch.
+  - Migrate generated ecommerce/events starters, CLI commands, documentation,
+    migration guidance, and direct-HTTP OpenAPI examples to the canonical flow.
+
+- 5344d84: Add optional `market` parameters to product detail, catalog detail, listing
+  groups, and listing page helpers so storefronts can request server-resolved
+  market catalog prices. Market-aware listing page helpers now reject price
+  filters and sorts client-side because market catalog prices are resolved on the
+  server instead of from base product projections.
+
+  Product upsert inputs now accept `variant.marketPrices` fixed market overrides,
+  and discount validation accepts `currency`, `market`, and item context so
+  absolute-money discount rules fail closed outside explicit base-price or market
+  catalog contexts. This includes fixed amount discounts, min order thresholds,
+  max discount caps, and fixed/tiered tier thresholds.
+
+  Catalog product variants now include optional `resolvedPrice` metadata
+  (`amount`, `compareAtPrice`, `currency`, `marketId`, and `source`) with the
+  resolved market catalog price, while catalog variants continue to expose
+  `inventoryPolicy` for availability decisions. Cart create/add-item APIs also
+  accept optional `market`; the Console locks the cart market, stores the resolved
+  market unit price, and carries the market currency through checkout. Provider
+  payment checkout remains constrained to supported KRW flows, and shippable
+  non-KRW carts fail closed until non-KRW shipping/payment support is added.
+
+  BREAKING (0.x minor): Browser `commerce.product.detail()` now returns the
+  public-safe catalog detail shape through the same path as `detailCatalog()`.
+  Full product detail remains available only through the trusted
+  `createServerClient().commerce.product.detail()` read surface because it includes
+  operational inventory fields; storefronts that previously read `totalInventory`,
+  `stock`, or `reservedStock` from browser detail responses must move those
+  overlays to `stockSnapshot()` / `stockCheck()` or a server-credential detail
+  read.
+
+  BREAKING (0.x minor): Root exported `Product`, `ProductVariant`, and `Market`
+  types now point at the sanitized public SDK aliases instead of generated Payload
+  types. Consumers that imported those root types for package-internal fields such
+  as variant `marketPrices` or the raw variant `product` relation should use the
+  server client or package-internal generated types instead.
+
+- 2dd156a: BREAKING (0.x minor): Update membership subscribe params to match the delegated
+  subscribe contract: `customerId` and `customerRef` are required, while
+  `pgPaymentId` is optional for trial starts and other non-immediate-charge flows.
+  The server membership client exposes secret-key lifecycle methods
+  (`subscribe`, `cancel`); the customer-owned `me` view and self-service
+  `cancel` method are exposed on the browser/client customer-JWT surface.
+- b440043: Add public `returnCanceled` commerce notification webhook guard and typed
+  handler support.
+- ff95684: BREAKING (0.x minor): align ecommerce order and transaction status types with
+  Shopify semantics. SDK transaction payload types now expose required
+  Shopify-style `kind` values (`authorization`, `sale`, `capture`, `void`,
+  `refund`) separately from the local payment/refund `type`. Transaction update
+  helpers no longer advertise server-derived `success` writes; legacy-compatible
+  `canceled` and `refunded` inputs remain typed for existing callers but are
+  server-derived in normal public update flows. Use provider-confirmed `paid` or
+  failure-like `failed`/`error` states for public transaction updates.
+- 4bf05e9: Add typed locale and fallbackLocale options for raw collection reads.
+- f4e4fea: Add server-only `tenant.context()` introspection for resolved tenant features, collection availability, field configuration, and optional document counts.
+- 893e5b3: Expose tenant custom-field definition and customData payload types.
+- 402e815: Add `residualCounts` to the `TenantPurgeJob` type. The purge job now records how
+  many rows remain per collection after a sweep, including trashed rows, so a run
+  that fails to drain a collection is visible rather than reported as complete.
+
+  Additive and optional; existing readers are unaffected.
+
+- 28c232b: Add the `senderIdentity` group to the `Tenant` type. Workspace sender identity
+  (display name, reply-to, sending domain and its verification state) now has its
+  own canonical group, separate from the commerce-era `commerceNotifications.sender*`
+  fields.
+
+  Additive and optional. The `commerceNotifications` fields are retained and
+  dual-written during the expand phase of the rename, so existing readers of either
+  group are unaffected; the two carry the same effective sender.
+
+### Patch Changes
+
+- 2eee2ef: Allow `discounts.code` to be nullable for code-less automatic discount
+  candidates, and add server-derived `appliedDiscount` provenance to carts,
+  checkouts, and orders. Cart discount evaluation keeps `discountCodes[]` as
+  customer-entered intent: the first applicable entered code wins, otherwise the
+  server applies the best eligible automatic candidate.
+- f2314fb: Preserve authored canvas image alt text, localize public renderer ARIA labels,
+  and disable focus transitions when the user prefers reduced motion.
+- c66cb8d: Cull offscreen CanvasRenderer nodes by default, memoize node renderers, and set
+  explicit canvas query cache lifetimes to reduce repeated template execution.
+- 22a516f: Add reserved Canvas `shape` node types and first-party SVG renderers for terminator, process, decision, input/output, and subprocess geometry.
+- 9cb1f40: Validate every canvas template `srcset` candidate and SVG URL attribute before materializing React elements.
+- 62bbfc0: Share the Canvas template element and prop security policy with server-side save validation.
+- b5c025c: Harden Cart and Checkout capability storage by replacing raw token fields with
+  digest and encrypted-recovery metadata in the generated Payload types.
+- d8fbb4e: Expose generated cart, checkout, and order market snapshot fields in SDK types and allow public checkout responses to include the resolved market reference.
+- 84c6b9f: Expose `Checkout.customerNote` in generated SDK Payload types so checkout
+  recovery and order placement note snapshots match the public commerce contract.
+- 9a2bedd: Expose generated Checkout payment-slot ownership and PaymentSession provider,
+  finalization, and slot recovery axes in SDK Payload types.
+- 4b3e1a7: Regenerate `payload-types` after moving Customer and Product custom fields into
+  the standard editor tab layout. The `Customer` and `Product` interface property
+  order changes to match the Console field declaration order; the type shape is
+  unchanged, so this is a structural no-op for consumers.
+- 3d9cd63: Convert `custom-field-definitions` ordering from a manual `order` number field to
+  Payload native `orderable: true` (`_order` fractional index). The manual `order`
+  defaulted to `0`, so every new definition tied and display order was
+  non-deterministic. Generated Payload types drop `CustomFieldDefinition.order` and
+  add `_order`; the collection now supports deterministic, drag-based reordering in
+  the Admin Panel and consumers sort by `_order` (#1959).
+- fbaff3a: Clarify that customer `retainUntil` is a retention-review reference rather than
+  authority for hard deletion, and distinguish self-withdrawal from operator
+  privacy redaction in generated customer type documentation.
+- b988e2c: Sync generated Payload types for the internal customer OAuth client registry
+  collection.
+- 509fe4d: Sync generated Payload types for hosted customer OIDC login registry comments.
+- fde4e27: Expose tenant customer password-reset delivery settings in generated SDK
+  Payload types and document platform-managed email delivery for direct local
+  customer auth.
+- 4973fa9: Expose generated customer OAuth client social-provider fields in SDK Payload
+  types for hosted social login support.
+- db73ada: Document that provider-payment order starts should use checkout pre-placement
+  plus provider-verified confirmation. Direct create-order inputs with
+  `pgPaymentId` are deprecated and return `direct_order_payment_deprecated`.
+- da9da4e: Add generated `objectCleanupVerifiedAt` / `lateObjectDetectedAt` fields to the internal `DirectUploadSession` type from the bounded temporary-object cleanup work (#2177). Additive, non-breaking.
+- 8125cbf: Add the `reconciliation_required` direct-upload session status to the durable
+  cleanup lifecycle (#2180). Direct-upload cleanup now deletes the temporary
+  object before releasing storage quota: only a proven-absent object (delete
+  success or not-found) releases the reservation and terminalizes the session in a
+  single PostgreSQL transaction; a transient object-store fault stays retryable and
+  a permanent auth/config fault routes the session to `reconciliation_required`
+  with its reservation left open for repair. The generated `DirectUploadSession`
+  status union gains the new value.
+- ea448c9: Expose the `discount_allocation_method_unsupported` validation reason for
+  discounts that use the not-yet-supported each-line allocation mode, and publish
+  the additive Payload type fields for stacked checkout/order discount snapshots
+  and item-level discount allocation provenance.
+- 6d07364: Sync generated payload type doc comments to match current collection
+  descriptions (markets, event-admission-types, custom-field-definitions,
+  draft-orders). Documentation-only regeneration; no type-structure or API change.
+- 0f8d95e: Add generated SDK payload types for draft order completion fields and custom manual order lines.
+- c256e29: Classify the new `draft-orders` and `draft-order-items` collections as
+  server-only in the collection registry. They back the Console merchant
+  draft/manual order workflow (#1037) and are not part of the browser-public SDK
+  surface.
+- 54d4430: Classify durable commerce idempotency records as SDK-internal and synchronize
+  the generated Checkout ownership fields used by atomic replay recovery.
+- 2dfc0b4: Refine event admission availability rows so admission type occurrence IDs are always the requested occurrence ID.
+- a378d92: Add optional event admission metadata to cart add-item requests so storefronts can keep admission-priced cart lines distinct through checkout.
+- 2b80fc4: Clarify generated `EventAdmissionType` documentation for optional price
+  references and current per-occurrence admission limits. This is a
+  documentation and readiness-copy update only; SDK runtime behavior and public
+  API or contract shapes are unchanged.
+- 6a0d2e9: Classify the new event-domain `event-admission-types` collection as SDK-internal/operator-only, not publishable-key public, and regenerate types to include it. Schema-only follow-up of ADR 0043 paid event admission; no public collection surface changes.
+- 726fa7d: Sync generated Payload types for platform-owned event attendee notification
+  events so SDK consumers can recognize `eventRegistrationConfirmed` and
+  `eventOccurrenceCanceled` email log and notification intent values.
+- 3dc115a: Expose admission identity on public cart items so event storefronts can resolve
+  live cart and checkout line labels.
+- 52f8996: Add the server-derived `parentPublic` field to the `event-occurrences` generated
+  type. It mirrors whether the parent event is exposed to public reads (published,
+  public/unlisted, not trashed) so occurrence reads can filter on it directly
+  instead of resolving parent events per request. The field is server-managed and
+  hidden from publishable-key reads, so storefront responses are unchanged.
+- e62b6a9: Clarify generated event registration quantity documentation so it describes
+  attendee and capacity calculations without implying a ticketing or payment
+  model.
+- 6e9f6c9: Sync generated Return type documentation so SDK consumers can see exchange
+  return fields are reserved until provider-verified exchange settlement exists.
+- 8632657: Align Cart capability retrieve and add-item requests with the hosted Console contract.
+- 326fc60: Fix Checkout SDK calls to use the registered Console routes, including
+  tenant-scoped server checkout detail reads.
+- 0f5049d: Accept numeric fulfillment relationship IDs in server commerce mutation inputs
+  and guard fulfillment request and shaped response types against contract drift.
+- 33ca27c: Add the internal `fulfillment-events` append-only collection to the generated SDK payload types and internal collection registry. Fulfillment events are server-only/internal; no public SDK surface changes.
+- 4b6d7d7: Make commerce request method and path atomic by routing Console registration
+  and SDK operation-only transports through one shared HTTP contract manifest.
+- 2f8db83: Refresh generated SDK Payload types after merging market currency capability gates from dev.
+- 9bf9efd: Expose generated SDK Payload types for market-aware custom payment provider currency support.
+- b2fe177: Let operators edit membership price options directly from the plan edit view.
+  Add a read-only `prices` join field to `membership-plans` (`on: plan`,
+  orderable) so billing-cycle/amount options are listed, created, and reordered
+  inline on the plan instead of a separate collection with a re-picked parent.
+  The join read is operator-only (denies publishable-key and customer reads), so
+  the public storefront plan shape is unchanged; generated Console/SDK types gain
+  the additive `MembershipPlan.prices` join field.
+  Includes the Postgres migration for Payload's join-order column on
+  `membership_plan_prices` so migrated environments can persist the inline
+  drag-sort order.
+- 9f5f31f: Add the generated operator-only membership plan active-price count used by the
+  Console sellability indicator.
+- aa6d933: Update membership SDK payload and endpoint types for membership plan price options. Subscribe calls now reference a `priceId`, and customer membership views expose the selected price cadence snapshot.
+- 6a9be68: Sync generated CustomerMembership type documentation for membership termination
+  fields. Documentation-only regeneration; no type-structure or API change.
+- 3432140: Expose the generated `ApiUsage.notificationEmailCount` field in SDK Payload
+  types so server integrations can read complete monthly billing usage snapshots.
+- a4df48e: Add generated SDK payload types for order edit sessions and staged changes, and classify both collections as server-only.
+- 598418d: Add create-order segment fields to the SDK request type: optional `source`,
+  `test`, and `tags` values for server-auth order creation workflows.
+- 10ecc9c: Move draft orders out of the primary Console nav and create/review them from
+  the orders list via a new launcher (create button + open-draft count). Draft
+  orders drop to a backing-tier surface (still reachable by URL, like
+  returns/fulfillments); the SDK payload types are only regenerated to drop the
+  removed draft-orders admin description comment — no public SDK API change.
+- 1ab3dee: Expose generated order item paid-admission snapshot fields in SDK types so
+  storefront/server integrations can read checkout item, admission type,
+  occurrence, and hold references on promoted order lines.
+- 574023a: Synchronize generated internal payment types with credential lifecycle states,
+  credential generations, bounded eligibility, and provider outcome evidence.
+- 7e60f73: Add the internal payment-kernel terminal-attempt relationship to generated
+  Payload types. This remains an internal-only schema type update and does not
+  add a public runtime surface.
+- 9f8167e: Keep generated Payload schema inputs synchronized for Console-only payment
+  kernel persistence while public `Collection` and `CollectionType` declarations
+  reject all seven internal slugs and shapes.
+- ddac441: Expose generated payment reconciliation, capture-role, payment-session, and
+  provider event inbox fields in SDK Payload types, including order-less
+  unattributed capture evidence, while keeping the inbox collection internal.
+- 03024ab: Classify the new ecommerce `payment-sessions` collection as SDK-internal (not publishable-key or secret-key public) and regenerate types to include it. Server-owned custom payment session state for checkout capture idempotency; raw create/update/delete access is closed, so there is no public collection surface change.
+- 6a4bb5f: Run package verification and prepublish pnpm commands through the workspace-pinned Corepack version so release checks use the supported pnpm 11 toolchain consistently.
+- 26ab105: Synchronize generated Payload types for the SDK-hidden payment interaction
+  recovery collection and private PaymentSession capture evidence.
+- 048d0b2: Preserve pre-12.11 Canvas selection behavior by disabling selection-edge auto-pan in `CanvasRenderer`.
+- a7175e8: Regenerate `payload-types` after reordering Console product editor fields
+  (제목→설명→본문→미디어→가격·품목 흐름 및 조직·판매 탭 성격별 정렬). The
+  `Product` interface property order changes to match the new field declaration
+  order; the type shape (fields and their types) is unchanged, so this is a
+  structural no-op for consumers.
+- 4e072c5: Synchronize the internal, SDK-hidden commerce payment account types with
+  provider-neutral configuration branches; this does not expose a public payment
+  API.
+- d5036a2: Document the publishable-key raw-read row cap on `limit` and `pagination`, and
+  bound the SDK Canvas node/edge type loaders. Browser (publishable-key) raw
+  collection reads must request a bounded `limit` in [1, 100]: `limit: 0`, a
+  `limit` above 100, and `pagination: false` are rejected with 400 rather than
+  returning an entire collection. Server credentials remain uncapped. The Canvas
+  type-definition loaders now request `limit: 100` instead of `limit: 0`.
+- 06dcb23: Expose the generated `Refund` and `RefundLineItem` collection types and classify both as server-only collections.
+- 41d7518: Keep the published SDK runtime unchanged while making the test coverage provider
+  explicit and removing an unused development-only UI scaffold dependency.
+- 2b8fb80: Document the tenant `shopCurrency` revaluation risk in generated SDK types: changing it re-denominates stored catalog and order amounts in place, and the change is now refused while live variants or unsettled orders exist.
+- f0e5806: Expose stateful per-channel marketing consent metadata on customer types while
+  preserving legacy boolean write compatibility.
+- cfe8ef1: Expose generated subscription discount and billing-history discount snapshot
+  fields in SDK payload types for internal billing integrations.
+- 3c4eee7: Expose tenant content locale policy fields in generated SDK Payload types.
+- ec6f604: Update repository metadata for the grouped monorepo package layout. Runtime
+  APIs and package import paths are unchanged.
+- 81aa87c: Harden the shipping calculation transport contract and add destination country
+  and region forwarding to the CLI command.
+- cff1cc1: Synchronize generated internal types and collection classification for durable Toss refund attempts.
+- fe90ba1: Synchronize generated internal types for registered commerce payment accounts,
+  provider customer aliases, and account-bound Toss PaymentSession state.
+- 37acdc2: Expose the generated `Transaction.parentTransaction` relationship type for transaction parent linkage.
+- f90c772: Sync generated Payload types for internal usage billing collections, including
+  usage rate cards, usage invoices, and subscription billing model fields.
+- f6fcd0a: Sync generated Payload types for finalized usage invoices, including nullable
+  charge timestamps and usage invoice line item allowance fields.
+- 79eadf8: Expose the generated `BillingHistory.status` `pending` value for durable usage
+  refund attempt rows.
+- c453fec: Deliver collection webhooks from a transactional Postgres outbox: one internal
+  `webhook-outbox-deliveries` row per event-time recipient persists the exact body
+  and URL in the source mutation transaction, its UUID remains stable across
+  retry/DLQ redrive, and a leased worker signs with the endpoint's nullable live
+  secret. The internal collection is excluded from SDK/MCP access; webhook payload
+  shapes and the public `webhooks` configuration surface are unchanged.
+
 ## 0.44.0
 
 ### Minor Changes
@@ -326,7 +682,7 @@ displayStatus` JSDoc comment from `Order.status`. The Console removed that
   - `ProductUpsertResponse` staleness hint renamed `listingProjectionStale` →
     `productProjectionStale`.
 
-  See `packages/sdk/MIGRATION.md` (“Shopify-shaped product listing fields (#1207)”)
+  See `packages/published/sdk/MIGRATION.md` (“Shopify-shaped product listing fields (#1207)”)
   for the full consumer migration path.
 
 - 31ff635: BREAKING (0.x minor): align product media with Shopify-style gallery ordering. Product listing/detail helpers no longer expose product-level `primaryMediaItemId` or `thumbnail` as canonical inputs; use `images[0]` / `featuredImage` instead.
@@ -516,7 +872,7 @@ displayStatus` JSDoc comment from `Order.status`. The Console removed that
   `ListingGroupingEmptyReason`. Swatch groups derive from the first product option
   by `_order`. `buildProductListingCard` uses persisted min/max when both are present
   and merges compare-at from groups when compare-at keys are absent. See
-  `packages/sdk/MIGRATION.md`.
+  `packages/published/sdk/MIGRATION.md`.
 
 ## 0.35.0
 

package/MIGRATION.md

@@ -1,5 +1,84 @@
 # @01.software/sdk Migration Notes
 
+## SDK 0.45 canonical commerce surface (#2375)
+
+Target release: `0.45.0`. This is a `BREAKING (0.x minor)` release.
+
+The provider-payment flow is now Cart → Checkout → PaymentSession → Order. The
+SDK no longer lets callers create a provider-paid Order or assert generic
+provider truth.
+
+| Before 0.45                                                      | 0.45 replacement                                                                                                                |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `commerce.cart.*`                                                | `commerce.carts.*`                                                                                                              |
+| `cart.get(cartToken)`                                            | `carts.retrieve({ cartToken })`                                                                                                 |
+| `cart.applyDiscount` / `cart.removeDiscount`                     | `carts.updateDiscountCodes` (replace the complete list; `[]` clears)                                                            |
+| singular `admission`                                             | `admissions[]` (non-empty when supplied; maximum 32)                                                                            |
+| `commerce.orders.checkout`                                       | `commerce.checkouts.create`                                                                                                     |
+| `commerce.checkouts.detail`                                      | `commerce.checkouts.retrieve`                                                                                                   |
+| custom PaymentSession create/confirm payloads                    | provider-discriminated `paymentSessions.create`, one canonical retrieve/cancel lifecycle, and typed server adapter confirmation |
+| provider-paid `orders.create`                                    | removed; create a Checkout from a Cart                                                                                          |
+| `orders.confirmPayment`                                          | removed; use the registered PaymentSession adapter action                                                                       |
+| ordinary `orders.updateTransaction`                              | removed; provider state belongs to PaymentSession reconciliation                                                                |
+| root `Order` / `Transaction` / `Cart` / `CartItem` Payload types | removed; use canonical `PublicOrder` / `PublicCart` DTOs or explicit server collection types                                    |
+| inline provider-refund `cancelOrder` response                    | removed; cancellation returns the local `refundPending` receipt and refund completion uses the dedicated resolution flow        |
+| CLI `01 order get` raw Order output                              | removed; use canonical customer Order reads or explicit trusted server collection tooling                                       |
+
+```ts
+const { cart, cartToken } = await client.commerce.carts.create({ market: 'kr' })
+await client.commerce.carts.addItem({
+  cartToken,
+  productId,
+  variantId,
+  quantity: 1,
+  admissions: [{ eventId, occurrenceId, admissionTypeId }],
+  expectedRevision: cart.revision,
+  idempotencyKey: crypto.randomUUID(),
+})
+
+const { checkout, checkoutToken } = await client.commerce.checkouts.create({
+  cartToken,
+  customer: { email: 'buyer@example.com' },
+  idempotencyKey: crypto.randomUUID(),
+})
+const session = await client.commerce.paymentSessions.create({
+  checkoutToken,
+  provider: 'toss',
+  providerOptions: { profile: 'widget_v2' },
+  idempotencyKey: crypto.randomUUID(),
+})
+```
+
+Checkout and PaymentSession results are discriminated unions with required
+cores. Narrow `status`, `providerStatus`,
+`presentationStatus`, or `finalizationStatus` before reading state-specific
+fields. Public money uses integer minor units and uppercase currency.
+`PublicOrderItem.product` and `.variant` are nullable only for snapshot-only
+custom lines created through completed Draft Orders; catalog-backed lines keep
+both references.
+
+Browser cart `mine()` and `merge()` derive customer identity from the customer
+JWT. Server equivalents require `{ customerToken }`; server merge requires both
+`guestCartToken` and `customerToken`. Checkout query is server-only and returns
+cursor pagination without capability tokens.
+
+Server commerce writes no longer share browser transport paths. The server SDK
+uses `/api/carts/server/*`,
+`/api/orders/checkout`, `/api/checkouts/detail`, and `/api/checkouts/query`, and
+`/api/payment-sessions/server/{create,retrieve,cancel,confirm}`. Public paths
+accept only the public capability/customer body and never advertise the server
+credential, even when a server request body happens to be identical.
+
+All Cart mutations except create/retrieve/mine now require an
+`idempotencyKey`. Token-keyed mutations also require `expectedRevision`; on
+`cart_revision_conflict`, retrieve the current Cart and begin a new logical
+mutation with a new key. Merge requires only the key because it resolves and
+locks both current Cart states.
+
+See the
+[complete SDK 0.45 migration matrix](https://github.com/01-office/01-software/blob/dev/docs/packages/sdk-0.45-migration.md)
+in the repository documentation.
+
 ## Shopify-shaped product listing fields (#1207)
 
 Next minor release as a semver minor for the pre-1.0 SDK. This release removes
@@ -17,16 +96,16 @@ be called out in release notes as `BREAKING (0.x minor)`.
 `ProductDetail` and `ProductDetailCatalog` no longer include the `listing`
 group. Replace each field as follows:
 
-| Removed                            | New                                                       |
-| ---------------------------------- | --------------------------------------------------------- |
-| `listing.primaryImage`             | `featuredImage`                                           |
-| `listing.minPrice`                 | `priceRange.minVariantPrice.amount`                       |
-| `listing.maxPrice`                 | `priceRange.maxVariantPrice.amount`                       |
-| `listing.isPriceRange`             | `priceRange.isPriceRange`                                 |
-| `listing.minCompareAtPrice`        | `compareAtPriceRange.minVariantPrice.amount`              |
-| `listing.maxCompareAtPrice`        | `compareAtPriceRange.maxVariantPrice.amount`              |
-| `listing.availableForSale`         | `availableForSale`                                        |
-| `listing.selectionHintVariant`     | `selectedOrFirstAvailableVariant`                         |
+| Removed                        | New                                          |
+| ------------------------------ | -------------------------------------------- |
+| `listing.primaryImage`         | `featuredImage`                              |
+| `listing.minPrice`             | `priceRange.minVariantPrice.amount`          |
+| `listing.maxPrice`             | `priceRange.maxVariantPrice.amount`          |
+| `listing.isPriceRange`         | `priceRange.isPriceRange`                    |
+| `listing.minCompareAtPrice`    | `compareAtPriceRange.minVariantPrice.amount` |
+| `listing.maxCompareAtPrice`    | `compareAtPriceRange.maxVariantPrice.amount` |
+| `listing.availableForSale`     | `availableForSale`                           |
+| `listing.selectionHintVariant` | `selectedOrFirstAvailableVariant`            |
 
 The new range types are exported as `ProductPriceRange` (price range, with
 `isPriceRange`) and `ProductMoneyRange` (compare-at range).