@01.software/sdk 0.29.0 → 0.31.0

package/README.md

@@ -42,10 +42,10 @@ export function App() {
 ```
 
 ```typescript
-// Main entry - browser client, query builder, hooks, utilities
+// Main entry - browser client, query builder, commerce helpers, utilities
 import { createClient } from '@01.software/sdk'
 
-// Server-only entry - avoids importing browser Client APIs
+// Server-only entry - keep Secret Key code out of browser-facing imports
 import { createServerClient } from '@01.software/sdk/server'
 
 // Webhook only - webhook handlers
@@ -67,6 +67,45 @@ import { CanvasRenderer } from '@01.software/sdk/ui/canvas'
 import { VideoPlayer } from '@01.software/sdk/ui/video'
 ```
 
+The root entry keeps `createClient`, commerce helpers, collection helpers, and
+types lightweight. Server, React Query, and UI features live behind explicit
+sub-paths so consumers install feature peers only when they import the matching
+entry.
+
+| Import                              | Feature(s)                                                               | Install when used                                                                                          |
+| ----------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `@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/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/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`                                                                                       |
+| `@01.software/sdk/ui/code-block`    | `CodeBlock`, `highlight`                                                 | `react`, `react-dom`, `shiki`, `hast-util-to-jsx-runtime`                                                  |
+| `@01.software/sdk/ui/canvas`        | `CanvasRenderer`, `CanvasFrame`, `useCanvas`, `prefetchCanvas`           | `react`, `react-dom`, `@tanstack/react-query`, `@xyflow/react`, `quickjs-emscripten`, `postcss`, `sucrase` |
+| `@01.software/sdk/ui/canvas/server` | canvas server helpers                                                    | none                                                                                                       |
+| `@01.software/sdk/ui/video`         | `VideoPlayer`                                                            | `react`, `react-dom`, `@mux/mux-player-react`                                                              |
+| `@01.software/sdk/ui/image`         | `Image`                                                                  | `react`, `react-dom`                                                                                       |
+
+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`.
+
+Migration quick reference:
+
+- `createClient` remains available from `@01.software/sdk` and
+  `@01.software/sdk/client`.
+- `createServerClient` must be imported from `@01.software/sdk/server`.
+- React Query hooks and cache helpers must be imported from
+  `@01.software/sdk/query`.
+- 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
+  `@01.software/contracts`. The public SDK keeps customer-facing helpers
+  self-contained and must not import private contracts; Console code should
+  import shared helpers from contracts directly.
+
 ## Getting Started
 
 ### Client
@@ -89,11 +128,13 @@ const { docs } = await client.collections.from('products').find({
 
 ```typescript
 import { createServerClient } from '@01.software/sdk/server'
+import { createServerQueryHooks } from '@01.software/sdk/query'
 
 const server = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY,
   secretKey: process.env.SOFTWARE_SECRET_KEY, // sk01_... opaque API key from Console
 })
+const serverQuery = createServerQueryHooks(server)
 
 // Create order (server only)
 const order = await server.commerce.orders.create({
@@ -107,12 +148,29 @@ const order = await server.commerce.orders.create({
 })
 
 // SSR prefetch (server)
-await server.query.prefetchQuery({
+await serverQuery.prefetchQuery({
   collection: 'products',
   options: { limit: 10 },
 })
 ```
 
+Always import `createServerClient` from `@01.software/sdk/server` so generated
+code and bundlers do not blur the Secret Key boundary.
+
+Server-rendered preview routes can use `server.preview.detail()` with the
+short-lived preview token issued by Console:
+
+```typescript
+const preview = await server.preview.detail(
+  { collection: 'products', id: previewId },
+  { previewToken },
+)
+```
+
+For product pages, `server.commerce.product.previewDetail({ id }, {
+previewToken })` returns the same shaped product detail as `detail()`, but allows
+the saved draft/unpublished record addressed by the preview token.
+
 ## Getting product detail
 
 The recommended way to fetch a single product is the shaped helper:
@@ -124,7 +182,9 @@ const client = createClient({
   publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
 })
 
-const product = await client.commerce.product.detail({ slug: 'every-peach-tee' })
+const product = await client.commerce.product.detail({
+  slug: 'every-peach-tee',
+})
 if (!product) {
   return notFound() // returned null — product missing, unpublished, or not in this tenant
 }
@@ -133,14 +193,120 @@ if (!product) {
 
 `detail()` returns `ProductDetail | null`. A `null` result covers every "no result" reason: `not_found`, `not_published`, `tenant_mismatch`, `feature_disabled`. Render the same "not available" UI for all four. To recover the exact reason for triage, `404` maps to `null` rather than a thrown error — inspect `client.lastRequestId` and match against backend logs.
 
+### Product selection helpers
+
+```typescript
+import {
+  buildProductHref,
+  buildProductOptionMatrixFromDetail,
+  getProductSelectionImages,
+  resolveProductSelectionFromMatrix,
+} from '@01.software/sdk'
+
+const matrix = buildProductOptionMatrixFromDetail(product)
+const selection = resolveProductSelectionFromMatrix(
+  matrix,
+  { search: '?opt.color=black&opt.size=s' },
+  undefined,
+  { detail: product },
+)
+
+const images = getProductSelectionImages(selection) // object media only, deduped
+const href = buildProductHref(product, {
+  optionSlug: 'color',
+  optionValueSlug: 'black',
+})
+```
+
+Selection media follows the resolved selection: a complete variant uses that
+variant's media first; a partial option selection uses selected option-value
+media first, then matching variant media, before falling back to listing or
+product media. This keeps listing-card selection links and detail-page images
+aligned without rebuilding media priority in storefront code.
+
+`availableValuesByOptionSlug` / `availableValuesByOptionId` include
+`availableStock`, `isUnlimited`, and `availableForSale` per value so option UIs
+can render stock state without recalculating from variants.
+
 ### With React Query
 
 ```typescript
-const { data: product, isLoading } = client.query.useProductDetailBySlug(slug)
+import { createQueryHooks } from '@01.software/sdk/query'
+
+const query = createQueryHooks(client)
+const { data: product, isLoading } = query.useProductDetailBySlug(slug)
 ```
 
 Cache key is `['products', 'detail', { slug }]`. Mutations on products, product-variants, product-options, product-option-values, brands, brand-logos, images, and related collections automatically invalidate this cache.
 
+### Selection URL contract
+
+Use `createProductSelectionCodec(detail)` when product pages need to keep option
+selection in the URL. Complete selections use `variant=<variantId>`; partial
+selections use `opt.<optionId>=<valueId>`. Older
+`opt.<optionSlug>=<valueSlug>` URLs still parse during Stage 1, but slugs are
+compatibility metadata rather than canonical identity.
+
+```typescript
+import {
+  createProductSelectionCodec,
+  resolveProductSelection,
+} from '@01.software/sdk'
+
+const codec = createProductSelectionCodec(product)
+const normalizedSelection = codec.parse('?opt.option-color=color-black')
+const selection = resolveProductSelection(product, normalizedSelection)
+const selectionQuery = codec.stringify(normalizedSelection)
+// selectionQuery === 'opt.option-color=color-black' for partial selections
+// selectionQuery === 'variant=variant-black-large' once a complete variant is selected
+// selection.selectedVariant, selection.price, selection.stock, selection.media
+```
+
+Use IDs from `detail.options[].id` and `detail.options[].values[].id` when
+building selection state. Slugs remain useful for display and old inbound URLs,
+but new outbound URLs should use the codec output.
+
+For listing cards, pass the listing group returned by
+`buildProductListingGroupsByOption()` or the listing-groups endpoint into
+`buildProductHref(product, group, { detail })`. The detail object lets the SDK
+emit canonical `variant=<variantId>` or `opt.<optionId>=<valueId>` params. When
+full detail is not available on a product-list page, pass the group without
+`detail`; `buildProductHref()` still emits the best available selection hint and
+the detail page can resolve it through `resolveProductSelection()`.
+
+Do not use bare option query keys such as `?size=large`. The SDK rejects them
+as ambiguous because product pages commonly share URLs with unrelated search,
+filter, analytics, or framework parameters. Namespacing selection keys under
+`opt.` lets the codec distinguish product-option state from ordinary query
+parameters while still allowing unrelated parameters such as `utm_campaign` to
+coexist without being interpreted as selection state.
+
+### Product listing card helper
+
+`buildProductListingCard(item, options?)` turns a single
+`commerce.product.listingGroups()` response item into a render-ready
+`ProductListingCard`. The card carries product-level hero media
+(`product.thumbnail` -> first `product.images` -> `null`), an aggregated
+price range across all option-value groups, and a `swatches[]` array
+derived from groups when there is more than one. Single-group products
+emit `swatches: []`; storefronts that disagree can read `item.groups`
+directly.
+
+```ts
+import {
+  buildProductListingCard,
+  type ProductListingCard,
+} from '@01.software/sdk'
+
+const cards: ProductListingCard[] = response.docs.map((item) =>
+  buildProductListingCard(item, { basePath: '/shop' }),
+)
+```
+
+Each swatch carries a hint-only option-value href
+(`?opt.<optionId>=<valueId>`); the detail page resolves it through
+`resolveProductSelection(detail, { search })`.
+
 ## Advanced: direct Payload queries (escape hatch)
 
 Most consumers should use the helper APIs above (`commerce.product.detail`, etc.). The query builder below is the escape hatch for advanced cases the helpers do not cover: bulk operations, custom filter combinations, or fields the helper response does not expose.
@@ -171,7 +337,7 @@ 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 schema, `products.variants`, `products.options`, `products.collections`, `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.
+`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.
 
 ```typescript
 // Canonical product detail query — variants/options are join fields on Products
@@ -244,29 +410,40 @@ export default async function ProductPage({ params }) {
 ```typescript
 const client = createClient({
   publishableKey: string, // Required
+  apiUrl?: string, // Optional API origin override
 })
 
 const server = createServerClient({
   publishableKey: string,
   secretKey: string, // sk01_... or pat01_...
+  apiUrl?: string, // Optional API origin override
 })
 ```
 
-| Option           | Type     | Description                  |
-| ---------------- | -------- | ---------------------------- |
-| `publishableKey` | `string` | API publishable key          |
-| `secretKey`      | `string` | API secret key (server only) |
+| Option           | Type     | Description                                                   |
+| ---------------- | -------- | ------------------------------------------------------------- |
+| `publishableKey` | `string` | API publishable key                                           |
+| `secretKey`      | `string` | API secret key or PAT (server only)                           |
+| `apiUrl`         | `string` | Optional API origin override for staging, preview, or proxies |
+
+Use `apiUrl: string` when an SDK instance should target a non-default API
+origin.
 
-API URL은 환경변수로 오버라이드 가능합니다:
+API URL resolution order:
 
-- `SOFTWARE_API_URL` (서버용) 또는 `NEXT_PUBLIC_SOFTWARE_API_URL` (브라우저용)
-- 미설정 시: dev 빌드(`@dev` 태그)는 `api-dev.01.software`, 정식 릴리즈는 `api.01.software`
+1. Explicit `apiUrl` passed to `createClient()` or `createServerClient()`
+2. `SOFTWARE_API_URL` (server) or `NEXT_PUBLIC_SOFTWARE_API_URL` (browser)
+3. Build-time default: `DEFAULT_API_URL` when injected at build time; otherwise dev-tagged SDK builds (`-dev.` versions) use `https://api.stg.01.software`, and regular releases use `https://api.01.software`
 
 ### Query Builder
 
 Access collections via `client.collections.from(slug)`.
 
-> **Note:** `client.collections.from()` returns a `ReadOnlyQueryBuilder` (only `find`, `findById`, `count`, `findMetadata`, `findMetadataById`). Write operations (`create`, `update`, `remove`, `updateMany`, `removeMany`) are only available on `server.collections.from()`.
+> **Note:** the root `client.collections.from()` type exposes the lightweight
+> read surface (`find`, `findById`, `count`). Metadata helpers live behind the
+> optional `@01.software/sdk/metadata` entry, and write operations (`create`,
+> `update`, `remove`, `updateMany`, `removeMany`) are only available on
+> `server.collections.from()`.
 
 ```typescript
 // List query - returns PayloadFindResponse
@@ -295,11 +472,17 @@ const product = await client.collections.from('products').findById(id, {
 
 // Single item query - returns document directly
 const product = await client.collections.from('products').findById('id')
+```
+
+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.
 
+```typescript
 // Create (server only) - returns PayloadMutationResponse
 const { doc, message } = await server.collections
-  .from('products')
-  .create({ name: 'Product' })
+  .from('articles')
+  .create({ title: 'Article' })
 
 // Create with file upload (server only) - uses multipart/form-data
 const { doc } = await server.collections
@@ -308,8 +491,8 @@ const { doc } = await server.collections
 
 // Update (server only) - returns PayloadMutationResponse
 const { doc } = await server.collections
-  .from('products')
-  .update('id', { name: 'Updated' })
+  .from('articles')
+  .update('id', { title: 'Updated article' })
 
 // Update with file replacement (server only)
 await server.collections
@@ -317,28 +500,26 @@ await server.collections
   .update('id', { alt: 'New alt' }, { file: newFile })
 
 // Delete (server only) - returns document directly
-const deletedDoc = await server.collections.from('products').remove('id')
+const deletedDoc = await server.collections.from('articles').remove('id')
 
 // Count
 const { totalDocs } = await client.collections.from('products').count()
 
-// SEO Metadata (fetch + generate in one call, depth: 1 auto-applied)
-const metadata = await client.collections
-  .from('products')
-  .findMetadata(
-    { where: { slug: { equals: 'my-product' } } },
-    { siteName: 'My Store' },
-  )
+// SEO Metadata (generate from a fetched document)
+import { extractSeo, generateMetadata } from '@01.software/sdk/metadata'
 
-const metadataById = await client.collections
-  .from('products')
-  .findMetadataById('id', {
-    siteName: 'My Store',
-  })
+const { docs } = await client.collections.from('products').find({
+  where: { slug: { equals: 'my-product' } },
+  limit: 1,
+  depth: 1,
+})
+const metadata = docs[0]
+  ? generateMetadata(extractSeo(docs[0]), { siteName: 'My Store' })
+  : null
 
 // Bulk operations (server only)
-await server.collections.from('products').updateMany(where, data)
-await server.collections.from('products').removeMany(where)
+await server.collections.from('articles').updateMany(where, data)
+await server.collections.from('articles').removeMany(where)
 ```
 
 ### API Response Types (Payload Native)
@@ -370,95 +551,112 @@ interface PayloadMutationResponse<T> {
 // findById() / remove() returns T (document directly)
 ```
 
-| Operation            | Response Type                                                      |
-| -------------------- | ------------------------------------------------------------------ |
-| `find()`             | `PayloadFindResponse<T>` - `{ docs, totalDocs, hasNextPage, ... }` |
-| `findById()`         | `T` - document object directly                                     |
-| `create()`           | `PayloadMutationResponse<T>` - `{ doc, message }`                  |
-| `update()`           | `PayloadMutationResponse<T>` - `{ doc, message }`                  |
-| `remove()`           | `T` - deleted document object directly                             |
-| `count()`            | `{ totalDocs: number }`                                            |
-| `findMetadata()`     | `Metadata \| null` - Next.js Metadata (null if no match)           |
-| `findMetadataById()` | `Metadata` - Next.js Metadata (throws on 404)                      |
+| Operation    | Response Type                                                      |
+| ------------ | ------------------------------------------------------------------ |
+| `find()`     | `PayloadFindResponse<T>` - `{ docs, totalDocs, hasNextPage, ... }` |
+| `findById()` | `T` - document object directly                                     |
+| `create()`   | `PayloadMutationResponse<T>` - `{ doc, message }`                  |
+| `update()`   | `PayloadMutationResponse<T>` - `{ doc, message }`                  |
+| `remove()`   | `T` - deleted document object directly                             |
+| `count()`    | `{ totalDocs: number }`                                            |
 
 ### React Query Hooks
 
-Read hooks are available on both `Client` and `ServerClient` via `client.query.*`. Mutation hooks (`useCreate`, `useUpdate`, `useRemove`) are only available on `ServerClient`.
+React Query helpers are opt-in through `@01.software/sdk/query`. Install
+`@tanstack/react-query` (and React peers) only when your app imports this
+sub-path. Browser components should use `createQueryHooks(client)` for
+browser-safe reads and customer auth hooks. Collection writes belong in trusted
+server code via `createServerClient`.
 
 ```typescript
+import { createQueryHooks } from '@01.software/sdk/query'
+
+const query = createQueryHooks(client)
+
 // List query
-const { data, isLoading } = client.query.useQuery({
+const { data, isLoading } = query.useQuery({
   collection: 'products',
   options: { limit: 10 },
 })
 
 // Suspense mode
-const { data } = client.query.useSuspenseQuery({
+const { data } = query.useSuspenseQuery({
   collection: 'products',
   options: { limit: 10 },
 })
 
 // Query by ID
-const { data } = client.query.useQueryById({
+const { data } = query.useQueryById({
   collection: 'products',
   id: 'product_id',
 })
 
 // Infinite scroll
-const { data, fetchNextPage, hasNextPage } = client.query.useInfiniteQuery({
+const { data, fetchNextPage, hasNextPage } = query.useInfiniteQuery({
   collection: 'products',
   options: { limit: 20 },
 })
 
-// Mutation hooks — ServerClient only (auto-invalidate cache on success)
-const { mutate: create } = client.query.useCreate({ collection: 'images' })
-const { mutate: update } = client.query.useUpdate({ collection: 'products' })
-const { mutate: remove } = client.query.useRemove({ collection: 'products' })
-
-create({ data: { alt: 'Hero' }, file: imageFile, filename: 'hero.jpg' })
-update({ id: 'product_id', data: { title: 'Updated' } })
-remove('product_id')
-
 // SSR Prefetch
-await client.query.prefetchQuery({
+await query.prefetchQuery({
   collection: 'products',
   options: { limit: 10 },
 })
-await client.query.prefetchQueryById({
+await query.prefetchQueryById({
   collection: 'products',
   id: 'product_id',
 })
-await client.query.prefetchInfiniteQuery({
+await query.prefetchInfiniteQuery({
   collection: 'products',
   pageSize: 20,
 })
 
 // Cache utilities
-client.query.invalidateQueries('products')
-client.query.getQueryData('products', 'list', options)
-client.query.setQueryData('products', 'detail', id, data)
+query.invalidateQueries('products')
+query.getQueryData('products', 'list', options)
+query.setQueryData('products', 'detail', id, data)
 
 // Customer auth hooks (Client only)
-const { data: profile } = client.query.useCustomerMe()
-const { mutate: login } = client.query.useCustomerLogin()
-const { mutate: register } = client.query.useCustomerRegister()
-const { mutate: logout } = client.query.useCustomerLogout()
+const { data: profile } = query.useCustomerMe()
+const { mutate: login } = query.useCustomerLogin()
+const { mutate: register } = query.useCustomerRegister()
+const { mutate: logout } = query.useCustomerLogout()
 
 login({ email: 'user@example.com', password: 'password' })
 
 // Other customer mutations
-client.query.useCustomerForgotPassword()
-client.query.useCustomerResetPassword()
-client.query.useCustomerChangePassword()
+query.useCustomerForgotPassword()
+query.useCustomerResetPassword()
+query.useCustomerChangePassword()
 
 // Customer cache utilities
-client.query.invalidateCustomerQueries()
-client.query.getCustomerData()
-client.query.setCustomerData(profile)
+query.invalidateCustomerQueries()
+query.getCustomerData()
+query.setCustomerData(profile)
+```
+
+```typescript
+// Server action / API route for collection writes
+import { createServerClient } from '@01.software/sdk/server'
+
+const server = createServerClient({
+  publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
+  secretKey: process.env.SOFTWARE_SECRET_KEY!,
+})
+
+await server.collections.from('articles').update('article_id', {
+  title: 'Updated article',
+})
 ```
 
 ### 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.
+
 Available on Client via `client.customer.auth.*`.
 
 ```typescript
@@ -548,7 +746,63 @@ await client.commerce.shipping.calculate({ shippingPolicyId?, orderAmount, posta
 
 ### Commerce Product
 
-Available on both Client and ServerClient via `commerce.product.*`.
+Product reads are available on both Client and ServerClient via `commerce.product.*`.
+Product catalog writes are ServerClient-only.
+Use `server.commerce.product.upsert()` for product catalog writes that include
+options, option values, and variants. It is the tenant-admin safe path because
+it applies the product/option/variant transaction that raw collection writes do
+not provide.
+
+```typescript
+const result = await server.commerce.product.upsert({
+  product: {
+    title: 'Every Peach Tee',
+    slug: 'every-peach-tee',
+    status: 'published',
+  },
+  options: [
+    {
+      title: 'Color',
+      slug: 'color',
+      values: [
+        { value: 'Black', slug: 'black', swatchColor: '#111111' },
+        { value: 'White', slug: 'white', swatchColor: '#ffffff' },
+      ],
+    },
+    {
+      title: 'Size',
+      slug: 'size',
+      values: [
+        { value: 'Small', slug: 's' },
+        { value: 'Medium', slug: 'm' },
+      ],
+    },
+  ],
+  variants: [
+    {
+      optionValues: { color: { valueSlug: 'black' }, size: { valueSlug: 's' } },
+      sku: 'TEE-BLK-S',
+      price: 29000,
+      stock: 10,
+      isActive: true,
+    },
+    {
+      optionValues: { color: { valueSlug: 'white' }, size: { valueSlug: 'm' } },
+      sku: 'TEE-WHT-M',
+      price: 29000,
+      stock: 8,
+      isActive: true,
+    },
+  ],
+})
+
+if (!result.ok) {
+  throw new Error(result.message)
+}
+```
+
+For updates to existing options or option-values, prefer `id` / `valueId` when
+available so rename-safe updates do not depend on slugs.
 
 ```typescript
 // Batch stock check (point-in-time read, NOT a reservation)
@@ -643,9 +897,9 @@ Source of truth: `packages/sdk/src/core/collection/const.ts` (`COLLECTIONS`: 73)
 | 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-profile-lists`, `customer-addresses`                                                                                   |
+| Customers          | `customers`, `customer-profiles`, `customer-addresses`                                                                                                             |
 | Carts              | `carts`, `cart-items`                                                                                                                                              |
-| Commerce           | `discounts`, `shipping-policies`                                                                                                                                   |
+| 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`                                                                                                 |
@@ -654,7 +908,7 @@ Source of truth: `packages/sdk/src/core/collection/const.ts` (`COLLECTIONS`: 73)
 | Live Streams       | `live-streams`                                                                                                                                                     |
 | Media              | `images`                                                                                                                                                           |
 | Forms              | `forms`, `form-submissions`                                                                                                                                        |
-| Community          | `posts`, `comments`, `reactions`, `reaction-types`, `bookmarks`, `post-categories`                                                                                  |
+| Community          | `posts`, `comments`, `reactions`, `reaction-types`, `bookmarks`, `post-categories`, `customer-profile-lists`                                                       |
 | Events             | `event-calendars`, `events`, `event-categories`, `event-occurrences`, `event-tags`                                                                                 |
 
 Server-only collections: `customer-groups`, `reports`, and `community-bans`

package/dist/analytics/react.cjs

@@ -28,7 +28,10 @@ module.exports = __toCommonJS(react_exports);
 var import_react = require("react");
 
 // src/core/client/types.ts
-function resolveApiUrl() {
+function resolveApiUrl(apiUrl) {
+  if (apiUrl) {
+    return apiUrl.replace(/\/$/, "");
+  }
   if (typeof process !== "undefined" && process.env) {
     const envUrl = process.env.SOFTWARE_API_URL || process.env.NEXT_PUBLIC_SOFTWARE_API_URL;
     if (envUrl) {