@01.software/sdk 0.43.0 → 0.45.0

package/README.md

@@ -63,6 +63,10 @@ entry.
 | `@01.software/sdk`                  | browser-safe `createClient`, commerce helpers, collection helpers, types | none                                                                                                       |
 | `@01.software/sdk/client`           | browser-safe `createClient` entry                                        | none                                                                                                       |
 | `@01.software/sdk/server`           | `createServerClient`, server-only collection, commerce, and preview APIs | none; keep `secretKey` code on the server                                                                  |
+| `@01.software/sdk/errors`           | SDK error classes and guards                                             | none                                                                                                       |
+| `@01.software/sdk/analytics`        | browser analytics client and typed event helpers                         | none                                                                                                       |
+| `@01.software/sdk/metadata`         | SEO metadata extraction and generation helpers                           | none                                                                                                       |
+| `@01.software/sdk/webhook`          | webhook handlers, event guards, and webhook types                        | none                                                                                                       |
 | `@01.software/sdk/query`            | React Query hooks, cache helpers, `getQueryClient`                       | `@tanstack/react-query`, `react`, `react-dom`                                                              |
 | `@01.software/sdk/realtime`         | `RealtimeConnection`, `useRealtimeQuery`                                 | `@tanstack/react-query`, `react`, `react-dom`                                                              |
 | `@01.software/sdk/storefront-cache` | product storefront cache resource name helpers                           | none                                                                                                       |
@@ -75,9 +79,13 @@ entry.
 | `@01.software/sdk/ui/video`         | `VideoPlayer`                                                            | `react`, `react-dom`, `@mux/mux-player-react`                                                              |
 | `@01.software/sdk/ui/image`         | `Image`                                                                  | `react`, `react-dom`                                                                                       |
 
+`CanvasRenderer` renders reserved `shape` nodes (`terminator`, `process`,
+`decision`, `io`, `subprocess`) with first-party SVG geometry, without a tenant
+catalog row or QuickJS template.
+
 If a feature is not listed here, it does not need a separate peer install.
 For the full component-to-peer mapping, see
-`packages/sdk/.claude/rules/components-reference.md`.
+`packages/published/sdk/.claude/rules/components-reference.md`.
 
 Migration quick reference:
 
@@ -211,23 +219,20 @@ const server = createServerClient({
 })
 const serverQuery = createServerQueryHooks(server)
 
-// Create order (server only)
-const order = await server.commerce.orders.create({
-  orderNumber: generateOrderNumber(),
-  customerSnapshot: { email: 'user@example.com' },
-  shippingAddress: {
-    recipientName: 'John',
-    phone: '010-1234-5678',
-    postalCode: '12345',
-    address: 'Seoul',
-    detailAddress: 'Apt 101',
-  },
-  items: [
-    { product: productId, variant: variantId, option: optionId, quantity: 1 },
-  ],
-  totalAmount: 10000,
-  pgPaymentId: 'provider-payment-id', // optional (omit for free orders)
-  discountCode: 'WELCOME10', // optional
+// Start the canonical Cart -> Checkout -> PaymentSession flow.
+const { cart, cartToken } = await server.commerce.carts.create({ market: 'kr' })
+await server.commerce.carts.addItem({
+  cartToken,
+  productId,
+  variantId,
+  quantity: 1,
+  expectedRevision: cart.revision,
+  idempotencyKey: crypto.randomUUID(),
+})
+const checkout = await server.commerce.checkouts.create({
+  cartToken,
+  customer: { email: 'user@example.com' },
+  idempotencyKey: crypto.randomUUID(),
 })
 
 // SSR prefetch (server)
@@ -237,13 +242,31 @@ await serverQuery.prefetchQuery({
 })
 ```
 
-Create-order inputs prefer `items`; existing `orderItems` callers remain
-supported and are serialized to the same endpoint field. Order reads expose
-joined line items at `order.items.docs`.
+Provider-paid and manual Order creation are not part of the 0.45 SDK surface.
+An Order is emitted only when the Checkout is placed. Canonical Order reads
+expose line snapshots directly at `order.items`.
 
 Always import `createServerClient` from `@01.software/sdk/server` so generated
 code and bundlers do not blur the Secret Key boundary.
 
+### Tenant context introspection
+
+Trusted server workflows can inspect the resolved tenant capability context
+without calling the Console endpoint directly:
+
+```typescript
+const context = await server.tenant.context()
+
+console.log(context.features)
+console.log(context.collections.active)
+console.log(context.fieldConfigs)
+```
+
+Pass `{ includeCounts: true }` only when document counts and webhook
+configuration are needed. That mode bypasses the endpoint cache and performs
+additional collection reads. Tenant introspection is server-only and is not
+exported from the browser-safe root entry.
+
 Server-rendered preview routes can use `server.preview.detail()` with the
 short-lived preview token issued by Console:
 
@@ -337,34 +360,34 @@ const { product } = result
 //   featuredImage, priceRange, compareAtPriceRange, availableForSale, selectedOrFirstAvailableVariant }
 ```
 
-`detail()` returns `ProductDetailResult`, a discriminated union:
-`{ found: true, product: ProductDetail } | { found: false, reason }`. The
-`reason` value is one of `not_found`, `not_published`, or
-`feature_disabled`, so storefronts can choose between a standard 404, preview
-CTA, or feature gating UI. Permission/auth errors, including 403 tenant
-mismatches, still throw
-typed `SDKError` subclasses and preserve request IDs through the existing
-`lastRequestId` / `onRequestId` path.
-
-Public product visibility has two axes. Lifecycle `status` must still be
-`published` and `publishedAt` must be current or empty. Then
-`storefrontVisibility` decides storefront exposure: `listed` products appear in
-listing helpers and direct detail, `unlisted` products are omitted from listing
-helpers but can be fetched by direct detail slug/id, and `hidden` products return
-`{ found: false, reason: 'not_published' }` from detail and are omitted from
-listings. Legacy products without `storefrontVisibility` are treated as
-`listed`.
-
-The successful product payload exposes inventory rollups without sentinel
-values: `product.totalInventory` is the tracked stock sum across non-unlimited
-variants, `null` when no variants are tracked, and
-`product.hasUnlimitedVariant` signals whether any variant is unlimited.
+Browser `detail()` returns `ProductDetailCatalogResult`, the same public-safe
+catalog detail shape as `detailCatalog()`: `{ found: true, product:
+ProductDetailCatalog } | { found: false, reason }`. The `reason` value is one of
+`not_found`, `not_published`, or `feature_disabled`, so storefronts can choose
+between a standard 404, preview CTA, or feature gating UI. Permission/auth
+errors, including 403 tenant mismatches, still throw typed `SDKError` subclasses
+and preserve request IDs through the existing `lastRequestId` / `onRequestId`
+path.
+
+Public product visibility is driven by product `status` and `publishedAt`.
+Listing helpers return products with `status: 'published'` when `publishedAt`
+is current or empty. Direct detail and checkout admission also allow
+`status: 'unlisted'`, so an unlisted product can be opened by slug/id without
+appearing in PLP/search/curated listing helpers. Draft, archived, scheduled, or
+malformed lifecycle states return `{ found: false, reason: 'not_published' }`
+from detail and are omitted from listings.
+
+The successful browser product payload omits operational inventory fields such as
+`product.totalInventory`, variant `stock`, and variant `reservedStock`. Use
+`stockSnapshot()` / `stockCheck()` for live storefront inventory overlays, or use
+`createServerClient().commerce.product.detail()` from trusted server code when a
+full operational detail read is required.
 
 ### Edge-cached catalog + live stock (storefront migration)
 
 When a PDP or listing UI is served behind the Console Edge CDN, prefer the
-catalog/stock split instead of reading `variant.stock` from a cached
-`detail()` response (inventory in that payload can lag for the catalog TTL).
+catalog/stock split instead of treating cached catalog responses as live
+inventory authorities.
 
 ```typescript
 import { createClient, mergeProductDetailWithStock } from '@01.software/sdk'
@@ -388,8 +411,8 @@ const { product, stockMergeStatus } = mergeProductDetailWithStock(
 Listing UIs use the same pattern: `listingPage()` for PLP/search grids, or
 `listingGroupsCatalog({ productIds })` when curated product IDs are already
 known, then `stockSnapshot()` (or `stock-check` at cart/checkout) for live
-availability. `detail()` and POST detail/listing endpoints are unchanged during
-the migration window; see ADR 0012 addendum in `docs/decisions/0012-sdk-public-commerce-contract.md`.
+availability. Browser `detail()` is now catalog-safe as well; see ADR 0012
+addendum in `docs/decisions/0012-sdk-public-commerce-contract.md`.
 
 ### Product Listing Pages (PLP) — join-safe queries
 
@@ -457,13 +480,6 @@ const { docs } = await server.collections.from('products').find({
           { publishedAt: { equals: null } },
         ],
       },
-      {
-        or: [
-          { storefrontVisibility: { equals: 'listed' } },
-          { storefrontVisibility: { exists: false } },
-          { storefrontVisibility: { equals: null } },
-        ],
-      },
     ],
   },
   limit: 24,
@@ -684,6 +700,57 @@ selection param. Each swatch carries a hint-only slug-compat href such as
 `preferCompleteVariantFromHint: true` on `buildProductListingCard()` only when
 the card should deep-link a complete hint variant.
 
+## Memberships
+
+Membership self-service is split by credential boundary:
+
+- Browser/customer JWT clients can read the signed-in customer's current or
+  latest membership and request cancellation for active, trialing, or past-due
+  memberships.
+- Server clients with a Secret Key can subscribe a customer after the storefront
+  has completed the delegated first charge.
+
+```typescript
+import { createClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
+
+const client = createClient({ publishableKey: 'pk_live_...' })
+
+const membership = await client.memberships.me()
+if (
+  membership &&
+  ['active', 'trialing', 'past_due'].includes(membership.status)
+) {
+  await client.memberships.cancel({ id: membership.id })
+}
+
+const server = createServerClient({
+  publishableKey: 'pk_live_...',
+  secretKey: process.env.SOFTWARE_SECRET_KEY!,
+})
+
+await server.memberships.subscribe({
+  planId: 'plan_123',
+  customerId: 'customer_123',
+  customerRef: 'cus_provider_123',
+  pgPaymentId: 'pay_123',
+  amount: 9900,
+  currency: 'KRW',
+  subscribeIntentKey: 'checkout-session-123',
+  card: { last4: '4242', brand: 'visa' },
+})
+```
+
+`subscribeIntentKey` is sent as `X-Idempotency-Key`; it is not part of the JSON
+body. Replays must use the same plan, customer reference, amount, currency, and
+paid-start provider payment id snapshot as the original incomplete membership.
+Trial subscriptions may omit `pgPaymentId` because no first-period charge has
+been captured yet; paid starts must include the provider payment id that funded
+the first period.
+`memberships.me()` and browser `memberships.cancel()` require the customer JWT
+configured on the client. Refund webhook `refundedAmount` values are cumulative
+charge totals, not per-event deltas.
+
 ## Storefront performance defaults
 
 - **PLP:** prefer `commerce.product.listingPage()` or `useProductListingPage()` (GET `/api/products/listing-groups/query/catalog`, CDN-cacheable, card-ready). Use `listingGroupsCatalog({ productIds })` only when IDs are already known. Treat the full listing-groups response shape as a server-auth escape hatch because it can include operational stock fields. Avoid fetching a product list and then calling `detail()` per card.
@@ -775,7 +842,7 @@ Dotted-path filters (`where: { 'product.slug': { equals } }`) are Payload-native
 
 Checklist when `find()` returns `docs: []` unexpectedly, in order of likelihood:
 
-1. **Access control filtered the document.** Many collections enforce public read filters. Products require `status: 'published'`, a current or unset `publishedAt`, and listable storefront visibility (`listed`, legacy missing, or `null`) for publishable-key raw listing reads. Draft, future, `unlisted`, `hidden`, or malformed products silently disappear from raw listing results even when their slug or ID matches. Use the shaped product detail helper for direct-link `unlisted` products. Correlate with backend logs via `client.lastRequestId` (or catch `SDKError.requestId`).
+1. **Access control filtered the document.** Many collections enforce public read filters. Product listing reads require `status: 'published'` plus a current or unset `publishedAt`. Draft, future, `unlisted`, archived, or malformed products silently disappear from raw listing results even when their slug or ID matches. Use `commerce.product.detail({ slug | id })` for `unlisted` products. Correlate with backend logs via `client.lastRequestId` (or catch `SDKError.requestId`).
 2. **Build-time publishable key / API URL differs from runtime.** SSG `generateStaticParams` / `generateMetadata` / the page render must all see the same tenant context. A wrong or missing key at build time produces a baked-in empty response.
 3. **Next.js SSG fetch cache served a stale empty response.** Use `cache: 'no-store'` or `export const revalidate = 0` on server components that should reflect live data.
 4. **`where: { slug: 'x' }` string shorthand.** Always use `{ slug: { equals: 'x' } }` — bare strings silently match nothing.
@@ -875,6 +942,24 @@ const product = await server.collections.from('products').findById(id, {
 const product = await client.collections.from('products').findById('id')
 ```
 
+Localized raw collection reads can request a supported Payload locale. The SDK
+currently exposes `en` and `ko`; it does not expose Payload's `locale=all`
+shape. `fallbackLocale` serializes to Payload's REST `fallback-locale` query
+key, and `fallbackLocale: false` serializes as `fallback-locale=none`.
+
+```typescript
+const { docs } = await client.collections.from('articles').find({
+  locale: 'ko',
+  fallbackLocale: 'en',
+  limit: 10,
+})
+
+const article = await server.collections.from('articles').findById(id, {
+  locale: 'ko',
+  fallbackLocale: false,
+})
+```
+
 Raw collection mutations are an escape hatch. For ecommerce product catalog
 writes, prefer `server.commerce.product.upsert()` so options, option-values,
 and variants are written through the domain transaction.
@@ -1052,13 +1137,58 @@ await server.collections.from('articles').update('article_id', {
 
 ### Customer Auth
 
-Customer auth methods currently cover local email/password flows: register,
-login, refresh, password reset, profile read/update, and password change.
-`CustomerProfile.authProvider` may contain `google`, `apple`, `kakao`, or
-`naver` for accounts created through platform/provider integrations, but the
-SDK does not expose social-login initiation or callback helpers yet.
+New storefronts should use hosted customer OAuth through
+`client.customer.oauth.*`. The SDK generates PKCE authorization URLs, parses the
+callback, exchanges codes, rotates refresh tokens, and calls hosted logout, but
+it does not store tokens for you. Store OAuth access, refresh, and transient
+state in trusted route handlers, preferably HttpOnly cookies or a server-side
+session store. Do not put OAuth tokens in browser-readable storage.
+
+```typescript
+const client = createClient({
+  publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY,
+  customer: {
+    persist: false,
+    oauth: {
+      issuer: process.env.NEXT_PUBLIC_SOFTWARE_CUSTOMER_AUTH_ISSUER!,
+      clientId: process.env.NEXT_PUBLIC_SOFTWARE_CUSTOMER_CLIENT_ID!,
+    },
+  },
+})
 
-Available on Client via `client.customer.auth.*`.
+const customerOAuth = client.customer.oauth
+if (!customerOAuth) throw new Error('Customer OAuth is not configured')
+
+const authorization = await customerOAuth.createAuthorizationUrl({
+  redirectUri: `${origin}/api/auth/customer/callback`,
+  returnTo: '/account',
+})
+
+const callback = customerOAuth.parseCallback(callbackUrl, {
+  expectedState: authorization.state,
+})
+
+const tokens = await customerOAuth.exchangeCode({
+  code: callback.code,
+  codeVerifier: authorization.codeVerifier,
+  redirectUri: `${origin}/api/auth/customer/callback`,
+})
+
+await customerOAuth.refresh({ refreshToken: tokens.refreshToken })
+await customerOAuth.logout({ refreshToken: tokens.refreshToken })
+```
+
+`exchangeCode()` may return an `idToken` when the `openid` scope is granted. In
+this SDK release, treat `idToken` as opaque unless your server verifies issuer,
+audience, expiry, nonce, and hosted JWKS signature itself. Use `me()` after
+establishing an access token for trusted customer profile display.
+
+#### Legacy direct local auth
+
+`client.customer.auth.*` remains available for existing local email/password
+flows: register, login, refresh, password reset, profile read/update, and
+password change. Keep this path as explicit legacy compatibility for existing
+integrations; do not overload `login()` to sometimes redirect into hosted auth.
 
 ```typescript
 const client = createClient({
@@ -1086,7 +1216,7 @@ client.customer.auth.logout()
 const orders = await client.commerce.orders.listMine({
   page: 1,
   limit: 10,
-  displayFinancialStatus: 'paid',
+  financialStatus: 'paid',
 })
 
 // Password
@@ -1095,15 +1225,191 @@ await client.customer.auth.resetPassword(token, newPassword)
 await client.customer.auth.changePassword(currentPassword, newPassword)
 ```
 
-### Commerce Orders (ServerClient-only writes)
+`forgotPassword()` keeps the same SDK signature in both delivery modes. A
+tenant administrator chooses either backward-compatible signed webhook
+delivery or platform-managed email in the Console customer-authentication
+settings. Platform email requires the storefront reset URL to be configured;
+the platform appends the `token` query parameter and sends through the verified
+tenant sender or the platform fallback. Do not add reset tokens or dynamic
+redirect URLs to the SDK call.
+
+### Market discovery
+
+Discover a tenant's active buyer markets and resolve the default market. These
+reads are safe for a publishable key — server-only FX/pricing fields are never
+returned.
+
+```ts
+const markets = await client.markets.list() // MarketDTO[] (active markets)
+const primary = await client.markets.default() // MarketDTO | null (active primary)
+
+// Pass the resolved handle to market-aware commerce calls:
+const cart = await client.commerce.carts.create({ market: primary?.handle })
+```
+
+`MarketDTO` is `{ id, handle, name, countryCode, targetCountries, currency,
+isPrimary, isActive }` — `countryCode`/`targetCountries` are ISO 3166-1 alpha-2,
+`currency` is ISO 4217.
+
+> `client.markets.default()` resolves the tenant's primary market from server
+> data. It is distinct from the client's _configured_ default market handle
+> (`CommerceClient.getDefaultMarket()`), which is the handle you passed to
+> `createClient({ market })`.
+
+### Commerce Market Context
+
+Pass `market` when constructing a client to default market-aware product and cart
+helpers to that market. Per-call `market` still wins when supplied.
+
+```typescript
+const client = createClient({
+  publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY,
+  market: 'kr',
+})
+
+await client.commerce.product.detail({ slug: 'shirt' }) // uses kr
+await client.commerce.carts.create() // creates a kr cart
+await client.commerce.product.detail({ slug: 'shirt', market: 'us' }) // override
+
+const usClient = client.withMarket('us')
+const { cart } = await usClient.commerce.carts.retrieve({ cartToken })
+await usClient.commerce.carts.addItem({
+  cartToken,
+  productId,
+  variantId,
+  quantity,
+  expectedRevision: cart.revision,
+  idempotencyKey: crypto.randomUUID(),
+})
+```
 
-Available on ServerClient via `server.commerce.orders.*`. `checkout` and `listMine` are also on Client and return sanitized customer-facing order DTOs. Customer order DTOs expose the independent status axes (`displayFinancialStatus`, `displayFulfillmentStatus`, `returnStatus`, `primaryDisplayStatus`, `returnDisplayStatus`); `status` and `displayStatus` are read-only compatibility aliases for older clients. Use `server.collections.from('orders')` for raw operational order documents.
+`createServerClient({ market })` and `server.withMarket(market)` provide the
+same request-scoped default for trusted server code.
+
+### Commerce Checkout and PaymentSession
+
+The canonical payment lifecycle is Cart → Checkout → PaymentSession → Order.
+Checkout and PaymentSession results are required discriminated unions: narrow
+their state fields before reading state-specific data such as `nextAction` or
+`order`. Browser calls use publishable-key capability tokens and the matching
+customer JWT when a resource is customer-bound. Server calls use the secret
+credential and never expose provider secrets in returned DTOs.
+
+Browser and server commerce writes use separate transports even when their JSON
+shapes match. `createServerClient()` routes every Cart operation, Checkout
+create/retrieve/query, and PaymentSession create/retrieve/cancel/confirm through
+the resource-owned `/server/*` namespace. Public paths retain only their exact
+capability/customer bodies and never advertise the server credential.
+
+Generate one idempotency key per logical mutation, persist it with the pending
+operation, and reuse it after timeouts or lost responses. Creating a fresh key
+for each retry starts a different operation. Do not derive ordinary keys from a
+Cart, Checkout, PaymentSession, Order, or provider id: reuse of that resource for
+a later operation would collide. Use `createCommerceIdempotencyKey()` and retain
+the generated value with the pending operation.
+
+Cart add/update/remove/clear/discount/attribute mutations additionally require
+the last observed `cart.revision` as `expectedRevision`. A
+`cart_revision_conflict` means refetch the Cart and start a new logical mutation
+with a new idempotency key. Cart merge requires the key but not a single revision
+because it atomically resolves two current Cart states.
+Treat a replayed Cart result as an operation receipt: never replace a newer
+cached Cart with a lower `revision`; retrieve when response ordering is unclear.
+
+```typescript
+import {
+  createCommerceIdempotencyKey,
+  isCommerceSDKError,
+} from '@01.software/sdk'
+
+const checkoutIdempotencyKey = createCommerceIdempotencyKey()
+const { checkout, checkoutToken } = await client.commerce.checkouts.create({
+  cartToken,
+  customer: { email: 'buyer@example.com', name: 'Buyer' },
+  shippingAddress,
+  idempotencyKey: checkoutIdempotencyKey,
+})
+
+const paymentIdempotencyKey = createCommerceIdempotencyKey()
+const paymentSession = await client.commerce.paymentSessions.create({
+  checkoutToken,
+  provider: 'toss',
+  providerOptions: { profile: 'widget_v2' },
+  idempotencyKey: paymentIdempotencyKey,
+})
+
+if (
+  paymentSession.presentationStatus === 'actionable' &&
+  paymentSession.nextAction.type === 'toss_widget'
+) {
+  // Initialize the Toss widget with the returned public client/variant fields.
+}
+
+// Browser recovery requires the parent capability.
+await client.commerce.paymentSessions.retrieve({
+  paymentSessionId: paymentSession.id,
+  checkoutToken,
+})
+
+// Toss confirmation is a typed server-only adapter action. There is no generic
+// `confirmVerified` or provider-paid Order creation escape hatch.
+const confirmationIdempotencyKey = createCommerceIdempotencyKey()
+let confirmed
+try {
+  confirmed = await server.commerce.paymentSessions.confirm({
+    paymentSessionId: paymentSession.id,
+    idempotencyKey: confirmationIdempotencyKey,
+    action: {
+      type: 'toss_authorization',
+      paymentKey,
+      providerOrderId,
+    },
+  })
+} catch (error) {
+  if (isCommerceSDKError(error) && error.retryable) {
+    // Retry the same logical operation with confirmationIdempotencyKey.
+  }
+  throw error
+}
+
+if (confirmed.finalizationStatus === 'committed') {
+  console.log(confirmed.order.orderNumber)
+}
+
+const checkoutPage = await server.commerce.checkouts.query({
+  status: ['open'],
+  limit: 20,
+})
+void checkoutPage.nextCursor
+```
+
+`checkoutToken` is returned only alongside Checkout creation; ordinary Checkout
+DTOs never echo the bearer capability. Browser `checkouts.retrieve` and
+PaymentSession retrieve/cancel calls accept that token. Server
+`checkouts.retrieve({ checkoutId })` uses tenant-scoped authority, and
+`checkouts.query` returns lightweight rows without capabilities.
+
+Canonical commerce error envelopes become `CommerceSDKError`. Branch on its
+stable `reason`, inspect `retryable`, and log `requestId`; a newer server reason
+is preserved as `reason: 'unknown_commerce_error'` plus `rawReason`.
+
+### Commerce Orders (post-placement operations)
+
+Provider-paid `orders.create`, `orders.confirmPayment`, and ordinary
+`orders.updateTransaction` were removed in SDK 0.45. No general manual Order API
+is exposed. After a PaymentSession commits an Order, trusted server code can use
+the remaining fulfillment, cancellation, and return operations. Customer order
+reads remain available through `client.commerce.orders.listMine()`.
+
+The SDK root no longer exports raw generated `Order`, `Transaction`, `Cart`, or
+`CartItem` Payload documents. Use the canonical `PublicOrder` / `PublicCart`
+DTOs for storefront code and explicit server collection types only inside
+trusted operational code. Order cancellation no longer returns the deprecated
+inline provider-refund branch: a paid cancellation returns `refundPending`, and
+the dedicated refund-resolution flow reports provider completion.
 
 ```typescript
-// Orders
-await server.commerce.orders.create(params)
 await server.commerce.orders.update({ orderNumber, status: 'confirmed' })
-await server.commerce.orders.checkout({ cartId, pgPaymentId?, orderNumber, customerSnapshot, discountCode? })
 
 // Single-order lookup (getOrder endpoint removed — use collection find)
 const { docs: [order] } = await server.collections.from('orders').find({
@@ -1118,23 +1424,6 @@ await server.commerce.orders.createFulfillment({ orderNumber, items })
 await server.commerce.orders.updateFulfillment({ fulfillmentId, carrier, trackingNumber })
 await server.commerce.orders.bulkImportFulfillments({ items: [{ orderNumber, carrier, trackingNumber }] })
 
-// Provider-verified payment confirmation
-// Provider webhook handlers should verify with the provider first, then call:
-await server.commerce.orders.confirmPayment({
-  orderNumber,
-  pgProvider: 'provider-name',
-  pgPaymentId,
-  amount,
-  providerStatus: 'PAID',
-  providerEventId,
-})
-
-// Low-level transaction annotation / compatibility path. Prefer confirmPayment()
-// for normal provider-verified paid transitions.
-// status: 'failed' records a retryable PG failure on the Transaction only; the
-// Order stays pending until verified payment succeeds or the merchant cancels it.
-await server.commerce.orders.updateTransaction({ pgPaymentId, status, paymentMethod, receiptUrl })
-
 // Returns
 await server.commerce.orders.createReturn({
   orderNumber,
@@ -1163,8 +1452,14 @@ Available on both Client (customer JWT) and ServerClient (secretKey).
 
 ```typescript
 await client.commerce.discounts.validate({ code, orderAmount })
-await client.commerce.shipping.calculate({ shippingPolicyId?, orderAmount, postalCode? })
-// calculateShipping returns: { shippingAmount, baseShippingAmount, extraShippingAmount, freeShipping, freeShippingMinAmount, isJeju, isRemoteIsland }
+await client.commerce.shipping.calculate({
+  shippingPolicyId?,
+  orderAmount,
+  postalCode?,
+  countryCode?,
+  regionCode?,
+})
+// calculateShipping returns: { shippingAmount, shippingLines, baseShippingAmount, extraShippingAmount, freeShipping, freeShippingMinAmount, isJeju, isRemoteIsland }
 ```
 
 ### Commerce Product
@@ -1282,31 +1577,77 @@ for (const item of results) {
 
 ### Commerce Cart
 
-Available on both Client and ServerClient via `commerce.cart.*`. These helpers return sanitized customer-facing cart DTOs; use `server.collections.from('carts' | 'cart-items')` for raw operational cart documents.
+Available on both Client and ServerClient via `commerce.carts.*`. These helpers
+return required, browser-safe DTOs; use
+`server.collections.from('carts' | 'cart-items')` for raw operational documents.
 
 ```typescript
-// Add item to cart
-await client.commerce.cart.addItem({
-  cartId,
-  product,
-  variant,
-  option,
-  quantity,
+const created = await client.commerce.carts.create({
+  market: 'kr',
+  attributes: [{ key: 'channel', value: 'web' }],
+})
+const { cartToken, warnings } = created
+let cart = created.cart
+
+cart = (
+  await client.commerce.carts.addItem({
+    cartToken,
+    productId,
+    variantId,
+    quantity,
+    admissions: [{ eventId, occurrenceId, admissionTypeId }],
+    expectedRevision: cart.revision,
+    idempotencyKey: crypto.randomUUID(),
+  })
+).cart
+
+cart = (
+  await client.commerce.carts.updateItem({
+    cartToken,
+    cartItemId,
+    quantity,
+    expectedRevision: cart.revision,
+    idempotencyKey: crypto.randomUUID(),
+  })
+).cart
+cart = (
+  await client.commerce.carts.removeItem({
+    cartToken,
+    cartItemId,
+    expectedRevision: cart.revision,
+    idempotencyKey: crypto.randomUUID(),
+  })
+).cart
+await client.commerce.carts.retrieve({ cartToken })
+cart = (
+  await client.commerce.carts.updateDiscountCodes({
+    cartToken,
+    discountCodes: ['WELCOME10', 'FREESHIP'],
+    expectedRevision: cart.revision,
+    idempotencyKey: crypto.randomUUID(),
+  })
+).cart
+cart = (
+  await client.commerce.carts.updateAttributes({
+    cartToken,
+    attributes: [], // replace/clear
+    expectedRevision: cart.revision,
+    idempotencyKey: crypto.randomUUID(),
+  })
+).cart
+await client.commerce.carts.clear({
+  cartToken,
+  expectedRevision: cart.revision,
+  idempotencyKey: crypto.randomUUID(),
 })
-
-// Update item quantity
-await client.commerce.cart.updateItem({ cartItemId, quantity })
-
-// Remove item from cart
-await client.commerce.cart.removeItem({ cartItemId })
-
-// Other cart operations return sanitized customer-facing cart DTOs.
-await client.commerce.cart.get(cartId)
-await client.commerce.cart.applyDiscount({ cartId, discountCode })
-await client.commerce.cart.removeDiscount({ cartId })
-await client.commerce.cart.clear({ cartId })
 ```
 
+`updateDiscountCodes({ cartToken, discountCodes })` is the canonical full-list
+replacement API. Pass an empty list to clear codes. Singular `admission`,
+`applyDiscount()`, and `removeDiscount()` are not part of the 0.45 surface.
+Browser `mine()`/`merge({ guestCartToken })` derive customer identity from the
+JWT; server calls require an explicit `customerToken`.
+
 ### Community Moderation (ServerClient-only)
 
 Available only on ServerClient via `server.community.moderation.*`.
@@ -1412,7 +1753,7 @@ join-order surface and does not emit a semantic order-change webhook.
 
 ## Supported Collections
 
-Source of truth: `packages/sdk/src/core/collection/const.ts` (`COLLECTIONS`).
+Source of truth: `packages/published/sdk/src/core/collection/const.ts` (`COLLECTIONS`).
 
 | Category           | Browser-public generic collections                                                                                                                                 |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -1435,8 +1776,9 @@ operational records, raw cart/cart-item records, form submissions, raw community
 Canvas graph shell rows (`canvas-nodes`, `canvas-edges`), segmentation records,
 and moderation records. They remain available from
 `createServerClient().collections` with secret/PAT credentials. Shaped
-browser/customer helpers such as `commerce.cart.*`,
-`commerce.orders.listMine()`, and `commerce.orders.checkout()` remain available
+browser/customer helpers such as `commerce.carts.*`,
+`commerce.checkouts.create/retrieve`, `commerce.paymentSessions.*`, and
+`commerce.orders.listMine()` remain available
 where customer-facing DTOs are needed, but raw slugs are intentionally absent
 from browser collection discovery.