@01.software/sdk 0.39.0 → 0.41.0

package/README.md

@@ -126,7 +126,7 @@ const client = createClient({
 // Query data (returns Payload native response)
 const { docs } = await client.collections.from('products').find({
   limit: 10,
-  where: { status: { equals: 'published' } },
+  select: { title: true, slug: true },
 })
 ```
 
@@ -264,7 +264,8 @@ if (!result.found) {
 }
 
 const { product } = result
-// product: { product, variants, options, brand, categories, tags, images, videos, listing }
+// product: { product, variants, options, brand, categories, tags, images, videos,
+//   featuredImage, priceRange, compareAtPriceRange, availableForSale, selectedOrFirstAvailableVariant }
 ```
 
 `detail()` returns `ProductDetailResult`, a discriminated union:
@@ -276,6 +277,15 @@ mismatches, still throw
 typed `SDKError` subclasses and preserve request IDs through the existing
 `lastRequestId` / `onRequestId` path.
 
+Public product visibility has two axes. Lifecycle `status` must still be
+`published` and `publishedAt` must be current or empty. Then
+`storefrontVisibility` decides storefront exposure: `listed` products appear in
+listing helpers and direct detail, `unlisted` products are omitted from listing
+helpers but can be fetched by direct detail slug/id, and `hidden` products return
+`{ found: false, reason: 'not_published' }` from detail and are omitted from
+listings. Legacy products without `storefrontVisibility` are treated as
+`listed`.
+
 The successful product payload exposes inventory rollups without sentinel
 values: `product.totalInventory` is the tracked stock sum across non-unlimited
 variants, `null` when no variants are tracked, and
@@ -353,7 +363,10 @@ 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,
+  projectProductToListingShape,
+} from '@01.software/sdk'
 import { createServerClient } from '@01.software/sdk/server'
 
 const server = createServerClient({
@@ -362,11 +375,32 @@ const server = createServerClient({
   secretKey: process.env.SOFTWARE_SECRET_KEY!,
 })
 
+const now = new Date().toISOString()
 const { docs } = await server.collections.from('products').find({
   ...PRODUCT_PLP_FIND_OPTIONS,
-  where: { status: { equals: 'published' } },
+  where: {
+    and: [
+      { status: { equals: 'published' } },
+      {
+        or: [
+          { publishedAt: { less_than_equal: now } },
+          { publishedAt: { exists: false } },
+          { publishedAt: { equals: null } },
+        ],
+      },
+      {
+        or: [
+          { storefrontVisibility: { equals: 'listed' } },
+          { storefrontVisibility: { exists: false } },
+          { storefrontVisibility: { equals: null } },
+        ],
+      },
+    ],
+  },
   limit: 24,
 })
+
+const listingProducts = docs.map(projectProductToListingShape)
 ```
 
 `PRODUCT_PLP_FIND_OPTIONS` sets `joins.variants` and `joins.options` to safe
@@ -465,11 +499,11 @@ const selectionQuery = codec.stringify(normalizedSelection)
 #### Empty vs partial selection
 
 When selection input is omitted, `resolveProductSelection()` applies
-`listing.selectionHintVariant` so PDP defaults match listing cards. That is
+`selectedOrFirstAvailableVariant` so PDP defaults match listing cards. That is
 separate from `fillDefaults` and is not gated by a flag.
 
 ```typescript
-// PDP default (uses listing.selectionHintVariant when selection is omitted)
+// PDP default (uses selectedOrFirstAvailableVariant when selection is omitted)
 resolveProductSelection(product)
 
 // Catalog: keep price range / no concrete variant
@@ -489,7 +523,7 @@ const resolution = resolveProductSelection(
   },
 )
 // resolution.selectedVariant is concrete; unselected options are filled
-// using the same available-by-order rules as listing selectionHintVariant.
+// using the same available-by-order rule that derives selectedOrFirstAvailableVariant.
 ```
 
 For option-click handlers, use `selectNext()` to apply a slug transition,
@@ -548,16 +582,19 @@ inspect grouped variant fields without a follow-up fetch. The by-ids response
 also returns `missing: string[]` for requested product IDs that were not found,
 not published, or not accessible; `docs` preserve the input `productIds` order
 for returned products. The helper populates optional `representativeVariant`, a
-PDP-seeded `href`, representative media (`product.thumbnail` -> first
-`product.images` -> representative variant media -> `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.
+PDP-seeded `href`, representative media from Shopify-shaped
+`product.featuredImage` with product gallery fallback, Product-level
+`priceRange` / `compareAtPriceRange`, Product-level `availableForSale`, 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.
 
 `buildProductListingCard()` derives card swatches from listing-group
 `optionValueSwatch`. Image swatches use `swatch.mediaItemId`; color swatches use
 `swatch.color`. Option-value thumbnail/gallery fields are no longer part of the
-public listing-group or product-detail contract.
+public listing-group or product-detail contract. New PLP filters and sorts
+should use Product-shaped names such as `priceRange.minVariantPrice.amount`,
+`priceRange.maxVariantPrice.amount`, and `availableForSale`.
 
 ```ts
 import {
@@ -669,7 +706,7 @@ Dotted-path filters (`where: { 'product.slug': { equals } }`) are Payload-native
 
 Checklist when `find()` returns `docs: []` unexpectedly, in order of likelihood:
 
-1. **Access control filtered the document.** Many collections enforce status/published filters on public read (e.g. `composedReadStatusPublished` on `products` restricts unauthenticated reads to `status: 'published'`). A draft or unpublished document silently disappears from results even when its slug matches. Correlate with backend logs via `client.lastRequestId` (or catch `SDKError.requestId`).
+1. **Access control filtered the document.** Many collections enforce public read filters. Products require `status: 'published'`, a current or unset `publishedAt`, and listable storefront visibility (`listed`, legacy missing, or `null`) for publishable-key raw listing reads. Draft, future, `unlisted`, `hidden`, or malformed products silently disappear from raw listing results even when their slug or ID matches. Use the shaped product detail helper for direct-link `unlisted` products. Correlate with backend logs via `client.lastRequestId` (or catch `SDKError.requestId`).
 2. **Build-time publishable key / API URL differs from runtime.** SSG `generateStaticParams` / `generateMetadata` / the page render must all see the same tenant context. A wrong or missing key at build time produces a baked-in empty response.
 3. **Next.js SSG fetch cache served a stale empty response.** Use `cache: 'no-store'` or `export const revalidate = 0` on server components that should reflect live data.
 4. **`where: { slug: 'x' }` string shorthand.** Always use `{ slug: { equals: 'x' } }` — bare strings silently match nothing.
@@ -749,7 +786,6 @@ const { docs, totalDocs, hasNextPage } = await client.collections
     limit: 20,
     page: 1,
     sort: '-createdAt',
-    where: { status: { equals: 'published' } },
     depth: 0,
     select: { title: true, slug: true },
   })
@@ -981,7 +1017,7 @@ client.customer.auth.logout()
 const orders = await client.commerce.orders.listMine({
   page: 1,
   limit: 10,
-  status: 'paid',
+  displayFinancialStatus: 'paid',
 })
 
 // Password
@@ -992,7 +1028,7 @@ await client.customer.auth.changePassword(currentPassword, newPassword)
 
 ### Commerce Orders (ServerClient-only writes)
 
-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.
+Available on ServerClient via `server.commerce.orders.*`. `checkout` and `listMine` are also on Client and return sanitized customer-facing order DTOs. Customer order DTOs expose the independent status axes (`displayFinancialStatus`, `displayFulfillmentStatus`, `returnStatus`, `primaryDisplayStatus`, `returnDisplayStatus`); `status` and `displayStatus` are read-only compatibility aliases for older clients. Use `server.collections.from('orders')` for raw operational order documents.
 
 ```typescript
 // Orders
@@ -1307,7 +1343,7 @@ 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`: 53).
+Source of truth: `packages/sdk/src/core/collection/const.ts` (`COLLECTIONS`: 51).
 
 | Category           | Browser-public generic collections                                                                                                                                 |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -1318,7 +1354,7 @@ Source of truth: `packages/sdk/src/core/collection/const.ts` (`COLLECTIONS`: 53)
 | 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`                                           |
+| Canvas             | `canvases`, `canvas-node-types`, `canvas-edge-types`, `canvas-categories`, `canvas-tags`                                                                           |
 | Videos             | `video-categories`, `video-tags`                                                                                                                                   |
 | Forms              | `forms`                                                                                                                                                            |
 | Community          | `reaction-types`, `post-categories`, `post-tags`, `customer-profile-lists`                                                                                         |
@@ -1327,7 +1363,8 @@ Source of truth: `packages/sdk/src/core/collection/const.ts` (`COLLECTIONS`: 53)
 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
+Canvas graph shell rows (`canvas-nodes`, `canvas-edges`), 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
@@ -1455,6 +1492,12 @@ API keys created without explicit scopes use the default `['read', 'write']`. Co
 
 ## Changelog
 
+> The complete, up-to-date release history (including 0.35.0+) lives in
+> [`CHANGELOG.md`](./CHANGELOG.md), and breaking-change migration steps live in
+> [`MIGRATION.md`](./MIGRATION.md). Both ship with the published package. The
+> selected entries below are kept inline for historically significant breaking
+> changes.
+
 ### v0.23.0 (Product option-value visuals)
 
 - Added reusable option-value visuals (nested `swatch`, `thumbnail`, `images`) to Payload types and ecommerce utility shapes.
@@ -1477,7 +1520,7 @@ 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`).
+3. Ensure media swatches reference an image already attached to the parent product (`products.images`).
 4. Remove reads of pre-ADR-0025 response fields; consume `optionValueSwatch` / `optionValue.swatch` instead.
 
 ## Migration Guide

package/dist/client.cjs

@@ -1479,6 +1479,19 @@ var CustomerAuth = class {
     const params = new URLSearchParams();
     if (options?.page) params.set("page", String(options.page));
     if (options?.limit) params.set("limit", String(options.limit));
+    if (options?.displayFinancialStatus) {
+      params.set("displayFinancialStatus", options.displayFinancialStatus);
+    }
+    if (options?.displayFulfillmentStatus) {
+      params.set("displayFulfillmentStatus", options.displayFulfillmentStatus);
+    }
+    if (options?.returnStatus) params.set("returnStatus", options.returnStatus);
+    if (options?.primaryDisplayStatus) {
+      params.set("primaryDisplayStatus", options.primaryDisplayStatus);
+    }
+    if (options?.returnDisplayStatus) {
+      params.set("returnDisplayStatus", options.returnDisplayStatus);
+    }
     if (options?.status) params.set("status", options.status);
     const qs = params.toString();
     return this.requestJson(`/api/customers/me/orders${qs ? `?${qs}` : ""}`, {
@@ -1593,9 +1606,6 @@ function getMediaId(value) {
   }
   return null;
 }
-function toPointerId(value) {
-  return getMediaId(value);
-}
 function mediaArray(value) {
   if (!Array.isArray(value)) return [];
   return value.filter((entry) => entry != null);
@@ -1712,22 +1722,16 @@ function resolveProductSelectionMedia(input) {
     source: "none"
   };
 }
-function resolveListingPrimaryImagePointer(input) {
+function resolveFeaturedImagePointer(input) {
   const pool = mediaArray(input.productMediaPool);
   const resolvedPointer = getMediaId(input.resolvedPrimary);
   if (resolvedPointer && input.resolvedSource !== "product_pool" && input.resolvedSource !== "none") {
     return resolvedPointer;
   }
   const poolById = buildPoolById(pool);
-  const listingPointer = getMediaId(input.listingPrimaryImage);
-  if (listingPointer && poolById.has(listingPointer)) {
-    return listingPointer;
-  }
-  const primaryPointer = toPointerId(input.productPrimaryMediaItemId);
-  if (primaryPointer && poolById.has(primaryPointer)) return primaryPointer;
-  const thumbnailPointer = getMediaId(input.productThumbnail);
-  if (thumbnailPointer && poolById.has(thumbnailPointer)) {
-    return thumbnailPointer;
+  const featuredImagePointer = getMediaId(input.featuredImage);
+  if (featuredImagePointer && poolById.has(featuredImagePointer)) {
+    return featuredImagePointer;
   }
   if (pool.length > 0) {
     const firstPoolId = getMediaId(pool[0]);
@@ -1782,13 +1786,9 @@ function extractEntityId(value) {
   return null;
 }
 function resolveGenericListingPrimaryImage(product, resolvedPrimary, resolvedSource) {
-  return resolveListingPrimaryImagePointer({
+  return resolveFeaturedImagePointer({
     productMediaPool: product?.images ?? [],
-    productPrimaryMediaItemId: getRelationID(
-      product?.primaryMediaItemId ?? null
-    ),
-    productThumbnail: product?.thumbnail ?? null,
-    listingPrimaryImage: product?.listing?.primaryImage ?? null,
+    featuredImage: product?.featuredImage ?? null,
     resolvedPrimary,
     resolvedSource
   });
@@ -2390,11 +2390,14 @@ function compareVariantOrder(a, b) {
   const bId = String(getRelationID(b.id) ?? "");
   return aId.localeCompare(bId);
 }
-function isVariantAvailableForSale(variant) {
+function getVariantAvailableForSale(variant) {
   if (variant.isActive === false) return false;
   if (variant.isUnlimited) return true;
   return (variant.stock ?? 0) - (variant.reservedStock ?? 0) > 0;
 }
+function isVariantAvailableForSale(variant) {
+  return getVariantAvailableForSale(variant);
+}
 function sortVariantsForMediaSelection(variants) {
   const orderedVariants = [...variants].sort(compareVariantOrder);
   const activeVariants = orderedVariants.filter(
@@ -2427,7 +2430,7 @@ function getMinMax(values) {
     max: Math.max(...numbers)
   };
 }
-function buildProductListingProjection(product, variants) {
+function buildProductListingGroupProjection(product, variants) {
   const orderedVariants = [...variants].sort(compareVariantOrder);
   const activeVariants = orderedVariants.filter(
     (variant) => variant.isActive !== false
@@ -2448,7 +2451,6 @@ function buildProductListingProjection(product, variants) {
   const mediaSelectionVariants = sortVariantsForMediaSelection(variants);
   const resolvedProductMedia = resolveProductSelectionMedia({
     productMediaPool,
-    productPrimaryMediaItemId: getRelationID(product?.primaryMediaItemId),
     selectedVariant: selectionHintVariant && selectionHintHasPoolMedia ? {
       id: selectionHintVariant.id,
       images: selectionHintVariant.images
@@ -2474,47 +2476,22 @@ function buildProductListingCard(item, options = {}) {
   const product = item.product;
   const groups = item.groups;
   const variants = getProductListingCardVariants(item);
-  const projectedListing = buildProductListingProjection(product, variants);
-  const selectionHintVariant = getRelationID(
-    product.listing && "selectionHintVariant" in product.listing ? product.listing.selectionHintVariant : null
-  ) ?? projectedListing.selectionHintVariant;
+  const projectedListing = buildProductListingGroupProjection(product, variants);
+  const selectionHintVariant = getRelationID(product.selectedOrFirstAvailableVariant) ?? projectedListing.selectionHintVariant;
   const representativeVariant = findListingCardRepresentativeVariant(
     variants,
     selectionHintVariant
   );
   const productMediaPool = mediaArray2(product.images);
-  const representativeHasPoolMedia = Boolean(
-    representativeVariant?.images?.some(
-      (image) => productMediaPool.some(
-        (poolItem) => getRelationID(poolItem) === getRelationID(image)
-      )
-    )
-  );
-  const resolvedPrimaryMedia = resolveProductSelectionMedia(
-    {
-      productMediaPool,
-      productPrimaryMediaItemId: getRelationID(product.primaryMediaItemId),
-      selectedVariant: representativeHasPoolMedia ? representativeVariant : null,
-      matchingVariants: representativeHasPoolMedia ? [] : variants
-    }
-  );
-  const listingPrimaryPointer = resolveListingPrimaryImagePointer({
-    productMediaPool,
-    productPrimaryMediaItemId: getRelationID(product.primaryMediaItemId),
-    productThumbnail: product.thumbnail ?? null,
-    listingPrimaryImage: product.listing?.primaryImage ?? null,
-    resolvedPrimary: resolvedPrimaryMedia.primaryImage,
-    resolvedSource: resolvedPrimaryMedia.source
-  });
-  const listingPrimaryMedia = listingPrimaryPointer ? productMediaPool.find(
-    (item2) => getRelationID(item2) === listingPrimaryPointer
-  ) ?? resolvedPrimaryMedia.primaryImage ?? null : null;
+  const featuredImageId = getRelationID(product.featuredImage);
+  const featuredImageFromPool = featuredImageId ? productMediaPool.find((item2) => getRelationID(item2) === featuredImageId) : void 0;
+  const listingPrimaryMedia = featuredImageFromPool ?? product.featuredImage ?? productMediaPool[0] ?? null;
   const priceRange = resolveListingCardPriceRange(
     product,
     projectedListing,
     groups
   );
-  const availableForSale = product.listing?.availableForSale != null ? product.listing.availableForSale : groups.length > 0 ? groups.some((group) => group.listing.availableForSale) : projectedListing.availableForSale;
+  const availableForSale = product.availableForSale != null ? product.availableForSale : groups.length > 0 ? groups.some((group) => group.listing.availableForSale) : projectedListing.availableForSale;
   const swatches = groups.length > 1 ? groups.map((group) => buildListingSwatch(product, group, options)) : [];
   return {
     id: String(product.id),
@@ -2554,23 +2531,20 @@ function findListingCardRepresentativeVariant(variants, representativeVariantId)
     (variant) => getRelationID(variant.id) === representativeVariantId
   ) ?? null;
 }
-function hasCompleteListingPriceProjection(listing) {
-  return listing?.minPrice != null && listing?.maxPrice != null;
-}
-function listingDefinesCompareAtProjection(listing) {
-  return "minCompareAtPrice" in listing || "maxCompareAtPrice" in listing;
+function hasCompleteProductPriceRange(priceRange) {
+  return priceRange?.minVariantPrice?.amount != null && priceRange?.maxVariantPrice?.amount != null;
 }
 function resolveListingCardPriceRange(product, projectedListing, groups) {
-  const listing = product.listing;
-  if (hasCompleteListingPriceProjection(listing)) {
+  if (hasCompleteProductPriceRange(product.priceRange)) {
     const groupRange = groups.length > 0 ? aggregateListingPriceRange(groups) : null;
-    const definesCompareAt = listingDefinesCompareAtProjection(listing);
+    const minCompareAtPrice = product.compareAtPriceRange?.minVariantPrice?.amount ?? groupRange?.minCompareAtPrice ?? null;
+    const maxCompareAtPrice = product.compareAtPriceRange?.maxVariantPrice?.amount ?? groupRange?.maxCompareAtPrice ?? null;
     return {
-      minPrice: listing.minPrice,
-      maxPrice: listing.maxPrice,
-      minCompareAtPrice: definesCompareAt ? listing.minCompareAtPrice ?? null : groupRange?.minCompareAtPrice ?? projectedListing.minCompareAtPrice,
-      maxCompareAtPrice: definesCompareAt ? listing.maxCompareAtPrice ?? null : groupRange?.maxCompareAtPrice ?? projectedListing.maxCompareAtPrice,
-      isPriceRange: listing.isPriceRange ?? listing.minPrice !== listing.maxPrice
+      minPrice: product.priceRange.minVariantPrice.amount,
+      maxPrice: product.priceRange.maxVariantPrice.amount,
+      minCompareAtPrice,
+      maxCompareAtPrice,
+      isPriceRange: product.priceRange.isPriceRange ?? product.priceRange.minVariantPrice.amount !== product.priceRange.maxVariantPrice.amount
     };
   }
   if (groups.length > 0) {
@@ -2682,15 +2656,19 @@ function buildProductListingPageWhere(params) {
   if (tagIds) clauses.push({ tags: { in: tagIds } });
   const minPrice = filters?.price?.min;
   if (minPrice != null) {
-    clauses.push({ "listing.maxPrice": { greater_than_equal: minPrice } });
+    clauses.push({
+      "priceRange.maxVariantPrice.amount": { greater_than_equal: minPrice }
+    });
   }
   const maxPrice = filters?.price?.max;
   if (maxPrice != null) {
-    clauses.push({ "listing.minPrice": { less_than_equal: maxPrice } });
+    clauses.push({
+      "priceRange.minVariantPrice.amount": { less_than_equal: maxPrice }
+    });
   }
   if (filters?.availableForSale != null) {
     clauses.push({
-      "listing.availableForSale": { equals: filters.availableForSale }
+      availableForSale: { equals: filters.availableForSale }
     });
   }
   if (clauses.length === 0) return void 0;