@01.software/sdk 0.30.1 → 0.31.0

package/README.md

@@ -42,7 +42,7 @@ 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 - keep Secret Key code out of browser-facing imports
@@ -72,21 +72,21 @@ 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` |
+| 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
@@ -157,6 +157,20 @@ await serverQuery.prefetchQuery({
 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:
@@ -204,6 +218,12 @@ const href = buildProductHref(product, {
 })
 ```
 
+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.
@@ -246,6 +266,14 @@ 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
@@ -253,6 +281,32 @@ filter, analytics, or framework parameters. Namespacing selection keys under
 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.
@@ -283,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
@@ -843,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`                                                                                                 |
@@ -854,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/client.cjs

@@ -72,8 +72,16 @@ var ValidationError = class extends SDKError {
   }
 };
 var ApiError = class extends SDKError {
-  constructor(message, status, details, userMessage, suggestion) {
-    super("API_ERROR", message, status, details, userMessage, suggestion);
+  constructor(message, status, details, userMessage, suggestion, requestId) {
+    super(
+      "API_ERROR",
+      message,
+      status,
+      details,
+      userMessage,
+      suggestion,
+      requestId
+    );
     this.name = "ApiError";
   }
 };
@@ -104,19 +112,43 @@ var UsageLimitError = class extends SDKError {
 };
 var AuthError = class extends SDKError {
   constructor(message, details, userMessage, suggestion, requestId) {
-    super("auth_error", message, 401, details, userMessage, suggestion, requestId);
+    super(
+      "auth_error",
+      message,
+      401,
+      details,
+      userMessage,
+      suggestion,
+      requestId
+    );
     this.name = "AuthError";
   }
 };
 var PermissionError = class extends SDKError {
   constructor(message, details, userMessage, suggestion, requestId) {
-    super("permission_error", message, 403, details, userMessage, suggestion, requestId);
+    super(
+      "permission_error",
+      message,
+      403,
+      details,
+      userMessage,
+      suggestion,
+      requestId
+    );
     this.name = "PermissionError";
   }
 };
 var NotFoundError = class extends SDKError {
   constructor(message, details, userMessage, suggestion, requestId) {
-    super("not_found", message, 404, details, userMessage, suggestion, requestId);
+    super(
+      "not_found",
+      message,
+      404,
+      details,
+      userMessage,
+      suggestion,
+      requestId
+    );
     this.name = "NotFoundError";
   }
 };
@@ -128,14 +160,22 @@ var ConflictError = class extends SDKError {
 };
 var RateLimitError = class extends SDKError {
   constructor(message, retryAfter, details, userMessage, suggestion, requestId) {
-    super("rate_limit_exceeded", message, 429, details, userMessage, suggestion, requestId);
+    super(
+      "rate_limit_exceeded",
+      message,
+      429,
+      details,
+      userMessage,
+      suggestion,
+      requestId
+    );
     this.name = "RateLimitError";
     this.retryAfter = retryAfter;
   }
 };
 var createNetworkError = (message, status, details, userMessage, suggestion) => new NetworkError(message, status, details, userMessage, suggestion);
 var createValidationError = (message, details, userMessage, suggestion, status) => new ValidationError(message, details, userMessage, suggestion, status);
-var createApiError = (message, status, details, userMessage, suggestion) => new ApiError(message, status, details, userMessage, suggestion);
+var createApiError = (message, status, details, userMessage, suggestion, requestId) => new ApiError(message, status, details, userMessage, suggestion, requestId);
 var createConfigError = (message, details, userMessage, suggestion) => new ConfigError(message, details, userMessage, suggestion);
 var createTimeoutError = (message, details, userMessage, suggestion) => new TimeoutError(message, details, userMessage, suggestion);
 var createUsageLimitError = (message, usage, details, userMessage, suggestion) => new UsageLimitError(message, usage, details, userMessage, suggestion);
@@ -143,7 +183,14 @@ var createAuthError = (message, details, userMessage, suggestion, requestId) =>
 var createPermissionError = (message, details, userMessage, suggestion, requestId) => new PermissionError(message, details, userMessage, suggestion, requestId);
 var createNotFoundError = (message, details, userMessage, suggestion, requestId) => new NotFoundError(message, details, userMessage, suggestion, requestId);
 var createConflictError = (message, details, userMessage, suggestion, requestId) => new ConflictError(message, details, userMessage, suggestion, requestId);
-var createRateLimitError = (message, retryAfter, details, userMessage, suggestion, requestId) => new RateLimitError(message, retryAfter, details, userMessage, suggestion, requestId);
+var createRateLimitError = (message, retryAfter, details, userMessage, suggestion, requestId) => new RateLimitError(
+  message,
+  retryAfter,
+  details,
+  userMessage,
+  suggestion,
+  requestId
+);
 
 // src/core/internal/utils/credentials.ts
 function requirePublishableKeyForSecret(apiName, publishableKey, secretKey) {
@@ -183,6 +230,22 @@ function debugLog(debug, type, message, data) {
     console.groupEnd();
   }
 }
+function redactSensitiveHeader(value) {
+  const prefix = value.toLowerCase().startsWith("bearer ") ? "Bearer " : "";
+  return value.length > 20 ? `${prefix}...****${value.slice(-8)}` : "****";
+}
+function redactSensitiveHeaders(headers) {
+  const redacted = Object.fromEntries(headers.entries());
+  if (redacted.authorization) {
+    redacted.authorization = redactSensitiveHeader(redacted.authorization);
+  }
+  if (redacted["x-preview-token"]) {
+    redacted["x-preview-token"] = redactSensitiveHeader(
+      redacted["x-preview-token"]
+    );
+  }
+  return redacted;
+}
 function getErrorSuggestion(status) {
   if (status === 400)
     return "The request data failed validation. Check field values and types.";
@@ -257,6 +320,12 @@ async function parseErrorBody(response) {
     return fallback;
   }
 }
+function getParsedErrorSuggestion(status, parsed) {
+  if (status === 403 && parsed.reason === "origin_not_allowed") {
+    return "Add the request origin to the tenant Browser API origins, then retry the browser request.";
+  }
+  return getErrorSuggestion(status);
+}
 async function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -270,7 +339,7 @@ function createHttpStatusError(status, parsed, details, requestId) {
     ...parsed.errors && { errors: parsed.errors },
     ...parsed.body && { body: parsed.body }
   };
-  const suggestion = getErrorSuggestion(status);
+  const suggestion = getParsedErrorSuggestion(status, parsed);
   if (status === 400 || status === 422) {
     return attachRequestId(
       createValidationError(
@@ -376,11 +445,7 @@ async function httpFetch(url, options) {
       if (!headers.has("Content-Type") && requestInit.body && !(requestInit.body instanceof FormData)) {
         headers.set("Content-Type", "application/json");
       }
-      const redactedHeaders = Object.fromEntries(headers.entries());
-      if (redactedHeaders["authorization"]) {
-        const token = redactedHeaders["authorization"];
-        redactedHeaders["authorization"] = token.length > 20 ? `Bearer ...****${token.slice(-8)}` : "****";
-      }
+      const redactedHeaders = redactSensitiveHeaders(headers);
       debugLog(debug, "request", url, {
         method: requestInit.method || "GET",
         headers: redactedHeaders,
@@ -398,7 +463,7 @@ async function httpFetch(url, options) {
       debugLog(debug, "response", url, {
         status: response.status,
         statusText: response.statusText,
-        headers: Object.fromEntries(response.headers.entries())
+        headers: redactSensitiveHeaders(response.headers)
       });
       if (!response.ok) {
         if (isUsageLimitExceededResponse(response)) {
@@ -831,7 +896,7 @@ async function parseApiResponse(response, endpoint) {
     if (reason === "validation_failed") {
       throw attachRequestId(createValidationError(errorMessage, data, errorMessage), requestId);
     }
-    if (reason === "token_expired" || reason === "token_invalid" || reason === "key_invalid" || reason === "key_revoked") {
+    if (reason === "token_expired" || reason === "token_invalid" || reason === "preview_token_invalid" || reason === "preview_token_required" || reason === "key_invalid" || reason === "key_revoked") {
       throw attachRequestId(createAuthError(errorMessage, data, errorMessage), requestId);
     }
     if (reason === "forbidden") {