@01.software/sdk 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -0,0 +1,492 @@
+# @01.software/sdk
+
+## 0.41.0
+
+### Minor Changes
+
+- 02d271b: Add `projectProductToListingShape(product)` — a pure, non-lossy adapter that
+  turns a product read from the raw `collections.from('products').find()` escape
+  hatch into the listing shape the SDK builders consume. A raw/public product
+  already carries `priceRange`, `availableForSale`, and
+  `selectedOrFirstAvailableVariant` but has no `featuredImage`; the adapter fills
+  it from the first gallery image so SSG/sitemap consumers can feed
+  `buildProductListingGroupsByOption` / `buildProductListingCard` without
+  hand-rolling the projection.
+- eb6a4aa: Add `getVariantAvailableForSale(variant)` and `getVariantAvailableStock(variant)`
+  pure helpers to the root entry. They expose the SDK's server-equivalent variant
+  sellability rule (`isActive && (isUnlimited || stock - reservedStock > 0)`) and a
+  Shopify-style `quantityAvailable` number (`max(0, stock - reservedStock)`, or
+  `null` when unlimited), so storefronts can compute `availableForSale` without
+  re-implementing the check or shipping raw `stock`/`reservedStock` to the browser.
+
+### Patch Changes
+
+- 1c93448: Ship `MIGRATION.md` and `CHANGELOG.md` in the published npm tarball. The
+  `files` field previously included only `dist`, so the migration docs referenced
+  by the release notes were absent from the installed package. The README
+  changelog section now points at the shipped `CHANGELOG.md` / `MIGRATION.md`.
+
+## 0.40.0
+
+### Minor Changes
+
+- 85abdd1: BREAKING (0.x minor): Remove legacy `CustomerAddress.isDefault` from generated SDK Payload types. Customer default shipping and billing addresses are now represented only by `Customer.defaultShippingAddress` and `Customer.defaultBillingAddress`.
+- 3c3cb1f: **BREAKING (0.x minor)** — expose Shopify-shaped product listing fields (#1207).
+
+  The internal `listing` projection has been replaced by Shopify-aligned top-level
+  fields on `ProductDetail` and `ProductDetailCatalog`:
+  - Removed public exports: `ProductDetailListing`, `ProductDetailCatalogListing`,
+    `ProductListingGroupsCatalogListing`.
+  - Removed the `listing` field from `ProductDetail` / `ProductDetailCatalog`.
+  - Added `featuredImage`, `priceRange` (`ProductPriceRange`), `compareAtPriceRange`
+    (`ProductMoneyRange`), `availableForSale`, and `selectedOrFirstAvailableVariant`.
+  - `ProductDetailDisplayMediaSource` member `'listing_primary'` renamed to
+    `'featured_image'`.
+  - `ProductListingPageSort` literals renamed (`'listing.minPrice'` →
+    `'priceRange.minVariantPrice.amount'`, etc.).
+  - Private-contract helper `resolveListingPrimaryImagePointer` renamed to
+    `resolveFeaturedImagePointer`.
+  - `ProductUpsertResponse` staleness hint renamed `listingProjectionStale` →
+    `productProjectionStale`.
+
+  See `packages/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.
+- 7b1cfa3: BREAKING (0.x minor): Events range responses now expose the tenant-global calendar as `calendar` instead of `calendars`, and embedded range events use `event.calendar` instead of `event.calendars`. Calendar range filters now accept one `calendar` or `calendarSlug` value to match the singleton event calendar model.
+
+### Patch Changes
+
+- 4f1f970: Move `canvas-nodes` and `canvas-edges` out of browser-public collection discovery while keeping them available to server-auth SDK clients.
+- a55bbb2: Checkout/order separation (#1285): when the platform flag
+  `CHECKOUT_ORDER_SEPARATION` is on, `checkout()` resolves to a Checkout that is
+  promoted to an Order at payment. The public response stays `PublicOrder`-shaped
+  via the `projectCheckoutAsOrder` shim. `orderNumber` remains the stable
+  cross-window correlation key; pre-payment `id` is checkout-backed until
+  promotion, and `status` is projected to the legacy-compatible `pending` value for
+  open checkouts. No breaking change; the distinct `PublicCheckout` surface
+  remains a deferred follow-up.
+- b4ceb12: Add `placedAt` to the public `Order` type. This write-once timestamp marks when an order was first placed (the first paid transition) and is the placed-date basis for sales reporting. The field is additive and optional, so existing consumers are unaffected.
+- 67f35a7: Expose `returnStatus` on public order responses and document `status` /
+  `displayStatus` as deprecated compatibility aliases.
+- 3ce85af: Clarify generated order shipment field descriptions for tenant administrators.
+- 5b7daed: Expose product `storefrontVisibility` in generated SDK Payload types.
+- 645d7d4: Expose `customer-profile-stats` as a browser-readable public collection and type its public profile stats shape.
+- 60063b7: Expose the `refunded` transaction status across SDK and CLI transaction update contracts.
+- 30333d3: Move tenant commerce config into the SDK internal collection registry while keeping storefront collection discovery unchanged.
+
+## 0.39.0
+
+### Minor Changes
+
+- 07d3d00: BREAKING (0.x minor): browser publishable-key raw collection reads now reject
+  relationship-expanded `depth`, `joins`, or `populate` options before making a
+  request. Direct HTTP raw reads with publishable keys return `400` for the same
+  contract violation instead of a not-found response.
+
+  Browser commerce listing-group helpers are catalog-only: `listingPage()` and
+  `listingGroups()` use public-safe catalog endpoints, and full listing-group
+  responses require server credentials.
+
+- 07d3d00: Add `commerce.product.listingPage()` and the matching React Query helper
+  surface, including `useProductListingPage()`, for greenfield product listing
+  pages.
+- 77eb02f: Add a storefront cache resource helper subpath for product listing/detail SSG and ISR invalidation tags.
+
+### Patch Changes
+
+- 52f947a: Add browser-safe storefront content helpers for links and gallery items.
+
+## 0.38.0
+
+### Minor Changes
+
+- f6263df: Sanitize public SDK response surfaces and split browser-public collection
+  discovery from server-auth collection access.
+
+  The SDK now routes community post/comment reads through projected public
+  endpoints, exposes projected community response types, and removes raw
+  customer/order/cart/media/community slugs from browser-public `COLLECTIONS`.
+  Server-auth clients continue to address those slugs through
+  `SERVER_COLLECTIONS`.
+
+  The CLI now validates and discovers server-auth collections for authenticated
+  agent and CRUD workflows.
+
+  BREAKING (0.x minor): browser `COLLECTIONS` no longer includes raw
+  customer/order/cart/media/community slugs; use `SERVER_COLLECTIONS` or
+  `@01.software/sdk/server` for raw server-auth access. Browser publishable-key raw
+  collection reads now default SDK calls to `depth=0&joins=false`, and raw
+  publishable-key reads require those relationship-expansion defaults. Use shaped
+  helpers such as `commerce.product.detail()`, `commerce.cart.*`, community
+  helpers, and customer order helpers for populated customer-facing DTOs. Cart and
+  customer order methods now return sanitized public DTOs instead of raw Payload
+  documents.
+
+### Patch Changes
+
+- 0af07b3: Add generated Payload type documentation for Admin collection descriptions.
+- 7ca5b46: Refresh generated Payload SDK types after removing descriptions for retired Console-only collections.
+- 992bf72: Update generated event visibility documentation in SDK payload types to match the hardened public event API contract.
+- b2ce208: Expose structured event recurrence fields in generated SDK event collection types.
+- 1ba77f6: Drop the unreachable order-level `failed` status from the public order types.
+
+  Order-level payment failure is recorded as `Transaction.status = failed` while
+  the order stays `pending`; permanent abandonment uses cancellation. Generated
+  SDK Payload types and the public `CancelOrderStatus` union no longer include
+  order-level `failed` (transaction, fulfillment, and shipment `failed` are
+  unchanged). The MCP `cancel-order` guidance no longer lists order-level `failed`
+  as a local cancel-from state.
+
+- 3cbf9b6: Generated Payload types: `inventory-reservations` gains a `pending` (pre-payment
+  checkout hold) status alongside `held`/`released`/`consumed`, plus an optional
+  `expiresAt` TTL field. Additive and backward-compatible — part of the
+  checkout-time inventory reservation that prevents payment-window oversell (#1033).
+- 1034772: Classify the new `inventory-adjustments` collection as SDK-internal and sync
+  generated Payload types. The collection is the Console-side append-only
+  finite-stock movement ledger (#1038); it is hidden from SDK/MCP collection
+  discovery.
+
+  Behavior note for direct `product-variants` updates: changing tracked `stock`
+  via the collection API now requires the write-only `stockAdjustmentReason`
+  field (`received | correction | damage | loss | cycle_count | other`) unless
+  the write comes from an instrumented server flow. Updates without it are
+  rejected with `400 stock_adjustment_reason_required`.
+
+- 2313263: Align confirm-payment and public catalog contracts with server behavior.
+
+  The CLI `transaction confirm-payment` command now supports an explicit
+  `--idempotency-key`, rejects malformed amount tokens without truncation, and
+  accepts zero amounts per the confirm-payment contract. The SDK now exposes
+  `paymentKey` on confirm-payment params and stock-stripped catalog listing
+  response types.
+
+- 188f052: Register the `order-export-profiles` collection in the SDK collection set
+  (server-only) and generate its Payload type. The collection stores reusable,
+  schema-validated order export layouts consumed by the Console export mapping
+  engine; it is not exposed on the public storefront/query surface.
+- 9275bee: Clarify generated order display status field descriptions for the orders composite status UX.
+- 2c98b63: `CreateOrderItem.product` and `.option` are now optional: the create-order
+  endpoint derives the line's product from the variant's parent server-side,
+  so storefront items may send `variant` + `quantity` only.
+- 75f57f8: Order reads now include Shopify-style display axes in the generated SDK Payload
+  types: `displayFinancialStatus`, `displayFulfillmentStatus`, and non-null
+  `returnStatus`, while preserving the legacy compatibility status fields.
+- 62a2966: Expose the generated `billing_key_update` billing-history type in the public SDK
+  Payload types.
+
+## 0.37.0
+
+### Minor Changes
+
+- b6ce22b: Analytics: skip event sends on local hosts by default.
+
+  `createAnalytics()` and `<Analytics />` gain a `mode` option
+  (`'auto' | 'production' | 'development'`, default `'auto'`). In `'auto'` mode no
+  events are sent when the page runs on `localhost` / `127.0.0.1` / `*.local`;
+  validation and dev warnings still run and a one-time console notice is emitted.
+  Pass `mode: 'production'` to send while developing, or `mode: 'development'` to
+  force-disable on any host. The hosted analytics snippet gains an equivalent
+  `captureOnLocalhost` opt-in (`window.__01_analytics__.captureOnLocalhost` or
+  `data-capture-localhost="true"`). This is observable behavior INVARIANT 9.
+
+- 3068b31: Add `createCommerceNotificationWebhookHandler` and related commerce notification webhook types on the public webhook subpath. `createCommerceEmailWebhookHandler` remains a compatibility alias. Update MCP webhook guidance shipped in the CLI MCP stdio artifact.
+- 1b00174: BREAKING: Tighten product upsert swatch input types so color swatches require `color` and media swatches require `mediaItemId`.
+- 5072a76: Add `PRODUCT_PLP_FIND_OPTIONS` for join-safe raw `products.find()` PLP queries and document `listingGroupsCatalog()` as the preferred listing path. MCP query-builder docs now explain Payload join-field default limits.
+- 79e52c8: Add tenant-configurable initial order shipping refund policy on returns. SDK create-return and return-with-refund clients accept `initialShippingRefundAmount` and override note fields; CLI `return create` and `return refund` expose matching flags.
+- 030e030: Improve SDK relation and order input ergonomics.
+
+  `resolveRelation<T>()` now accepts unknown relation values, and create-order
+  inputs accept `items` as a storefront-facing alias that serializes to the
+  existing `orderItems` endpoint field. The CLI order create path stays aligned
+  with the SDK order input contract.
+
+- d661646: Add Shopify-like fulfillment preparation and shipment APIs. Fulfillment creation can start shipment without carrier/tracking, and fulfillment updates can add or correct tracking information later.
+
+### Patch Changes
+
+- e6c6f59: Normalize community create/update helper responses that return Payload `{ doc }` wrappers so SDK callers receive the created or updated resource directly.
+- bb22a83: Fix `IMAGE_SIZES` to match platform upload tiers `[200, 400, 800, 1200, 1600]` so `getImageUrl` and `getImageSrcSet` select real renditions instead of silently falling back to originals. Legacy numeric size keys (e.g. `1536`) remain supported at runtime.
+- 02e41c8: Expose the operator-voided `Fulfillment.status = 'canceled'` value in generated SDK Payload types.
+- ca495fc: Expose optional `ProductTag.color` metadata in generated SDK Payload types.
+
+## 0.36.0
+
+### Minor Changes
+
+- c4956b2: Paid order cancel responses now include `refundPending: true` when a captured
+  payment still awaits storefront PG refund after local cancellation. Legacy
+  `reconciliationRequired` responses remain for older inline-PG-cancel rows.
+  MCP order-flow guidance reflects local-only cancel ownership.
+
+  **Consumer migration:** `providerRefunded` is no longer `true` on new cancels.
+  Paid local cancel responses now always have `refundedAmount: 0` and
+  `refundPending: true` instead of a positive `refundedAmount` and
+  `providerRefunded: true`.
+
+- 06e061a: Add `POST /api/orders/resolve-cancel-refund` and
+  `client.commerce.orders.resolveCancelRefund(...)` so storefront/BFF code can
+  report PG cancel-refund success or failure back to the platform idempotently.
+  The existing `alreadyCanceled + refundPending` cancel-order response remains
+  backward-compatible and continues to accept any nonnegative `refundedAmount`;
+  new paid local-cancel responses still emit `refundedAmount: 0` while PG refund
+  settlement is pending by design (#826).
+- b97d35e: BREAKING (0.x minor): Simplify listing projection — remove persisted listing
+  grouping and `listingPrimaryOption` across console, contracts, and SDK surfaces.
+  `ProductListingGroupsItem` drops `primaryOptionId`, `listingGroupingState`, and
+  `listingGroupingEmptyReason`; generated `Product` types drop `listingPrimaryOption`
+  and `listing.grouping*` fields; SDK no longer exports `ListingGroupingState` /
+  `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`.
+
+## 0.35.0
+
+### Minor Changes
+
+- 10fff1d: Add the `@01.software/sdk/errors` public subpath for SDK error classes, type
+  guards, and factory helpers. The entrypoint re-exports the same surface already
+  available from the root package without pulling React, Next.js, or internal SDK
+  modules. ESM and CJS builds are included in the published artifact.
+
+## 0.34.0
+
+### Minor Changes
+
+- BREAKING (0.x minor): Simplify listing projection — remove persisted listing
+  grouping and `listingPrimaryOption` across console, contracts, and SDK surfaces.
+  `ProductListingGroupsItem` drops `primaryOptionId`, `listingGroupingState`, and
+  `listingGroupingEmptyReason`; generated `Product` / `ProductsSelect` drop
+  `listingPrimaryOption` and `listing.grouping*` fields; SDK no longer exports
+  `ListingGroupingState` / `ListingGroupingEmptyReason`. Swatch groups derive from
+  the first product option by `_order` (migration reorders legacy primaries).
+  `buildProductListingCard` uses persisted min/max when both are present and
+  merges compare-at from groups when compare-at keys are absent.
+  See `MIGRATION.md` (Listing projection simplification).
+- 0c12c2b: BREAKING (0.x minor): Remove the Canvas `BUILT_IN_NODE_TYPES` and
+  `BUILT_IN_EDGE_TYPES` exports. Canvas node and edge definitions now come from the
+  tenant database catalog. Optional starter rows are imported through explicit
+  migrate or seed commands; `useCanvasData()` defaults `nodeTypeDefs` and
+  `edgeTypeDefs` to empty arrays unless callers pass catalog data.
+- bafcf2d: Add catalog/stock split commerce reads: `detailCatalog()`, `listingGroupsCatalog()`, `stockSnapshot()`, and `mergeProductDetailWithStock()` for edge-cached catalog shells with live inventory snapshots. Existing `detail()` and POST endpoints remain unchanged.
+- 7990112: Product admin save splits Payload document writes from graph upsert; SDK mirrors upsert graph conflict and revision-required error bodies without depending on private contracts. CLI aligns with vitest 4 catalog for dependency health.
+- 2bf6ddc: Add `ProductSelectionCodecOptions.fillDefaults` and exported `selectNext()` for product selection. Opt-in `fillDefaults` on `resolveProductSelection()` fills unselected options to a concrete variant using available-by-order rules aligned with listing `selectionHintVariant`. `selectNext()` applies slug-based option-click transitions, keeps compatible prior selections, and re-defaults incompatible ones. Default `fillDefaults` remains `false` for backward compatibility.
+- a56c69a: Add optional `idempotencyKey` to retry-sensitive `server.commerce.orders`
+  mutations (`create`, `checkout`, `createFulfillment`, `createReturn`,
+  `returnWithRefund`, `confirmPayment`, `cancelOrder`). The SDK sends
+  `X-Idempotency-Key` and omits the key from JSON bodies. For `confirmPayment`,
+  `idempotencyKey` overrides `providerEventId` when both are set.
+
+  Expose the provider-verified `server.commerce.orders.cancelOrder()` method and
+  public cancel types. `CancelOrderResponse` is now a mutually exclusive union for
+  committed, `alreadyCanceled`, and `reconciliationRequired` outcomes, and the SDK
+  only sends the explicit cancel request body fields.
+
+  Add `orderCanceled` to the semantic commerce notification/webhook helper
+  surface. Operators should treat `alreadyCanceled` as idempotent success and
+  `reconciliationRequired` as the durable handoff signal after a provider refund
+  when local cancellation could not safely commit.
+
+  The matching private contracts package is ignored by changeset policy.
+
+- fa4ce7d: Default `commerce.product.detail()` and `listingGroups()` to GET query transport for Edge CDN caching. Console POST endpoints remain supported for backward compatibility and large listing-groups batches.
+- 09e9422: Default product selection URL stringify and `buildProductHref()` partial output to slug-compat params (`opt.color=ivory`) instead of canonical ID params. Adds `ProductListingGroup.optionSlug` in SDK and `@01.software/contracts` for listing href generation. Listing hint `variant=` links require `preferCompleteVariantFromHint: true`. Parse behavior unchanged. Opt out with `emit: 'canonical-id'`.
+
+## 0.33.0
+
+### Minor Changes
+
+- 906577e: Add headless commerce email webhook helpers for routing commerce notification events, deriving idempotency keys, and typing tenant email configuration manifests.
+- ecba235: BREAKING (0.x minor): Replace the product-detail `totalInventory` unlimited sentinel with explicit inventory rollups. `commerce.product.detail()` successful payloads now expose `product.hasUnlimitedVariant`; `product.totalInventory` is the tracked stock sum across non-unlimited variants and can be `null` when no variants are tracked.
+- 156ff73: BREAKING (0.x minor): Change `commerce.product.detail()` to return a `ProductDetailResult`
+  discriminated union instead of `ProductDetail | null`. Successful responses now
+  return `{ found: true, product }`; product-detail 404 responses return
+  `{ found: false, reason }` with `not_found`, `not_published`, or
+  `feature_disabled`. Permission/auth responses, including 403 tenant mismatch,
+  continue to throw typed SDK errors. Any product-detail 404 without an
+  allowlisted code/reason also throws instead of being collapsed, so unexpected
+  backend absence states remain visible during integration.
+- ef4abdf: Expose commerce notification webhook constants, public types, and a semantic event guard from the SDK webhook entrypoint.
+
+## 0.32.0
+
+### Minor Changes
+
+- 4fea701: Add generic order payment confirmation support through `commerce.orders.confirmPayment()`.
+  Order creation item IDs now accept string or numeric entity identifiers while
+  legacy caller-supplied line prices remain compatibility-only inputs.
+- 6407210: Add the server-only SDK tenant introspection API and route CLI schema and
+  feature-progress discovery through the SDK instead of command-local fetches.
+
+### Patch Changes
+
+- 11c1878: Remove retired marker wording from order creation compatibility fields.
+- bc94da6: Route customer auth requests through the shared SDK transport so request IDs,
+  usage-limit errors, API reason mapping, origin suggestions, and timeout/network
+  errors match the rest of the SDK while keeping customer auth endpoint retries
+  disabled. Customer auth failures now surface the same SDK-specific error classes
+  as other SDK requests instead of the previous generic API error shape.
+
+## Unreleased
+
+### Minor Changes
+
+- BREAKING (0.x minor): `resolveProductSelectionMedia()` no longer returns
+  `product_primary` or `product_pool`; use `resolveProductDisplayMedia()` or
+  `resolveProductSelection()` display fallback when strict selection is `none`.
+  Option swatch selection returns the swatch image only, not the full product pool.
+  Listing primary display fallback is pool-only (`products.images[]`).
+
+- Add `EventsClient` and `client.events` / `server.events` helpers for public
+  event occurrence range reads, event registration, guest registration lookup,
+  and guest self-cancel flows. These helpers require `X-Publishable-Key`, keep
+  `server.events` on the public event-helper credential boundary without
+  forwarding `secretKey`, and derive registration `customer` identity from
+  customer auth rather than public request body input. **Breaking:** **`POST
+/api/event-registrations/register` rejects `body.customer` with `400
+bad_request`;** bind customers with `Authorization: Bearer` only. See
+  `docs/events/public-api-contract.md` for migration. Guest-token lookup/cancel
+  helpers send tokens in POST bodies. Range helpers support calendar, category,
+  and tag filters aligned with the Console public range endpoint. Exported
+  structural `RootClient` / `RootServerClient` keep `events` optional for
+  object-literal mocks; `createClient()` / `createServerClient()` return
+  `RootClientWithEvents` / `RootServerClientWithEvents` with required `events`.
+
+- **BREAKING (0.x minor):** Remove flat `swatchColor` from product-detail option
+  values, SDK matrix/selection shapes, and listing projections that mirrored the
+  removed Payload field. Use nested `swatch: { type, color, mediaItemId }` (or
+  selection `swatch.color` / `swatch.image`). `ProductApi.upsert()` and Console
+  HTTP upsert reject unknown `swatchColor` on option-value input; send
+  `swatch: { type: 'color', color: '#...' }` instead. MCP `product-upsert` no
+  longer documents `swatchColor` in the tool schema.
+
+- Add handoff-aligned fields on `ProductSelectionAvailableValue`: `exists` (alias
+  of `available`), `label` (same source as `value`), and Shopify-shaped
+  `swatch: { color, image }` via exported `ProductSelectionAvailableSwatch`.
+  Flat `thumbnail` and `images` on selection values are unchanged. Document
+  selection-hint vs `fillDefaults` behavior in SDK README and `AGENTS.md`.
+
+- Add `ProductSelectionCodecOptions.fillDefaults` and `selectNext()` for product
+  selection. Opt-in `fillDefaults` resolves partial selections to a concrete
+  variant using the same available-by-order rules as listing
+  `selectionHintVariant`. `selectNext()` applies option-click transitions while
+  keeping compatible prior values and re-defaulting incompatible ones.
+
+- **BREAKING (0.x minor):** Align `CreateOrderItem` with the create-order API
+  request contract. `product`, `variant`, and `option` are required scalar IDs.
+  The create-order endpoint still accepts `unitPrice` and `totalPrice` as
+  optional compatibility inputs, but the server derives authoritative line money
+  values from product variants.
+
+- **BREAKING (0.x minor):** Remove legacy product media fields from detail and
+  listing contracts. Selection media now resolves through
+  `resolveProductSelectionMedia` pointer/pool rules; direct
+  `variant.thumbnail`, option-value `thumbnail`/`images`, product `thumbnail`,
+  and `mediaSets` gallery fallback fields are no longer authoritative SDK
+  resolver inputs. Empty `mediaSets` intentionally falls through to selection
+  media. Deprecated one-release `resolveProductMedia` and
+  `resolveProductGallery` shims remain for migration, but legacy direct-media
+  fallback precedence is removed.
+
+- Deprecate `resolveProductGallery`, `utils/product-gallery`, and related
+  `ProductMediaSetInput` / `ProductGallerySource` names as one-release shims
+  that forward or fall through to `resolveProductSelectionMedia`. Product detail
+  `mediaSets` and variant `gallerySource` fields are removed rather than
+  deprecated; only the gallery helper names remain as temporary shims.
+
+## 0.31.0
+
+### Minor Changes
+
+- 6cadf1e: Remove the generated `parent` field from default tag collection types. Tags are
+  now flat by default across content, media, events, canvas, and ecommerce
+  taxonomy collections; category collections continue to expose `parent` for
+  hierarchy.
+- 6cadf1e: Add `server.preview.detail()` for generic saved-record preview lookups and route
+  product `previewDetail()` through the generic preview detail endpoint.
+
+  Preview redirects now use `/api/preview/start?collection=<slug>&id=<id>` and
+  send tenant frontends to `<origin><draftPath>?token=...&collection=<slug>&id=...`.
+  Tenant preview configuration has moved to `tenants.previewDestinations` with
+  `draftPath` defaulting to `/api/01software/draft`; migrate old product-only
+  draft routes and `/api/products/*/preview` integrations to the generic
+  collection/id contract.
+
+## 0.30.1
+
+### Patch Changes
+
+- auto release 5d91b13ba2
+
+## 0.30.0
+
+### Minor Changes
+
+- 51a6399: **BREAKING (0.x minor):** Split feature-specific SDK surfaces out of the root entry so `createClient`
+  consumers do not need React Query, Next.js, Payload, rich text, canvas, or code
+  highlighting peers. The root entry is now the browser-safe core surface;
+  server-only code must import `createServerClient` from `@01.software/sdk/server`,
+  and React Query hooks/helpers must import from `@01.software/sdk/query`.
+
+  Migration notes:
+  - `createClient` remains available from `@01.software/sdk` and
+    `@01.software/sdk/client`.
+  - `createServerClient` must move to `@01.software/sdk/server`; it is no longer
+    exported from the root browser-safe entry.
+  - React Query hooks and cache helpers must move to `@01.software/sdk/query`.
+  - UI components live under explicit `@01.software/sdk/ui/*` sub-paths. Install
+    only the optional peers listed for the sub-paths you import.
+
+- 51a6399: Add stable product-detail selection helpers for ecommerce storefronts.
+
+  Product detail responses now expose option and option-value compatibility slugs,
+  and the SDK adds helpers for building option matrices from detail responses,
+  parsing and stringifying selection URLs, and resolving selected/partial variant
+  state. New selection URLs use stable variant/option/value IDs; slug URLs remain
+  read-only compatibility input for older storefront links.
+
+- 51a6399: Improve tenant-admin consumer ergonomics.
+
+  Server React Query helpers can now address server-only SDK collections such as
+  customer groups, reports, and community bans. SDK clients also accept an
+  explicit `apiUrl` override for staging, preview, self-hosted, and proxy
+  deployments. README examples now steer product catalog writes through the
+  transactional `server.commerce.product.upsert()` helper and clarify the current
+  local-only customer auth method boundary.
+
+### Patch Changes
+
+- 51a6399: Strengthen packaged SDK boundary checks and document that Console-shared
+  contracts stay private.
+- 51a6399: Fix product listing group detail links so grouped option-value selections emit
+  partial ID-based selection URLs before falling back to listing hint variants.
+
+## 0.29.0
+
+### Minor Changes
+
+- 3061394: Add slug-based product detail selection helpers for ecommerce storefronts.
+
+  Product detail responses now expose option and option-value slugs, and the SDK
+  adds helpers for building option matrices from detail responses, parsing and
+  stringifying selection URLs, and resolving selected/partial variant state.
+
+## 0.28.0
+
+### Minor Changes
+
+- 75b7b1c: Remove unused playlist and track fields from generated Payload types:
+  `playlists.coverArt`, `playlists.isCollaborative`, `playlists.videos`,
+  `tracks.content`, `tracks.isFeatured`, `tracks.publishedAt`, and
+  `tracks.isEmbeddable`.
+
+## 0.27.0
+
+### Minor Changes
+
+- Relax generated collection types for title and event default fields that can
+  now be absent or null in tenant content responses.
+
+- Add package repository metadata and align release scripts with the Changesets
+  and npm trusted publishing workflow.

package/MIGRATION.md

@@ -0,0 +1,183 @@
+# @01.software/sdk Migration Notes
+
+## Shopify-shaped product listing fields (#1207)
+
+Next minor release as a semver minor for the pre-1.0 SDK. This release removes
+public product-detail exports and renames public union/sort literals, and must
+be called out in release notes as `BREAKING (0.x minor)`.
+
+### Removed public exports
+
+- `ProductDetailListing`
+- `ProductDetailCatalogListing`
+- `ProductListingGroupsCatalogListing`
+
+### Removed fields
+
+`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`                         |
+
+The new range types are exported as `ProductPriceRange` (price range, with
+`isPriceRange`) and `ProductMoneyRange` (compare-at range).
+
+### Renamed literals
+
+- `ProductDetailDisplayMediaSource`: `'listing_primary'` → `'featured_image'`.
+- `ProductListingPageSort`: `'listing.minPrice'` / `'-listing.minPrice'` /
+  `'listing.maxPrice'` / `'-listing.maxPrice'` →
+  `'priceRange.minVariantPrice.amount'` / `'-priceRange.minVariantPrice.amount'`.
+- Private-contract helper `resolveListingPrimaryImagePointer` →
+  `resolveFeaturedImagePointer` (input field `listingPrimaryImage` →
+  `featuredImage`).
+
+### Product upsert response
+
+`ProductApi.upsert()` (`POST /api/products/upsert`) renames its
+projection-staleness hint:
+
+```diff
+- { ok: true, product, listingProjectionStale: boolean }
++ { ok: true, product, productProjectionStale: boolean }
+```
+
+The CSV bulk-import per-row response renames `listingSyncOk` / `listingSyncError`
+to `projectionSyncOk` / `projectionSyncError`.
+
+## Listing projection simplification
+
+Target release: `0.34.0` as a semver minor for the pre-1.0 SDK. This release
+contains breaking listing-groups and product upsert behavior and must be called
+out in release notes as `BREAKING (0.x minor)`.
+
+### Removed fields
+
+`ProductListingGroupsItem` no longer includes:
+
+- `primaryOptionId`
+- `listingGroupingState`
+- `listingGroupingEmptyReason`
+
+Generated `Product` / `ProductsSelect` types no longer include:
+
+- top-level `listingPrimaryOption`
+- `listing.groupingState`, `listing.groupingEmptyReason`, `listing.groupingCount`
+
+Public SDK exports removed:
+
+- `ListingGroupingState`
+- `ListingGroupingEmptyReason`
+
+Platform `ProductUpsertSchema` no longer accepts `listingPrimaryOption`
+(released through the SDK; see SDK notes below).
+
+Product upsert inputs no longer accept `listingPrimaryOption`.
+
+### Swatch grouping behavior
+
+Listing-groups `groups` are now derived at read time from the **first product
+option by `_order`**, not from a persisted primary option.
+
+Migration `20260613_000000_drop_product_listing_grouping_and_primary_option`
+**swaps option `_order` with the first option** when `listing_primary_option_id`
+was set to a non-first option, so existing storefront swatch grouping is
+preserved before the column is dropped. Option order in Admin may change for
+affected products.
+
+Before deploy, quantify products that configured a primary option (column exists
+until that migration runs):
+
+```sql
+SELECT COUNT(*) FROM products WHERE listing_primary_option_id IS NOT NULL;
+```
+
+Products where the primary option was not already first (reordered by migration):
+
+```sql
+WITH ranked AS (
+  SELECT
+    p.id AS product_id,
+    p.listing_primary_option_id,
+    po.id AS option_id,
+    ROW_NUMBER() OVER (
+      PARTITION BY p.id
+      ORDER BY
+        CASE
+          WHEN po._order ~ '^-?[0-9]+$' THEN po._order::numeric
+          ELSE 2147483647
+        END,
+        po._order NULLS LAST,
+        po.id
+    ) AS rn
+  FROM products p
+  JOIN product_options po ON po.product_id = p.id
+  WHERE p.listing_primary_option_id IS NOT NULL
+)
+SELECT COUNT(DISTINCT product_id)
+FROM ranked
+WHERE rn = 1 AND option_id <> listing_primary_option_id;
+```
+
+### `buildProductListingCard` price and availability
+
+When **both** `product.priceRange.minVariantPrice.amount` and
+`product.priceRange.maxVariantPrice.amount` are set, the SDK card uses those
+persisted values instead of aggregating from `groups`. Compare-at fields are
+taken from `product.compareAtPriceRange` only when both amount bounds are
+present; otherwise compare-at is merged from `groups`, then on-the-fly
+projection. Partial Product price ranges fall back to group aggregation
+entirely.
+
+When `product.availableForSale` is set, it takes precedence over group
+availability. Ensure the Product projection stays in sync on product saves, or
+cards may show stale prices relative to live variant data.
+
+## Canvas Tenant Catalog Runtime
+
+Target release: `0.34.0` as a semver minor for the pre-1.0 SDK. This release
+contains breaking Canvas API behavior and must be called out in release notes as
+`BREAKING (0.x minor)`.
+
+### Removed Exports
+
+The `@01.software/sdk/ui/canvas` entry no longer exports:
+
+- `BUILT_IN_NODE_TYPES`
+- `BUILT_IN_EDGE_TYPES`
+
+The server barrel also no longer exports these `BUILT_IN_*` arrays.
+
+The platform Canvas catalog concept has been removed. Canvas node and edge
+types now live only in the tenant database catalog. Optional starter rows
+(`text`, `image`, and `default`) are ordinary tenant data imported through the
+explicit starter catalog migration or single-tenant seed command.
+
+### Runtime Catalog Inputs
+
+`useCanvasData()` no longer merges SDK built-in node or edge definitions. Its
+`nodeTypeDefs` and `edgeTypeDefs` options default to empty arrays.
+
+Consumers must pass catalog definitions from one of these sources:
+
+- `useCanvas()`, which returns `nodeTypeDefs` and `edgeTypeDefs` from the tenant
+  catalog API.
+- Server props or loader data populated from `canvas-node-types` and
+  `canvas-edge-types`.
+
+`CanvasRenderer` likewise expects `nodeTypeDefs` and `edgeTypeDefs` from the
+tenant catalog when rendering dynamic nodes or styled edges. Image rendering is
+field-based: image output comes from catalog fields with `fieldType: 'image'`,
+not from a special `nodeTypeSlug === 'image'` branch. Do not rebuild the
+removed `BUILT_IN_*` arrays in application code; seed the tenant catalog
+instead. Server consumers should import CSS sanitizers from
+`@01.software/sdk/ui/canvas/server`.