@01.software/sdk 0.10.0 → 0.11.0

package/README.md

@@ -429,7 +429,7 @@ const handler = createTypedWebhookHandler('orders', async (event) => {
 | Carts        | `carts`, `cart-items`                                                                                                                           |
 | Commerce     | `discounts`, `shipping-policies`                                                                                                                |
 | Content      | `posts`, `post-authors`, `post-categories`, `post-tags`, `documents`, `document-categories`, `document-types`                                  |
-| Playlists    | `playlists`, `playlist-categories`, `playlist-tags`, `tracks`, `playlist-tracks`, `track-categories`, `track-tags`                            |
+| Playlists    | `playlists`, `playlist-categories`, `playlist-tags`, `tracks`, `track-categories`, `track-tags`                                               |
 | Galleries    | `galleries`, `gallery-items`, `gallery-categories`, `gallery-tags`                                                                              |
 | Canvas       | `canvases`, `canvas-node-types`, `canvas-edge-types`, `canvas-categories`, `canvas-tags`                                                        |
 | Videos       | `videos`, `video-categories`, `video-tags`                                                                                                      |

package/dist/{const-Dmgge6oQ.d.ts → const-CWbOFesW.d.ts}

@@ -1,4 +1,4 @@
-import { C as Config } from './payload-types-D0zFPijW.js';
+import { C as Config } from './payload-types-BX9al1wy.js';
 
 /**
  * Collection type derived from Payload Config.
@@ -9,7 +9,7 @@ type Collection = keyof Config['collections'];
  * Array of all public collection names for runtime use (e.g., Zod enum validation).
  * This is the single source of truth for which collections are publicly accessible via SDK.
  */
-declare const COLLECTIONS: readonly ["tenants", "tenant-metadata", "tenant-logos", "products", "product-variants", "product-options", "product-option-values", "product-categories", "product-tags", "product-collections", "brands", "brand-logos", "orders", "order-items", "returns", "return-items", "fulfillments", "fulfillment-items", "transactions", "customers", "customer-addresses", "customer-groups", "carts", "cart-items", "discounts", "shipping-policies", "documents", "document-categories", "document-types", "posts", "post-authors", "post-categories", "post-tags", "playlists", "playlist-categories", "playlist-tags", "tracks", "playlist-tracks", "track-categories", "track-tags", "galleries", "gallery-categories", "gallery-tags", "gallery-items", "links", "link-categories", "link-tags", "canvases", "canvas-node-types", "canvas-edge-types", "canvas-categories", "canvas-tags", "videos", "video-categories", "video-tags", "live-streams", "images", "forms", "form-submissions", "threads", "comments", "reactions", "reaction-types", "bookmarks", "thread-categories", "reports", "community-bans"];
+declare const COLLECTIONS: readonly ["tenants", "tenant-metadata", "tenant-logos", "products", "product-variants", "product-options", "product-option-values", "product-categories", "product-tags", "product-collections", "brands", "brand-logos", "orders", "order-items", "returns", "return-items", "fulfillments", "fulfillment-items", "transactions", "customers", "customer-addresses", "customer-groups", "carts", "cart-items", "discounts", "shipping-policies", "documents", "document-categories", "document-types", "posts", "post-authors", "post-categories", "post-tags", "playlists", "playlist-categories", "playlist-tags", "tracks", "track-categories", "track-tags", "galleries", "gallery-categories", "gallery-tags", "gallery-items", "links", "link-categories", "link-tags", "canvases", "canvas-node-types", "canvas-edge-types", "canvas-categories", "canvas-tags", "videos", "video-categories", "video-tags", "live-streams", "images", "forms", "form-submissions", "threads", "comments", "reactions", "reaction-types", "bookmarks", "thread-categories", "reports", "community-bans"];
 /**
  * Public collections available for SDK access.
  * Derived from the COLLECTIONS array (single source of truth).

package/dist/{const-k0fqIBda.d.cts → const-DBZBjsZH.d.cts}

@@ -1,4 +1,4 @@
-import { C as Config } from './payload-types-D0zFPijW.cjs';
+import { C as Config } from './payload-types-BX9al1wy.cjs';
 
 /**
  * Collection type derived from Payload Config.
@@ -9,7 +9,7 @@ type Collection = keyof Config['collections'];
  * Array of all public collection names for runtime use (e.g., Zod enum validation).
  * This is the single source of truth for which collections are publicly accessible via SDK.
  */
-declare const COLLECTIONS: readonly ["tenants", "tenant-metadata", "tenant-logos", "products", "product-variants", "product-options", "product-option-values", "product-categories", "product-tags", "product-collections", "brands", "brand-logos", "orders", "order-items", "returns", "return-items", "fulfillments", "fulfillment-items", "transactions", "customers", "customer-addresses", "customer-groups", "carts", "cart-items", "discounts", "shipping-policies", "documents", "document-categories", "document-types", "posts", "post-authors", "post-categories", "post-tags", "playlists", "playlist-categories", "playlist-tags", "tracks", "playlist-tracks", "track-categories", "track-tags", "galleries", "gallery-categories", "gallery-tags", "gallery-items", "links", "link-categories", "link-tags", "canvases", "canvas-node-types", "canvas-edge-types", "canvas-categories", "canvas-tags", "videos", "video-categories", "video-tags", "live-streams", "images", "forms", "form-submissions", "threads", "comments", "reactions", "reaction-types", "bookmarks", "thread-categories", "reports", "community-bans"];
+declare const COLLECTIONS: readonly ["tenants", "tenant-metadata", "tenant-logos", "products", "product-variants", "product-options", "product-option-values", "product-categories", "product-tags", "product-collections", "brands", "brand-logos", "orders", "order-items", "returns", "return-items", "fulfillments", "fulfillment-items", "transactions", "customers", "customer-addresses", "customer-groups", "carts", "cart-items", "discounts", "shipping-policies", "documents", "document-categories", "document-types", "posts", "post-authors", "post-categories", "post-tags", "playlists", "playlist-categories", "playlist-tags", "tracks", "track-categories", "track-tags", "galleries", "gallery-categories", "gallery-tags", "gallery-items", "links", "link-categories", "link-tags", "canvases", "canvas-node-types", "canvas-edge-types", "canvas-categories", "canvas-tags", "videos", "video-categories", "video-tags", "live-streams", "images", "forms", "form-submissions", "threads", "comments", "reactions", "reaction-types", "bookmarks", "thread-categories", "reports", "community-bans"];
 /**
  * Public collections available for SDK access.
  * Derived from the COLLECTIONS array (single source of truth).

package/dist/index.cjs

@@ -45,6 +45,9 @@ __export(src_exports, {
   TimeoutError: () => TimeoutError,
   UsageLimitError: () => UsageLimitError,
   ValidationError: () => ValidationError,
+  buildProductListingGroupsByOption: () => buildProductListingGroupsByOption,
+  buildProductListingProjection: () => buildProductListingProjection,
+  buildProductOptionMatrix: () => buildProductOptionMatrix,
   collectionKeys: () => collectionKeys,
   createClient: () => createClient,
   createServerClient: () => createServerClient,
@@ -52,12 +55,14 @@ __export(src_exports, {
   customerKeys: () => customerKeys,
   formatOrderName: () => formatOrderName,
   generateOrderNumber: () => generateOrderNumber,
+  getAvailableOptionValues: () => getAvailableOptionValues,
   getImageLqip: () => getImageLqip,
   getImagePalette: () => getImagePalette,
   getImagePlaceholderStyle: () => getImagePlaceholderStyle,
   getImageSrcSet: () => getImageSrcSet,
   getImageUrl: () => getImageUrl,
   getQueryClient: () => getQueryClient,
+  getSelectedValueByOptionId: () => getSelectedValueByOptionId,
   getVideoGif: () => getVideoGif,
   getVideoMp4Url: () => getVideoMp4Url,
   getVideoStoryboard: () => getVideoStoryboard,
@@ -74,7 +79,10 @@ __export(src_exports, {
   isUsageLimitError: () => isUsageLimitError,
   isValidWebhookEvent: () => isValidWebhookEvent,
   isValidationError: () => isValidationError,
-  resolveRelation: () => resolveRelation
+  normalizeSelectedValueIds: () => normalizeSelectedValueIds,
+  productKeys: () => productKeys,
+  resolveRelation: () => resolveRelation,
+  resolveVariantForSelection: () => resolveVariantForSelection
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -644,6 +652,12 @@ var ProductApi = class extends BaseApi {
   stockCheck(params) {
     return this.request("/api/products/stock-check", params);
   }
+  listingGroups(params) {
+    return this.request(
+      "/api/products/listing-groups",
+      params
+    );
+  }
 };
 
 // src/utils/types.ts
@@ -988,6 +1002,18 @@ var CollectionClient = class extends HttpClient {
     });
     return this.parseFindResponse(response);
   }
+  /**
+   * Find-like response from a custom endpoint
+   * POST /api/...custom-endpoint
+   */
+  async requestFindEndpoint(endpoint, data) {
+    const response = await httpFetch(endpoint, {
+      ...this.defaultOptions,
+      method: "POST",
+      body: data ? JSON.stringify(data) : void 0
+    });
+    return this.parseFindResponse(response);
+  }
   /**
    * Find document by ID
    * GET /api/{collection}/{id}
@@ -1136,7 +1162,6 @@ var COLLECTIONS = [
   "playlist-categories",
   "playlist-tags",
   "tracks",
-  "playlist-tracks",
   "track-categories",
   "track-tags",
   "galleries",
@@ -1631,6 +1656,9 @@ function getQueryClient() {
   return browserQueryClient;
 }
 
+// src/core/query/query-hooks.ts
+var import_react_query4 = require("@tanstack/react-query");
+
 // src/core/query/collection-hooks.ts
 var import_react_query2 = require("@tanstack/react-query");
 
@@ -1650,6 +1678,10 @@ var customerKeys = {
   all: ["customer"],
   me: () => ["customer", "me"]
 };
+var productKeys = {
+  listingGroups: (options) => ["products", "listing-groups", "list", options],
+  listingGroupsInfinite: (options) => ["products", "listing-groups", "infinite", options]
+};
 
 // src/core/query/collection-hooks.ts
 var DEFAULT_PAGE_SIZE = 20;
@@ -2024,6 +2056,98 @@ var QueryHooks = class extends CollectionHooks {
     this.setCustomerData = (data) => this._customer.setCustomerData(data);
     this._customer = new CustomerHooks(queryClient, customerAuth);
   }
+  useProductListingGroupsQuery(params, options) {
+    const queryOptions = params.options;
+    const { placeholderData, ...restOptions } = options ?? {};
+    return (0, import_react_query4.useQuery)({
+      queryKey: productKeys.listingGroups(queryOptions),
+      queryFn: async () => this.collectionClient.requestFindEndpoint(
+        "/api/products/listing-groups/query",
+        { options: queryOptions }
+      ),
+      ...restOptions,
+      ...placeholderData !== void 0 && {
+        placeholderData
+      }
+    });
+  }
+  useSuspenseProductListingGroupsQuery(params, options) {
+    const queryOptions = params.options;
+    return (0, import_react_query4.useSuspenseQuery)({
+      queryKey: productKeys.listingGroups(queryOptions),
+      queryFn: async () => this.collectionClient.requestFindEndpoint(
+        "/api/products/listing-groups/query",
+        { options: queryOptions }
+      ),
+      ...options
+    });
+  }
+  useInfiniteProductListingGroupsQuery(params, options) {
+    const {
+      options: queryOptions,
+      pageSize = 20
+    } = params;
+    return (0, import_react_query4.useInfiniteQuery)({
+      queryKey: productKeys.listingGroupsInfinite(queryOptions),
+      queryFn: async ({ pageParam }) => this.collectionClient.requestFindEndpoint(
+        "/api/products/listing-groups/query",
+        {
+          options: { ...queryOptions, page: pageParam, limit: pageSize }
+        }
+      ),
+      initialPageParam: 1,
+      getNextPageParam: (lastPage) => lastPage.hasNextPage ? lastPage.nextPage : void 0,
+      ...options
+    });
+  }
+  useSuspenseInfiniteProductListingGroupsQuery(params, options) {
+    const {
+      options: queryOptions,
+      pageSize = 20
+    } = params;
+    return (0, import_react_query4.useSuspenseInfiniteQuery)({
+      queryKey: productKeys.listingGroupsInfinite(queryOptions),
+      queryFn: async ({ pageParam }) => this.collectionClient.requestFindEndpoint(
+        "/api/products/listing-groups/query",
+        {
+          options: { ...queryOptions, page: pageParam, limit: pageSize }
+        }
+      ),
+      initialPageParam: 1,
+      getNextPageParam: (lastPage) => lastPage.hasNextPage ? lastPage.nextPage : void 0,
+      ...options
+    });
+  }
+  async prefetchProductListingGroupsQuery(params, options) {
+    const queryOptions = params.options;
+    return this.queryClient.prefetchQuery({
+      queryKey: productKeys.listingGroups(queryOptions),
+      queryFn: async () => this.collectionClient.requestFindEndpoint(
+        "/api/products/listing-groups/query",
+        { options: queryOptions }
+      ),
+      ...options
+    });
+  }
+  async prefetchInfiniteProductListingGroupsQuery(params, options) {
+    const {
+      options: queryOptions,
+      pageSize = 20
+    } = params;
+    return this.queryClient.prefetchInfiniteQuery({
+      queryKey: productKeys.listingGroupsInfinite(queryOptions),
+      queryFn: async ({ pageParam }) => this.collectionClient.requestFindEndpoint(
+        "/api/products/listing-groups/query",
+        {
+          options: { ...queryOptions, page: pageParam, limit: pageSize }
+        }
+      ),
+      initialPageParam: 1,
+      getNextPageParam: (lastPage) => lastPage.hasNextPage ? lastPage.nextPage : void 0,
+      pages: options?.pages ?? 1,
+      staleTime: options?.staleTime
+    });
+  }
 };
 
 // src/core/client/client.ts
@@ -2364,6 +2488,242 @@ function createTypedWebhookHandler(collection, handler) {
   };
 }
 
+// src/utils/ecommerce.ts
+function getRelationID(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (value && typeof value === "object" && "id" in value) {
+    const id = value.id;
+    if (typeof id === "string") return id;
+    if (typeof id === "number") return String(id);
+  }
+  return void 0;
+}
+function compareOrder(left, right) {
+  return (left ?? "").localeCompare(right ?? "");
+}
+function isProductOptionValueDoc(value) {
+  return typeof value === "object" && value !== null && "id" in value && ("value" in value || "slug" in value);
+}
+function extractEntityId(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (value && typeof value === "object" && "id" in value) {
+    if (typeof value.id === "string") return value.id;
+    if (typeof value.id === "number") return String(value.id);
+  }
+  return null;
+}
+function getFirstMediaId(values) {
+  if (!Array.isArray(values)) return null;
+  for (const value of values) {
+    const id = extractEntityId(value);
+    if (id != null) return id;
+  }
+  return null;
+}
+function getVariantPrimaryImage(variant) {
+  if (!variant) return null;
+  return extractEntityId(variant.thumbnail) ?? getFirstMediaId(variant.images);
+}
+function normalizeOptionValue(value, fallbackOptionId) {
+  return {
+    id: String(value.id),
+    optionId: getRelationID(value.option) ?? fallbackOptionId,
+    label: value.value || value.slug || String(value.id),
+    slug: value.slug ?? null,
+    order: value._order ?? value["_product-option-values_values_order"] ?? ""
+  };
+}
+function normalizeVariantOptionValues(variant, valueToOptionId, optionIds) {
+  const optionValueByOptionId = /* @__PURE__ */ new Map();
+  for (const rawValue of Array.isArray(variant.optionValues) ? variant.optionValues : []) {
+    const valueId = getRelationID(rawValue);
+    if (!valueId) continue;
+    const optionId = valueToOptionId.get(valueId) ?? (isProductOptionValueDoc(rawValue) ? getRelationID(rawValue.option) : void 0);
+    if (!optionId || optionValueByOptionId.has(optionId)) continue;
+    optionValueByOptionId.set(optionId, valueId);
+  }
+  const optionValueIds = optionIds.map((optionId) => optionValueByOptionId.get(optionId)).filter((valueId) => Boolean(valueId));
+  return {
+    id: String(variant.id),
+    optionValueIds,
+    optionValueByOptionId,
+    source: variant
+  };
+}
+function buildProductOptionMatrix({
+  options,
+  variants = []
+}) {
+  const normalizedOptions = options.map((option) => {
+    const valuesById = /* @__PURE__ */ new Map();
+    for (const rawValue of option.values?.docs ?? []) {
+      if (!isProductOptionValueDoc(rawValue)) continue;
+      const normalizedValue = normalizeOptionValue(rawValue, String(option.id));
+      valuesById.set(normalizedValue.id, normalizedValue);
+    }
+    return {
+      id: String(option.id),
+      title: option.title ?? String(option.id),
+      order: option._order ?? option["_product-options_options_order"] ?? "",
+      values: Array.from(valuesById.values()).sort(
+        (left, right) => compareOrder(left.order, right.order)
+      )
+    };
+  }).sort((left, right) => compareOrder(left.order, right.order));
+  const optionById = new Map(normalizedOptions.map((option) => [option.id, option]));
+  const valueById = /* @__PURE__ */ new Map();
+  const valueToOptionId = /* @__PURE__ */ new Map();
+  for (const option of normalizedOptions) {
+    for (const value of option.values) {
+      valueById.set(value.id, value);
+      valueToOptionId.set(value.id, option.id);
+    }
+  }
+  const optionIds = normalizedOptions.map((option) => option.id);
+  const normalizedVariants = variants.map(
+    (variant) => normalizeVariantOptionValues(variant, valueToOptionId, optionIds)
+  );
+  return {
+    options: normalizedOptions,
+    optionIds,
+    optionById,
+    valueById,
+    valueToOptionId,
+    variants: normalizedVariants
+  };
+}
+function getSelectedValueByOptionId(matrix, selectedValueIds) {
+  const selectedByOption = /* @__PURE__ */ new Map();
+  for (const rawValue of selectedValueIds) {
+    const valueId = getRelationID(rawValue);
+    if (!valueId) continue;
+    const optionId = matrix.valueToOptionId.get(valueId);
+    if (!optionId || selectedByOption.has(optionId)) continue;
+    selectedByOption.set(optionId, valueId);
+  }
+  return selectedByOption;
+}
+function normalizeSelectedValueIds(matrix, selectedValueIds) {
+  const selectedByOption = getSelectedValueByOptionId(matrix, selectedValueIds);
+  return matrix.optionIds.map((optionId) => selectedByOption.get(optionId)).filter((valueId) => Boolean(valueId));
+}
+function getAvailableOptionValues(matrix, optionId, selectedValueIds) {
+  const option = matrix.optionById.get(optionId);
+  if (!option) return [];
+  if (matrix.variants.length === 0) {
+    return option.values;
+  }
+  const selectedByOption = getSelectedValueByOptionId(matrix, selectedValueIds);
+  selectedByOption.delete(optionId);
+  const matchingVariants = matrix.variants.filter(
+    (variant) => Array.from(selectedByOption.entries()).every(
+      ([selectedOptionId, selectedValueId]) => variant.optionValueByOptionId.get(selectedOptionId) === selectedValueId
+    )
+  );
+  const availableValueIds = new Set(
+    matchingVariants.map((variant) => variant.optionValueByOptionId.get(optionId)).filter((valueId) => Boolean(valueId))
+  );
+  return option.values.filter((value) => availableValueIds.has(value.id));
+}
+function resolveVariantForSelection(matrix, selectedValueIds) {
+  const selectedByOption = getSelectedValueByOptionId(matrix, selectedValueIds);
+  if (selectedByOption.size !== matrix.optionIds.length) {
+    return void 0;
+  }
+  return matrix.variants.find(
+    (variant) => matrix.optionIds.every(
+      (optionId) => variant.optionValueByOptionId.get(optionId) === selectedByOption.get(optionId)
+    )
+  );
+}
+function compareVariantOrder(a, b) {
+  const aOrder = Number(a._order ?? Number.MAX_SAFE_INTEGER);
+  const bOrder = Number(b._order ?? Number.MAX_SAFE_INTEGER);
+  if (Number.isFinite(aOrder) && Number.isFinite(bOrder) && aOrder !== bOrder) {
+    return aOrder - bOrder;
+  }
+  const aId = String(getRelationID(a.id) ?? "");
+  const bId = String(getRelationID(b.id) ?? "");
+  return aId.localeCompare(bId);
+}
+function isVariantAvailableForSale(variant) {
+  if (variant.isActive === false) return false;
+  if (variant.isUnlimited) return true;
+  return (variant.stock ?? 0) > 0;
+}
+function getMinMax(values) {
+  const numbers = values.filter((value) => typeof value === "number");
+  if (numbers.length === 0) {
+    return { min: null, max: null };
+  }
+  return {
+    min: Math.min(...numbers),
+    max: Math.max(...numbers)
+  };
+}
+function buildProductListingProjection(product, variants) {
+  const orderedVariants = [...variants].sort(compareVariantOrder);
+  const activeVariants = orderedVariants.filter((variant) => variant.isActive !== false);
+  const availableVariants = activeVariants.filter(isVariantAvailableForSale);
+  const selectionHintVariant = availableVariants[0] ?? activeVariants[0] ?? null;
+  const { min: minPrice, max: maxPrice } = getMinMax(
+    activeVariants.map((variant) => variant.price)
+  );
+  const { min: minCompareAtPrice, max: maxCompareAtPrice } = getMinMax(
+    activeVariants.map((variant) => variant.compareAtPrice)
+  );
+  const productPrimaryImage = extractEntityId(product?.thumbnail) ?? getFirstMediaId(product?.images);
+  const variantPrimaryImage = getVariantPrimaryImage(selectionHintVariant) ?? getVariantPrimaryImage(activeVariants[0]) ?? getVariantPrimaryImage(orderedVariants[0]);
+  return {
+    selectionHintVariant: getRelationID(selectionHintVariant?.id) ?? null,
+    primaryImage: productPrimaryImage ?? variantPrimaryImage,
+    minPrice,
+    maxPrice,
+    minCompareAtPrice,
+    maxCompareAtPrice,
+    isPriceRange: minPrice !== null && maxPrice !== null ? minPrice !== maxPrice : false,
+    availableForSale: availableVariants.length > 0
+  };
+}
+function buildProductListingGroupsByOption(args) {
+  const primaryOptionId = args.primaryOptionId ?? void 0;
+  if (!primaryOptionId) return [];
+  const matrix = buildProductOptionMatrix({
+    options: args.options,
+    variants: args.variants
+  });
+  const primaryOption = matrix.optionById.get(primaryOptionId);
+  if (!primaryOption) return [];
+  return primaryOption.values.flatMap((value) => {
+    const variants = matrix.variants.filter(
+      (variant) => variant.optionValueByOptionId.get(primaryOption.id) === value.id
+    ).map((variant) => variant.source);
+    if (variants.length === 0) {
+      return [];
+    }
+    const listingBase = buildProductListingProjection(void 0, variants);
+    const productFallbackImage = extractEntityId(args.product?.thumbnail) ?? getFirstMediaId(args.product?.images);
+    return [
+      {
+        optionId: primaryOption.id,
+        optionTitle: primaryOption.title,
+        optionValueId: value.id,
+        optionValueLabel: value.label,
+        optionValueSlug: value.slug,
+        variantIds: variants.map((variant) => String(variant.id)),
+        variantCount: variants.length,
+        variants,
+        listing: {
+          ...listingBase,
+          primaryImage: listingBase.primaryImage ?? productFallbackImage
+        }
+      }
+    ];
+  });
+}
+
 // src/utils/image.ts
 var IMAGE_SIZES = [384, 768, 1536];
 function getImageUrl(image, displayWidth, dpr = 1) {