@01.software/sdk 0.29.0 → 0.30.1

package/README.md

@@ -45,7 +45,7 @@ export function App() {
 // Main entry - browser client, query builder, hooks, 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 and commerce 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,15 @@ 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.
+
 ## Getting product detail
 
 The recommended way to fetch a single product is the shaped helper:
@@ -124,7 +168,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 +179,80 @@ 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',
+})
+```
+
+`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.
+
+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.
+
 ## 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.
@@ -244,29 +356,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 +418,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 +437,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 +446,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 +497,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 +692,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)
@@ -654,7 +854,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`                                                                                 |
 | 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) {