@01.software/sdk 0.37.0 → 0.39.0

package/README.md

@@ -19,7 +19,7 @@ pnpm add @01.software/sdk
 - Customer auth hooks (useCustomerMe, useCustomerLogin, etc.) with cache management
 - Automatic retry with exponential backoff (non-retryable: 400, 401, 403, 404, 409, 422)
 - Webhook handling with HMAC-SHA256 signature verification
-- Sub-path imports (`./server`, `./webhook`, `./realtime`, `./ui/*`) for tree-shaking
+- Sub-path imports (`./server`, `./webhook`, `./realtime`, `./storefront-cache`, `./ui/*`) for tree-shaking
 - Type-safe read-only `collections.from()` for Client (compile-time write prevention)
 
 ### Sub-path Imports
@@ -57,6 +57,9 @@ import {
 // Realtime only
 import { createRealtimeClient } from '@01.software/sdk/realtime'
 
+// Storefront cache resource names for SSG/ISR adapters
+import { storefrontCacheResources } from '@01.software/sdk/storefront-cache'
+
 // Components - sub-path imports per domain
 import { Analytics } from '@01.software/sdk/analytics/react'
 import { RichTextContent } from '@01.software/sdk/ui/rich-text'
@@ -79,6 +82,7 @@ entry.
 | `@01.software/sdk/server`           | `createServerClient`, server-only collection, commerce, and preview APIs | none; keep `secretKey` code on the server                                                                  |
 | `@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                                                                                                       |
 | `@01.software/sdk/analytics/react`  | `<Analytics />`                                                          | `react`, `react-dom`                                                                                       |
 | `@01.software/sdk/ui/rich-text`     | `RichTextContent`, `StyledRichTextContent`                               | `react`, `react-dom`, `@payloadcms/richtext-lexical`                                                       |
 | `@01.software/sdk/ui/form`          | `FormRenderer`                                                           | `react`, `react-dom`                                                                                       |
@@ -99,6 +103,8 @@ Migration quick reference:
 - `createServerClient` must be imported from `@01.software/sdk/server`.
 - React Query hooks and cache helpers must be imported from
   `@01.software/sdk/query`.
+- Product storefront cache resource helpers must be imported from
+  `@01.software/sdk/storefront-cache`.
 - UI components must be imported from the specific `@01.software/sdk/ui/*`
   sub-path and require only that row's peers.
 - Console-shared pure ecommerce helpers live in private
@@ -140,8 +146,16 @@ const serverQuery = createServerQueryHooks(server)
 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 }],
+  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
@@ -176,6 +190,61 @@ previewToken })` returns the raw product detail payload for the saved
 draft/unpublished record addressed by the preview token. `detail()` wraps the
 published storefront payload in a `{ found, product | reason }` result.
 
+## Getting storefront content
+
+Use shaped content helpers when a browser storefront needs relationship-backed
+media for common public content. These helpers use the publishable key only;
+the server resolves the tenant, enforces the owning feature, excludes drafts,
+and returns allowlisted DTOs instead of raw Payload documents.
+
+```typescript
+import { createClient } from '@01.software/sdk'
+
+const client = createClient({ publishableKey: '<publishable-key>' })
+
+const links = await client.content.links.list({
+  limit: 10,
+  categorySlug: 'social',
+  tagSlug: 'footer',
+  featured: true,
+  sort: 'title',
+})
+
+const gallery = await client.content.galleryItems.list({
+  gallerySlug: 'spring-lookbook',
+  limit: 24,
+})
+```
+
+`content.links.list()` calls `GET /api/links/storefront`; link DTOs include
+display fields, categories/tags, thumbnail, and icon media. Operator-only
+fields such as tenant, metadata, click counters, and private storage details
+are omitted. Use `categorySlug` and `tagSlug` for stable storefront URLs when
+available; `categoryId` and `tagId` are also supported. Expired links are
+excluded by default, though visible link DTOs may include `expiresAt` so
+storefronts can render time-sensitive copy.
+
+`content.galleryItems.list()` calls `GET /api/gallery-items/storefront`;
+gallery item DTOs include title, description, content, gallery reference, and
+image media. Tenant, metadata, draft status, and storage/provider internals are
+omitted. Gallery item reads require either `gallerySlug` or `galleryId`; prefer
+`gallerySlug` for storefront routes. The default gallery item sort is `manual`,
+matching curator order from the Admin Panel.
+
+Both helpers return Payload-style pagination (`docs`, `totalDocs`, `page`,
+`limit`, etc.). `limit` is bounded server-side to `1..100`; invalid query,
+publishable-key, feature, rate-limit, and server errors surface through the
+SDK's typed error classes and preserve request IDs on `client.lastRequestId`.
+SDK sort inputs are typed public allowlists: links support created/updated/
+published dates, title, and featured ordering; gallery items support manual
+curator order, created/updated dates, and title.
+
+Use `client.collections.from(...).find()` only as the advanced raw collection
+escape hatch. Browser publishable-key raw reads stay shallow (`depth: 0`,
+`joins: false`) and are not for relationship-expanded media. Use shaped helpers
+for storefront content media, or `createServerClient()` when a server route
+needs full raw collection access with server credentials.
+
 ## Getting product detail
 
 The recommended way to fetch a single product is the shaped helper:
@@ -219,14 +288,13 @@ catalog/stock split instead of reading `variant.stock` from a cached
 `detail()` response (inventory in that payload can lag for the catalog TTL).
 
 ```typescript
-import {
-  createClient,
-  mergeProductDetailWithStock,
-} from '@01.software/sdk'
+import { createClient, mergeProductDetailWithStock } from '@01.software/sdk'
 
 const client = createClient({ publishableKey: '<publishable-key>' })
 
-const catalog = await client.commerce.product.detailCatalog({ slug: 'every-peach-tee' })
+const catalog = await client.commerce.product.detailCatalog({
+  slug: 'every-peach-tee',
+})
 if (!catalog.found) return notFound()
 
 const variantIds = catalog.product.variants.map((v) => v.id)
@@ -238,46 +306,63 @@ const { product, stockMergeStatus } = mergeProductDetailWithStock(
 // stockMergeStatus: 'complete' | 'partial' — partial when a variant id is missing from snapshot
 ```
 
-Listing groups use the same pattern: `listingGroupsCatalog()` for the cacheable
-shell, then `stockSnapshot()` (or `stock-check` at cart/checkout) for live
+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`.
 
 ### Product Listing Pages (PLP) — join-safe queries
 
-**Recommended path:** Use `commerce.product.listingGroupsCatalog()` (or the
-`useProductListingGroupsCatalogQuery` hook) together with
-`buildProductListingCard()`. The endpoint applies unlimited join fetches
-server-side and returns pre-grouped `ProductListingGroupsItem[]` data, so color
-swatches are never truncated regardless of how many option values the product
-has.
+**Recommended path:** Use `commerce.product.listingPage()` (or
+`createQueryHooks(client).useProductListingPage()`) for greenfield storefront
+PLPs. It wraps the cacheable listing-groups query endpoint, keeps the raw
+Payload pagination response, and adds `cards` built with
+`buildProductListingCard()`. The endpoint returns pre-grouped listing data and
+avoids the top-level `products.options` / `products.variants` join truncation
+that raw REST product queries hit by default.
 
 ```typescript
-import {
-  buildProductListingCard,
-  type ProductListingCard,
-} from '@01.software/sdk'
-
-const response = await client.commerce.product.listingGroupsCatalog({
-  where: { status: { equals: 'published' } },
+const response = await client.commerce.product.listingPage({
+  search: 'shirt',
   limit: 24,
+  filters: {
+    categoryIds: ['category-1'],
+    price: { min: 10000, max: 50000 },
+    availableForSale: true,
+  },
+  basePath: '/shop',
 })
 
-const cards: ProductListingCard[] = response.docs.map((item) =>
-  buildProductListingCard(item, { basePath: '/shop' }),
-)
+const cards = response.cards
+```
+
+Use `commerce.product.listingGroupsCatalog({ productIds })` when product IDs
+are already known, for example curated rails, recommendations, or editorial
+sections:
+
+```typescript
+const response = await client.commerce.product.listingGroupsCatalog({
+  productIds: ['product-1', 'product-2'],
+})
 ```
 
-**Escape hatch:** When you need to query the `products` collection directly
-(bulk operations, custom filters, fields the helper does not expose), spread
+**Server-auth escape hatch:** When server code deliberately needs raw
+`products` collection reads (bulk operations, custom filters, fields the helper
+does not expose), use `createServerClient()` and spread
 `PRODUCT_PLP_FIND_OPTIONS` to raise the default Payload join limit of 10:
 
 ```typescript
-import {
-  PRODUCT_PLP_FIND_OPTIONS,
-} from '@01.software/sdk'
+import { PRODUCT_PLP_FIND_OPTIONS } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
-const { docs } = await client.collections.from('products').find({
+const server = createServerClient({
+  publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
+  apiUrl: process.env.SOFTWARE_API_URL!,
+  secretKey: process.env.SOFTWARE_SECRET_KEY!,
+})
+
+const { docs } = await server.collections.from('products').find({
   ...PRODUCT_PLP_FIND_OPTIONS,
   where: { status: { equals: 'published' } },
   limit: 24,
@@ -288,7 +373,10 @@ const { docs } = await client.collections.from('products').find({
 limits with `sort: '_order'`. It cures top-level `products.options` and
 `products.variants` join truncation but **cannot** cure the nested
 `options[].values.docs` join — the Payload REST `joins` param is flat and
-nested join limits require the listing-groups endpoint.
+nested join limits require the listing-groups endpoint. This preset is not
+accepted by publishable `createClient().collections.from('products').find()`
+because browser-public raw reads are constrained to `depth: 0` and
+`joins: false`, and cannot use `populate`.
 
 ### Product selection helpers
 
@@ -325,9 +413,9 @@ aligned without rebuilding media priority in storefront code.
 
 For new storefront work, prefer pool-pointer and gallery-aware resolution from
 `commerce.product.detail()` + `resolveProductSelection()` (and
-`getProductSelectionImages()` when a list is needed). Direct legacy fields like
+`getProductSelectionImages()` when a list is needed). Direct pre-ADR-0025 fields like
 `variant.thumbnail` and option-value direct `images` are still accepted as
-compatibility input, but are deprecated as primary storefront media sources.
+transitional input, but are no longer primary storefront media sources.
 
 `availableValuesByOptionSlug` / `availableValuesByOptionId` include
 `availableStock`, `isUnlimited`, and `availableForSale` per value so option UIs
@@ -393,9 +481,13 @@ By default, partial selections (for example color only) leave
 `selectedOrFirstAvailableVariant` behavior with `fillDefaults: true`:
 
 ```typescript
-const resolution = resolveProductSelection(product, codec.parse('?opt.color=ivory'), {
-  fillDefaults: true,
-})
+const resolution = resolveProductSelection(
+  product,
+  codec.parse('?opt.color=ivory'),
+  {
+    fillDefaults: true,
+  },
+)
 // resolution.selectedVariant is concrete; unselected options are filled
 // using the same available-by-order rules as listing selectionHintVariant.
 ```
@@ -446,8 +538,8 @@ Selection query params are share/deep-link state, not index targets.
 ### Product listing card helper
 
 `buildProductListingCard(item, options?)` turns a single
-`commerce.product.listingGroups()` response item into a render-ready
-`ProductListingCard`. Each item includes `listingGroupingState` (`grouped`,
+`commerce.product.listingPage()` or `listingGroupsCatalog()` response item into
+a render-ready `ProductListingCard`. Each item includes `listingGroupingState` (`grouped`,
 `no_primary_option`, or `empty`) and, when empty, `listingGroupingEmptyReason`
 (`primary_option_not_linked`, `primary_option_has_no_values`, or
 `no_variants_for_primary_option`). Each group includes public-safe
@@ -488,14 +580,17 @@ the card should deep-link a complete hint variant.
 
 ## Storefront performance defaults
 
-- **PLP:** prefer `useProductListingGroupsCatalogQuery()` (GET `/api/products/listing-groups/query/catalog`, CDN-cacheable) or `commerce.product.listingGroupsCatalog()` + `buildProductListingCard()`. Use `useProductListingGroupsQuery()` when you need the full POST `/query` response shape. Avoid fetching a product list and then calling `detail()` per card.
+- **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.
 - **PDP:** prefer `useProductDetailBySlug()` / `commerce.product.detail()`. Override `staleTime` / `retry` on the hook when you need fresher catalog data or faster failure on errors.
 - **CDN-friendly reads:** server/edge code can use `detailCatalog()` and `listingGroupsCatalog()` (GET, cacheable) plus batched `stockSnapshot()` for live inventory.
 - **React Query in the browser:** default `getQueryClient()` keeps SSR data fresh forever (`staleTime: Infinity`). For client-only storefronts, use `getStorefrontQueryClient()` (~1 minute staleTime) when creating query hooks:
 
 ```ts
 import { createClient } from '@01.software/sdk'
-import { createQueryHooks, getStorefrontQueryClient } from '@01.software/sdk/query'
+import {
+  createQueryHooks,
+  getStorefrontQueryClient,
+} from '@01.software/sdk/query'
 
 const client = createClient({ publishableKey: '...' })
 const query = createQueryHooks(client, getStorefrontQueryClient())
@@ -507,11 +602,12 @@ Most consumers should use the helper APIs above (`commerce.product.detail`, etc.
 
 ### `depth` — how deep to populate relationship fields
 
-`depth` is the primary control for populating relationships like `category`, `images`, `brand`. The configured Payload default applies when unset.
+`depth` is the primary control for populating relationships like `category`, `images`, `brand`. Browser publishable-key raw collection reads are constrained to `depth: 0` with `joins: false` and no `populate`; relationship-rich storefront reads should use shaped helpers such as `commerce.product.detail()` / `listingPage()`, or a `createServerClient()` raw query when server credentials are appropriate. Browser SDK raw reads add those safe defaults automatically and reject relationship-expanded raw read options before making a request.
 
 ```typescript
 const product = await client.collections.from('products').findById(id, {
-  depth: 2, // populates product.category, product.category.parent, etc.
+  depth: 0,
+  joins: false,
 })
 ```
 
@@ -520,7 +616,7 @@ const product = await client.collections.from('products').findById(id, {
 `populate` controls which fields are returned per collection. It does NOT decide which relationships to populate — that is `depth`.
 
 ```typescript
-await client.collections.from('products').find({
+await server.collections.from('products').find({
   depth: 2,
   populate: {
     categories: { title: true, slug: true },
@@ -531,11 +627,11 @@ await client.collections.from('products').find({
 
 ### `joins` — Payload join-field reverse-relations
 
-`joins` is the correct control for Payload `type: 'join'` virtual reverse-relation fields. In this platform's public SDK schema, `products.variants`, `products.options`, `customers.orders`, `customers.addresses`, `posts.comments`, `article-authors.articles`, `orders.{items,transactions,fulfillments,returns}`, and similar reverse-relations are all join fields — you must use `joins` (not `depth`/`populate`) to control their pagination, sorting, filtering, and count. Internal backing joins such as product collection memberships are intentionally omitted from public SDK collection types.
+`joins` is the correct control for Payload `type: 'join'` virtual reverse-relation fields. In this platform's SDK schema, browser-public relations such as `products.variants`, `products.options`, and `article-authors.articles`, plus server-auth relations such as `customers.orders`, `customers.addresses`, `posts.comments`, and `orders.{items,transactions,fulfillments,returns}`, are all join fields — you must use `joins` (not `depth`/`populate`) to control their pagination, sorting, filtering, and count. Internal backing joins such as product collection memberships are intentionally omitted from SDK collection types.
 
 ```typescript
 // Canonical product detail query — variants/options are join fields on Products
-await client.collections.from('products').find({
+await server.collections.from('products').find({
   where: { slug: { equals } },
   joins: {
     variants: { limit: 50, sort: '_order' },
@@ -546,11 +642,14 @@ await client.collections.from('products').find({
 
 // Disable all join-field population for a lightweight list query
 await client.collections.from('products').find({
+  depth: 0,
   joins: false,
 })
 ```
 
-Each join field defaults to **limit 10** when `joins` is omitted. `depth` does not raise that cap — storefront PLPs that call `products.find()` with only `depth` and then `buildProductListingGroupsByOption()` can silently drop color swatches. Prefer `listingGroupsCatalog()` for PLP cards, or spread `PRODUCT_PLP_FIND_OPTIONS` for raw product queries (see [PLP join-safe queries](#product-listing-pages-plp--join-safe-queries) above).
+Each join field defaults to **limit 10** when `joins` is omitted. `depth` does not raise that cap — storefront PLPs that call `products.find()` with only `depth` and then `buildProductListingGroupsByOption()` can silently drop color swatches. Prefer `listingPage()` for PLP cards, or use `PRODUCT_PLP_FIND_OPTIONS` only in server-auth raw product queries (see [PLP join-safe queries](#product-listing-pages-plp--join-safe-queries) above).
+
+Publishable-key browser raw reads must keep `depth: 0`, `joins: false`, and omit `populate`; relationship-expanded public storefront reads belong behind shaped helpers. Use `createServerClient()` for raw `joins` queries that need server credentials.
 
 `joins` does NOT populate normal relationship fields. Keys that do not match a `type: 'join'` field on the queried collection are silently ignored — e.g. `joins: { category: {} }` on Products is a no-op because `category` is not a join field there. For normal relationships use `depth` (and optionally `populate`).
 
@@ -651,7 +750,7 @@ const { docs, totalDocs, hasNextPage } = await client.collections
     page: 1,
     sort: '-createdAt',
     where: { status: { equals: 'published' } },
-    depth: 2,
+    depth: 0,
     select: { title: true, slug: true },
   })
 
@@ -661,8 +760,8 @@ const { docs } = await client.collections.from('products').find({
   joins: false, // disable joins for lightweight list
 })
 
-// Override relationship populate
-const product = await client.collections.from('products').findById(id, {
+// Override relationship populate and join expansion (server credentials only)
+const product = await server.collections.from('products').findById(id, {
   populate: { brands: { name: true, logo: true } },
   joins: { variants: { limit: 50 } },
 })
@@ -708,7 +807,7 @@ import { extractSeo, generateMetadata } from '@01.software/sdk/metadata'
 const { docs } = await client.collections.from('products').find({
   where: { slug: { equals: 'my-product' } },
   limit: 1,
-  depth: 1,
+  depth: 0,
 })
 const metadata = docs[0]
   ? generateMetadata(extractSeo(docs[0]), { siteName: 'My Store' })
@@ -893,7 +992,7 @@ await client.customer.auth.changePassword(currentPassword, newPassword)
 
 ### Commerce Orders (ServerClient-only writes)
 
-Available on ServerClient via `server.commerce.orders.*`. Only `checkout` and `listMine` are also on Client.
+Available on ServerClient via `server.commerce.orders.*`. `checkout` and `listMine` are also on Client and return sanitized customer-facing order DTOs. Use `server.collections.from('orders')` for raw operational order documents.
 
 ```typescript
 // Orders
@@ -927,6 +1026,8 @@ await server.commerce.orders.confirmPayment({
 
 // 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
@@ -974,15 +1075,15 @@ not provide.
 documents, Payload saves product fields first; upsert receives `productId`,
 `graphRevision` (required when updating an existing product via `productId` -
 load from `GET /api/products/:id/composer-draft`), options, and variants. Do
-not send removed legacy media inputs (`optionValue.thumbnail`,
+not send removed pre-ADR-0025 media inputs (`optionValue.thumbnail`,
 `optionValue.images`, `variant.thumbnail`); use `swatch.mediaItemId` and
 variant `images[]`. Unknown keys are not part of the published upsert contract.
 
-| Payload | Valid | Invalid |
-| ------- | ----- | ------- |
-| Create | `product: { title, ... }` + graph | `productId` on create; missing `product.title` |
-| Edit graph | `productId` + `graphRevision?` + graph | `product.title` / SEO on upsert; conflicting `productId` vs `product.id` |
-| Edit (legacy) | `product: { id }` + graph only | `product: { id, title }` on edit |
+| Payload       | Valid                                  | Invalid                                                                  |
+| ------------- | -------------------------------------- | ------------------------------------------------------------------------ |
+| Create        | `product: { title, ... }` + graph      | `productId` on create; missing `product.title`                           |
+| Edit graph    | `productId` + `graphRevision?` + graph | `product.title` / SEO on upsert; conflicting `productId` vs `product.id` |
+| Edit existing | `product: { id }` + graph only         | `product: { id, title }` on edit                                         |
 
 ```typescript
 const result = await server.commerce.product.upsert({
@@ -1076,7 +1177,7 @@ for (const item of results) {
 
 ### Commerce Cart
 
-Available on both Client and ServerClient via `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.
 
 ```typescript
 // Add item to cart
@@ -1094,7 +1195,7 @@ await client.commerce.cart.updateItem({ cartItemId, quantity })
 // Remove item from cart
 await client.commerce.cart.removeItem({ cartItemId })
 
-// Other cart operations
+// 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 })
@@ -1170,7 +1271,10 @@ const customerAuthHandler = createCustomerAuthWebhookHandler({
 // Semantic order-change events keep operation as "update" for compatibility.
 // Use isOrderChangedWebhookEvent when you need to distinguish manual ordering
 // from content field edits.
-import { handleWebhook, isOrderChangedWebhookEvent } from '@01.software/sdk/webhook'
+import {
+  handleWebhook,
+  isOrderChangedWebhookEvent,
+} from '@01.software/sdk/webhook'
 
 function getWebhookSecret(): string {
   const secret = process.env.WEBHOOK_SECRET
@@ -1203,31 +1307,32 @@ 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`: 73).
+Source of truth: `packages/sdk/src/core/collection/const.ts` (`COLLECTIONS`: 53).
 
-| Category           | Collections                                                                                                                                                        |
+| Category           | Browser-public generic collections                                                                                                                                 |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Tenant             | `tenants`, `tenant-metadata`, `tenant-logos`                                                                                                                       |
-| Products           | `products`, `product-variants`, `product-options`, `product-option-values`, `product-categories`, `product-tags`, `product-collections`, `brands`, `brand-logos`   |
-| Orders             | `orders`, `order-items`, `returns`, `return-items`, `fulfillments`, `fulfillment-items`, `transactions`                                                            |
-| Customers          | `customers`, `customer-profiles`, `customer-addresses`                                                                                                             |
-| Carts              | `carts`, `cart-items`                                                                                                                                              |
+| Tenant             | `tenants`, `tenant-metadata`                                                                                                                                       |
+| Products           | `products`, `product-variants`, `product-options`, `product-option-values`, `product-categories`, `product-tags`, `product-collections`, `brands`                  |
+| Customers          | `customer-profiles`                                                                                                                                                |
 | Commerce           | `discounts`, `shipping-policies`, `shipping-zones`                                                                                                                 |
 | Content            | `documents`, `document-categories`, `document-types`, `articles`, `article-authors`, `article-categories`, `article-tags`, `links`, `link-categories`, `link-tags` |
 | Playlists / Tracks | `playlists`, `playlist-categories`, `playlist-tags`, `tracks`, `track-categories`, `track-tags`                                                                    |
 | Galleries          | `galleries`, `gallery-categories`, `gallery-tags`, `gallery-items`                                                                                                 |
 | Canvas             | `canvases`, `canvas-node-types`, `canvas-edge-types`, `canvas-categories`, `canvas-tags`, `canvas-nodes`, `canvas-edges`                                           |
-| Videos             | `videos`, `video-categories`, `video-tags`                                                                                                                         |
-| Live Streams       | `live-streams`                                                                                                                                                     |
-| Media              | `images`                                                                                                                                                           |
-| Forms              | `forms`, `form-submissions`                                                                                                                                        |
-| Community          | `posts`, `comments`, `reactions`, `reaction-types`, `bookmarks`, `post-categories`, `customer-profile-lists`                                                       |
+| Videos             | `video-categories`, `video-tags`                                                                                                                                   |
+| Forms              | `forms`                                                                                                                                                            |
+| Community          | `reaction-types`, `post-categories`, `post-tags`, `customer-profile-lists`                                                                                         |
 | Events             | `event-calendars`, `events`, `event-categories`, `event-occurrences`, `event-tags`                                                                                 |
 
-Server-only collections: `customer-groups`, `reports`, and `community-bans`
-are available from `createServerClient().collections` for segmentation and
-moderation workflows, but are intentionally absent from browser collection
-discovery.
+Server-only collections include raw media/logo records, customer and order
+operational records, raw cart/cart-item records, form submissions, raw community documents
+(`posts`, `comments`, `reactions`, `bookmarks`), live stream provider records,
+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
+where customer-facing DTOs are needed, but raw slugs are intentionally absent
+from browser collection discovery.
 
 ## Utilities
 
@@ -1362,18 +1467,18 @@ API keys created without explicit scopes use the default `['read', 'write']`. Co
 `swatch` (`type`, `color`, `mediaItemId`). Legacy public fields are removed
 from SDK input/output helpers and from listing/detail contracts.
 
-| Surface | Removed | Replacement |
-| ------- | ------- | ----------- |
-| Upsert option value | `swatchColor`, `thumbnail`, `images` | `swatch.type`, `swatch.color`, `swatch.mediaItemId` |
-| Listing groups | `optionValueSwatchColor`, `optionValueThumbnail`, `optionValueImages` | `optionValueSwatch` |
-| Product detail option value | `swatchColor`, `thumbnail`, `images` | `swatch` |
+| Surface                     | Removed                                                               | Replacement                                         |
+| --------------------------- | --------------------------------------------------------------------- | --------------------------------------------------- |
+| Upsert option value         | `swatchColor`, `thumbnail`, `images`                                  | `swatch.type`, `swatch.color`, `swatch.mediaItemId` |
+| Listing groups              | `optionValueSwatchColor`, `optionValueThumbnail`, `optionValueImages` | `optionValueSwatch`                                 |
+| Product detail option value | `swatchColor`, `thumbnail`, `images`                                  | `swatch`                                            |
 
 Migration steps:
 
 1. Replace color-only values with `swatch: { type: 'color', color: '#111111' }`.
 2. Replace thumbnail/gallery values with `swatch: { type: 'media', mediaItemId: '<product-pool-image-id>' }`.
 3. Ensure media swatches reference an image already attached to the parent product (`products.images` / `products.thumbnail`).
-4. Remove reads of legacy response fields; consume `optionValueSwatch` / `optionValue.swatch` instead.
+4. Remove reads of pre-ADR-0025 response fields; consume `optionValueSwatch` / `optionValue.swatch` instead.
 
 ## Migration Guide