@01.software/sdk 0.38.0 → 0.39.0

package/dist/server.cjs

@@ -641,6 +641,32 @@ function listingGroupsQuery(params) {
 function listingGroupsCatalogQuery(params) {
   return `/api/products/listing-groups/catalog?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
 }
+function appendListingGroupsQuerySearchParams(search, options) {
+  if (options?.page != null) search.set("page", String(options.page));
+  if (options?.limit != null) search.set("limit", String(options.limit));
+  if (options?.sort != null) {
+    const sort = options.sort;
+    search.set(
+      "sort",
+      Array.isArray(sort) ? sort.join(",") : sort
+    );
+  }
+  if (options?.where != null) {
+    search.set("whereJson", JSON.stringify(options.where));
+  }
+}
+function listingGroupsQueryUrl(options) {
+  const search = new URLSearchParams();
+  appendListingGroupsQuerySearchParams(search, options);
+  const query = search.toString();
+  return `/api/products/listing-groups/query${query ? `?${query}` : ""}`;
+}
+function listingGroupsQueryCatalogUrl(options) {
+  const search = new URLSearchParams();
+  appendListingGroupsQuerySearchParams(search, options);
+  const query = search.toString();
+  return `/api/products/listing-groups/query/catalog${query ? `?${query}` : ""}`;
+}
 function stockSnapshotQuery(params) {
   return `/api/products/stock?variantIds=${params.variantIds.map(encodeURIComponent).join(",")}`;
 }
@@ -1628,6 +1654,1061 @@ var CartApi = class extends CustomerScopedApi {
   }
 };
 
+// src/utils/product-selection-media.ts
+function selectedSwatchMediaItemId(swatch) {
+  if (!swatch || swatch.type !== "media") return null;
+  const id = swatch.mediaItemId;
+  if (id == null || id === "") return null;
+  return String(id);
+}
+function getMediaId(value) {
+  if (typeof value === "string" || typeof value === "number") {
+    return String(value);
+  }
+  if (typeof value === "object" && value !== null && "id" in value) {
+    const id = value.id;
+    if (typeof id === "string" || typeof id === "number") return String(id);
+  }
+  return null;
+}
+function toPointerId(value) {
+  return getMediaId(value);
+}
+function mediaArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => entry != null);
+}
+function uniqueWithPrimaryFirst(primary, items) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const id = getMediaId(item);
+    const key = id ?? `inline:${unique.size}`;
+    if (!unique.has(key)) unique.set(key, item);
+  }
+  if (primary) {
+    const primaryId = getMediaId(primary);
+    const prefixed = /* @__PURE__ */ new Map();
+    const primaryKey = primaryId ?? "inline:primary";
+    prefixed.set(primaryKey, primary);
+    for (const [key, value] of unique.entries()) {
+      if (!prefixed.has(key)) prefixed.set(key, value);
+    }
+    return Array.from(prefixed.values());
+  }
+  return Array.from(unique.values());
+}
+function buildPoolById(pool) {
+  const poolById = /* @__PURE__ */ new Map();
+  for (const item of pool) {
+    const id = getMediaId(item);
+    if (id) poolById.set(id, item);
+  }
+  return poolById;
+}
+function resolveVariantImageItems(variant, poolById) {
+  if (!variant || !Array.isArray(variant.images)) return [];
+  const resolved = [];
+  for (const entry of variant.images) {
+    if (entry == null) continue;
+    if (typeof entry === "string" || typeof entry === "number") {
+      const pooled = poolById.get(String(entry));
+      if (pooled) resolved.push(pooled);
+      continue;
+    }
+    const mediaId = getMediaId(entry);
+    if (mediaId) {
+      const pooled = poolById.get(mediaId);
+      if (pooled) {
+        resolved.push(pooled);
+      }
+      continue;
+    }
+  }
+  return resolved;
+}
+function resolveOptionSwatchPrimary(selectedOptionValues, poolById) {
+  if (!selectedOptionValues?.length) return null;
+  for (const optionValue of selectedOptionValues) {
+    const swatch = optionValue?.swatch;
+    const swatchPointer = selectedSwatchMediaItemId(swatch);
+    if (swatchPointer) {
+      const pooled = poolById.get(swatchPointer);
+      if (pooled) return pooled;
+    }
+    const inline = swatch?.inlineMedia;
+    if (inline != null && typeof inline === "object") {
+      return inline;
+    }
+  }
+  return null;
+}
+function resolveProductSelectionMedia(input) {
+  const pool = mediaArray(input.productMediaPool);
+  const poolById = buildPoolById(pool);
+  const selectedVariantImages = resolveVariantImageItems(
+    input.selectedVariant,
+    poolById
+  );
+  if (selectedVariantImages.length > 0) {
+    const primaryImage = selectedVariantImages[0] ?? null;
+    return {
+      primaryImage,
+      images: uniqueWithPrimaryFirst(primaryImage, selectedVariantImages),
+      source: "variant_media_selected"
+    };
+  }
+  if (input.selectedVariant == null && (input.matchingVariants?.length ?? 0) > 0) {
+    const mergedMatchingImages = [];
+    for (const matchingVariant of input.matchingVariants ?? []) {
+      mergedMatchingImages.push(
+        ...resolveVariantImageItems(matchingVariant, poolById)
+      );
+    }
+    if (mergedMatchingImages.length > 0) {
+      const primaryImage = mergedMatchingImages[0] ?? null;
+      return {
+        primaryImage,
+        images: uniqueWithPrimaryFirst(primaryImage, mergedMatchingImages),
+        source: "variant_media_matching"
+      };
+    }
+  }
+  const optionSwatchPrimary = resolveOptionSwatchPrimary(
+    input.selectedOptionValues,
+    poolById
+  );
+  if (optionSwatchPrimary) {
+    return {
+      primaryImage: optionSwatchPrimary,
+      images: [optionSwatchPrimary],
+      source: "option_swatch"
+    };
+  }
+  return {
+    primaryImage: null,
+    images: [],
+    source: "none"
+  };
+}
+function resolveListingPrimaryImagePointer(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;
+  }
+  if (pool.length > 0) {
+    const firstPoolId = getMediaId(pool[0]);
+    if (firstPoolId) return firstPoolId;
+  }
+  return null;
+}
+
+// src/utils/ecommerce.ts
+var DEFAULT_PRODUCT_SELECTION_URL_EMIT = "slug-compat";
+function resolveProductSelectionUrlEmit(emit) {
+  return emit ?? DEFAULT_PRODUCT_SELECTION_URL_EMIT;
+}
+function appendSlugCompatSelectionParam(params, matrix, optionId, valueId) {
+  const option = matrix.optionById.get(optionId);
+  const value = matrix.valueById.get(valueId);
+  if (!option?.slug || !value?.slug) return false;
+  const slugMatches = option.values.filter(
+    (candidate) => candidate.slug === value.slug
+  );
+  if (slugMatches.length !== 1) return false;
+  params.append(`opt.${option.slug}`, value.slug);
+  return true;
+}
+function appendCanonicalSelectionParam(params, optionId, valueId) {
+  params.append(`opt.${optionId}`, valueId);
+}
+var ProductSelectionCodecError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "ambiguous_product_selection_query";
+    this.name = "ProductSelectionCodecError";
+  }
+};
+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 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 resolveGenericListingPrimaryImage(product, resolvedPrimary, resolvedSource) {
+  return resolveListingPrimaryImagePointer({
+    productMediaPool: product?.images ?? [],
+    productPrimaryMediaItemId: getRelationID(
+      product?.primaryMediaItemId ?? null
+    ),
+    productThumbnail: product?.thumbnail ?? null,
+    listingPrimaryImage: product?.listing?.primaryImage ?? null,
+    resolvedPrimary,
+    resolvedSource
+  });
+}
+function normalizeProductOptionValueSwatch(swatch) {
+  if (swatch == null) return null;
+  if (typeof swatch !== "object") return null;
+  const raw = swatch;
+  const mediaItemId = extractEntityId(raw.mediaItemId);
+  const color = typeof raw.color === "string" ? raw.color.trim() : "";
+  const hasColor = color.length > 0;
+  if (raw.type === "media" || mediaItemId && raw.type !== "color") {
+    if (!mediaItemId || hasColor) return null;
+    return {
+      type: "media",
+      mediaItemId,
+      color: null
+    };
+  }
+  if (raw.type === "color" || hasColor) {
+    if (mediaItemId || !hasColor) return null;
+    return { type: "color", color, mediaItemId: null };
+  }
+  return null;
+}
+function matrixOrder(index) {
+  return String(index).padStart(6, "0");
+}
+function buildProductOptionMatrixFromDetail(detail) {
+  const normalizedOptions = detail.options.map((option, optionIndex) => ({
+    id: String(option.id),
+    title: option.title || String(option.id),
+    slug: option.slug,
+    order: matrixOrder(optionIndex),
+    values: option.values.map((value, valueIndex) => ({
+      id: String(value.id),
+      optionId: String(option.id),
+      optionSlug: option.slug,
+      label: value.value || value.slug || String(value.id),
+      slug: value.slug,
+      swatch: normalizeProductOptionValueSwatch(value.swatch),
+      order: matrixOrder(valueIndex)
+    }))
+  }));
+  const optionById = new Map(
+    normalizedOptions.map((option) => [option.id, option])
+  );
+  const optionBySlug = new Map(
+    normalizedOptions.map((option) => [option.slug, option])
+  );
+  const valueById = /* @__PURE__ */ new Map();
+  const valueToOptionId = /* @__PURE__ */ new Map();
+  const valueToOptionSlug = /* @__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);
+      valueToOptionSlug.set(value.id, option.slug);
+    }
+  }
+  const optionIds = normalizedOptions.map((option) => option.id);
+  const optionSlugs = normalizedOptions.map((option) => option.slug);
+  const normalizedVariants = detail.variants.map((variant) => {
+    const optionValueByOptionId = /* @__PURE__ */ new Map();
+    const optionValueByOptionSlug = /* @__PURE__ */ new Map();
+    for (const rawValue of variant.optionValues) {
+      const optionId = String(rawValue.optionId);
+      const valueId = String(rawValue.valueId);
+      const optionSlug = rawValue.optionSlug;
+      if (!optionById.has(optionId)) continue;
+      if (valueToOptionId.get(valueId) !== optionId) continue;
+      if (optionValueByOptionId.has(optionId)) continue;
+      optionValueByOptionId.set(optionId, valueId);
+      if (optionSlug && !optionValueByOptionSlug.has(optionSlug)) {
+        optionValueByOptionSlug.set(optionSlug, valueId);
+      }
+    }
+    const optionValueIds = optionIds.map((optionId) => optionValueByOptionId.get(optionId)).filter((valueId) => Boolean(valueId));
+    return {
+      id: String(variant.id),
+      optionValueIds,
+      optionValueByOptionId,
+      optionValueByOptionSlug,
+      source: variant
+    };
+  });
+  return {
+    options: normalizedOptions,
+    optionIds,
+    optionSlugs,
+    optionById,
+    optionBySlug,
+    valueById,
+    valueToOptionId,
+    valueToOptionSlug,
+    variants: normalizedVariants
+  };
+}
+function getVariantSelection(matrix, variantId) {
+  if (variantId == null) return void 0;
+  const id = String(variantId);
+  return matrix.variants.find((variant) => variant.id === id);
+}
+function hasExplicitSelection(selection) {
+  return Boolean(
+    selection.variantId != null || selection.search || selection.valueIds || Object.keys(selection.byOptionId ?? {}).length > 0 || Object.keys(selection.byOptionSlug ?? {}).length > 0
+  );
+}
+function assignSelectedValue(matrix, selectedByOptionId, optionId, valueId) {
+  if (valueId == null) return false;
+  const normalizedValueId = String(valueId);
+  if (matrix.valueToOptionId.get(normalizedValueId) !== optionId) return false;
+  selectedByOptionId.set(optionId, normalizedValueId);
+  return true;
+}
+function assignSelectedValueSlugByOptionId(matrix, selectedByOptionId, optionId, valueSlug) {
+  if (!valueSlug) return false;
+  const option = matrix.optionById.get(optionId);
+  if (!option) return false;
+  const values = option.values.filter(
+    (candidate) => candidate.slug === valueSlug
+  );
+  if (values.length > 1) {
+    throw new ProductSelectionCodecError(
+      `Ambiguous product selection value slug "${valueSlug}" for option "${optionId}". Use opt.<optionId>=<valueId>.`
+    );
+  }
+  const value = values[0];
+  if (!value) return false;
+  selectedByOptionId.set(optionId, value.id);
+  return true;
+}
+function assignSelectedValueSlugByOptionSlug(matrix, selectedByOptionId, optionSlug, valueSlug) {
+  if (!valueSlug) return false;
+  const option = matrix.optionBySlug.get(optionSlug);
+  if (!option) return false;
+  const values = option.values.filter(
+    (candidate) => candidate.slug === valueSlug
+  );
+  if (values.length > 1) {
+    throw new ProductSelectionCodecError(
+      `Ambiguous product selection value slug "${valueSlug}" for option "${optionSlug}". Use opt.<optionId>=<valueId>.`
+    );
+  }
+  const value = values[0];
+  if (!value) return false;
+  selectedByOptionId.set(option.id, value.id);
+  return true;
+}
+function toSearchParams(search) {
+  if (!search) return new URLSearchParams();
+  if (search instanceof URLSearchParams) return new URLSearchParams(search);
+  if (search instanceof URL) return new URLSearchParams(search.searchParams);
+  const trimmed = search.trim();
+  if (!trimmed) return new URLSearchParams();
+  try {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+      return new URL(trimmed).searchParams;
+    }
+  } catch {
+    return new URLSearchParams();
+  }
+  return new URLSearchParams(
+    trimmed.startsWith("?") ? trimmed.slice(1) : trimmed
+  );
+}
+function slugLike(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function assertNoAmbiguousSelectionParams(matrix, params) {
+  const knownSelectionKeys = /* @__PURE__ */ new Set();
+  const hasVariantParam = params.has("variant");
+  const hasOptionParams = Array.from(params.keys()).some(
+    (key) => key.startsWith("opt.")
+  );
+  if (hasVariantParam && hasOptionParams) {
+    throw new ProductSelectionCodecError(
+      "Product selection URL cannot mix variant=<variantId> with opt.<optionId>=<valueId> params."
+    );
+  }
+  for (const option of matrix.options) {
+    knownSelectionKeys.add(slugLike(option.slug));
+    knownSelectionKeys.add(slugLike(option.title));
+    for (const value of option.values) {
+      if (value.slug) knownSelectionKeys.add(slugLike(value.slug));
+    }
+  }
+  for (const [key, value] of params.entries()) {
+    if (key.startsWith("opt.")) {
+      const optionToken = key.slice(4);
+      if (!optionToken || !matrix.optionBySlug.has(optionToken) && !matrix.optionById.has(optionToken)) {
+        throw new ProductSelectionCodecError(
+          `Unknown product selection query parameter "${key}". Use opt.<optionId>=<valueId>.`
+        );
+      }
+      if (!value) {
+        throw new ProductSelectionCodecError(
+          `Product selection query parameter "${key}" requires a value ID or compatibility value slug.`
+        );
+      }
+      continue;
+    }
+    if (key === "variant") {
+      if (!value) {
+        throw new ProductSelectionCodecError(
+          'Product selection query parameter "variant" requires a variant ID.'
+        );
+      }
+      if (!getVariantSelection(matrix, value)) {
+        throw new ProductSelectionCodecError(
+          `Unknown product selection variant "${value}".`
+        );
+      }
+      continue;
+    }
+    const keyToken = slugLike(key);
+    if (knownSelectionKeys.has(keyToken) || value === "" && knownSelectionKeys.has(keyToken)) {
+      throw new ProductSelectionCodecError(
+        `Ambiguous product selection query parameter "${key}". Use opt.<optionId>=<valueId>.`
+      );
+    }
+  }
+}
+function emitCompatibilityOptionIdParam(options, event) {
+  try {
+    if (options?.onCompatibilityOptionIdParam) {
+      options.onCompatibilityOptionIdParam(event);
+      return;
+    }
+    options?.onLegacyOptionIdParam?.(event);
+  } catch {
+  }
+}
+function assignSearchSelection(matrix, selectedByOptionId, search, options) {
+  if (!search) return null;
+  const params = toSearchParams(search);
+  assertNoAmbiguousSelectionParams(matrix, params);
+  const variantParam = params.get("variant");
+  if (variantParam != null) {
+    const variantSelection = getVariantSelection(matrix, variantParam);
+    if (!variantSelection) {
+      throw new ProductSelectionCodecError(
+        `Unknown product selection variant "${variantParam}".`
+      );
+    }
+    for (const [optionId, valueId] of variantSelection.optionValueByOptionId) {
+      selectedByOptionId.set(optionId, valueId);
+    }
+    return variantSelection.id;
+  }
+  for (const [key, valueToken] of params.entries()) {
+    if (!key.startsWith("opt.")) continue;
+    const optionToken = key.slice(4);
+    const optionById = matrix.optionById.get(optionToken);
+    if (optionById) {
+      if (assignSelectedValue(
+        matrix,
+        selectedByOptionId,
+        optionById.id,
+        valueToken
+      )) {
+        continue;
+      }
+      const before = selectedByOptionId.get(optionById.id);
+      if (assignSelectedValueSlugByOptionId(
+        matrix,
+        selectedByOptionId,
+        optionById.id,
+        valueToken
+      ) && selectedByOptionId.get(optionById.id) !== before) {
+        emitCompatibilityOptionIdParam(options, {
+          optionId: optionById.id,
+          optionSlug: optionById.slug,
+          valueSlug: valueToken,
+          searchParam: key
+        });
+        continue;
+      }
+      throw new ProductSelectionCodecError(
+        `Unknown product selection value "${valueToken}" for option "${optionToken}". Use opt.<optionId>=<valueId>.`
+      );
+    }
+    const optionBySlug = matrix.optionBySlug.get(optionToken);
+    if (optionBySlug) {
+      if (assignSelectedValueSlugByOptionSlug(
+        matrix,
+        selectedByOptionId,
+        optionBySlug.slug,
+        valueToken
+      )) {
+        continue;
+      }
+      if (matrix.valueById.has(valueToken)) {
+        throw new ProductSelectionCodecError(
+          `Unknown product selection value "${valueToken}" for option "${optionToken}". Use opt.<optionId>=<valueId>.`
+        );
+      }
+      throw new ProductSelectionCodecError(
+        `Unknown product selection value "${valueToken}" for option "${optionToken}". Use opt.<optionSlug>=<valueSlug> for compatibility URLs.`
+      );
+    }
+  }
+  return null;
+}
+function normalizeProductSelectionFromMatrix(matrix, selection = {}, options) {
+  const selectedByOptionId = /* @__PURE__ */ new Map();
+  const variantSelection = getVariantSelection(matrix, selection.variantId);
+  const variantId = variantSelection?.id ?? null;
+  if (variantSelection) {
+    for (const [optionId, valueId] of variantSelection.optionValueByOptionId) {
+      selectedByOptionId.set(optionId, valueId);
+    }
+  }
+  for (const rawValueId of selection.valueIds ?? []) {
+    const valueId = getRelationID(rawValueId);
+    if (!valueId) continue;
+    const optionId = matrix.valueToOptionId.get(valueId);
+    if (!optionId) continue;
+    selectedByOptionId.set(optionId, valueId);
+  }
+  const searchVariantId = assignSearchSelection(
+    matrix,
+    selectedByOptionId,
+    selection.search,
+    options
+  );
+  for (const [rawOptionId, rawSelection] of Object.entries(
+    selection.byOptionId ?? {}
+  )) {
+    const optionId = String(rawOptionId);
+    if (!matrix.optionById.has(optionId)) continue;
+    if (rawSelection && typeof rawSelection === "object" && "valueId" in rawSelection && rawSelection.valueId != null) {
+      assignSelectedValue(
+        matrix,
+        selectedByOptionId,
+        optionId,
+        rawSelection.valueId
+      );
+      continue;
+    }
+    if (typeof rawSelection === "string" || typeof rawSelection === "number") {
+      assignSelectedValue(matrix, selectedByOptionId, optionId, rawSelection);
+      continue;
+    }
+    if (rawSelection && typeof rawSelection === "object" && "valueSlug" in rawSelection) {
+      assignSelectedValueSlugByOptionId(
+        matrix,
+        selectedByOptionId,
+        optionId,
+        rawSelection.valueSlug
+      );
+    }
+  }
+  for (const [rawOptionSlug, rawSelection] of Object.entries(
+    selection.byOptionSlug ?? {}
+  )) {
+    const optionSlug = String(rawOptionSlug);
+    if (!matrix.optionBySlug.has(optionSlug)) continue;
+    if (rawSelection && typeof rawSelection === "object" && "valueId" in rawSelection && rawSelection.valueId != null) {
+      const option = matrix.optionBySlug.get(optionSlug);
+      if (option) {
+        assignSelectedValue(
+          matrix,
+          selectedByOptionId,
+          option.id,
+          rawSelection.valueId
+        );
+      }
+      continue;
+    }
+    if (rawSelection && typeof rawSelection === "object" && "valueSlug" in rawSelection) {
+      assignSelectedValueSlugByOptionSlug(
+        matrix,
+        selectedByOptionId,
+        optionSlug,
+        rawSelection.valueSlug
+      );
+      continue;
+    }
+    if (typeof rawSelection === "string" || typeof rawSelection === "number") {
+      assignSelectedValueSlugByOptionSlug(
+        matrix,
+        selectedByOptionId,
+        optionSlug,
+        String(rawSelection)
+      );
+    }
+  }
+  const byOptionId = Object.fromEntries(
+    matrix.optionIds.map((optionId) => [optionId, selectedByOptionId.get(optionId)]).filter((entry) => Boolean(entry[1]))
+  );
+  const byOptionSlug = Object.fromEntries(
+    matrix.options.map((option) => {
+      const valueId = selectedByOptionId.get(option.id);
+      const value = valueId ? matrix.valueById.get(valueId) : void 0;
+      return [option.slug, value?.slug ?? void 0];
+    }).filter((entry) => Boolean(entry[1]))
+  );
+  return {
+    byOptionSlug,
+    byOptionId,
+    valueIds: matrix.optionIds.map((optionId) => byOptionId[optionId]).filter((valueId) => Boolean(valueId)),
+    variantId: searchVariantId ?? variantId
+  };
+}
+function stringifyProductSelection(detail, selection = {}, options) {
+  const matrix = buildProductOptionMatrixFromDetail(detail);
+  const normalized = normalizeProductSelectionFromMatrix(
+    matrix,
+    selection,
+    options
+  );
+  const params = new URLSearchParams();
+  if (hasExplicitSelection(selection)) {
+    const matchingVariants = getMatchingVariantEntries(matrix, normalized);
+    const exactVariant = getExactSelectedVariantEntry(
+      matrix,
+      normalized,
+      matchingVariants
+    );
+    if (exactVariant) {
+      params.set("variant", exactVariant.id);
+      return params.toString();
+    }
+  }
+  const emit = resolveProductSelectionUrlEmit(options?.emit);
+  for (const optionId of matrix.optionIds) {
+    const valueId = normalized.byOptionId[optionId];
+    if (!valueId) continue;
+    if (!matrix.optionById.has(optionId) || !matrix.valueById.has(valueId)) {
+      continue;
+    }
+    if (emit === "slug-compat") {
+      if (appendSlugCompatSelectionParam(params, matrix, optionId, valueId)) {
+        continue;
+      }
+    }
+    appendCanonicalSelectionParam(params, optionId, valueId);
+  }
+  return params.toString();
+}
+function selectedEntries(selection) {
+  return Object.entries(selection.byOptionId);
+}
+function getMatchingVariantEntries(matrix, selection) {
+  const entries = selectedEntries(selection);
+  if (entries.length === 0) return matrix.variants;
+  return matrix.variants.filter(
+    (variant) => entries.every(
+      ([optionId, valueId]) => variant.optionValueByOptionId.get(optionId) === valueId
+    )
+  );
+}
+function getExactSelectedVariantEntry(matrix, selection, matchingVariants) {
+  if (matrix.optionIds.length === 0) {
+    return getVariantSelection(matrix, selection.variantId) ?? (matchingVariants.length === 1 ? matchingVariants[0] ?? null : null);
+  }
+  const allOptionsSelected = matrix.optionIds.every(
+    (optionId) => Boolean(selection.byOptionId[optionId])
+  );
+  if (!allOptionsSelected) return null;
+  return matchingVariants.find(
+    (variant) => matrix.optionIds.every(
+      (optionId) => variant.optionValueByOptionId.get(optionId) === selection.byOptionId[optionId]
+    )
+  ) ?? null;
+}
+function isPresentMedia(value) {
+  return value != null;
+}
+function mediaArray2(values) {
+  if (!Array.isArray(values)) return [];
+  return values.filter(isPresentMedia);
+}
+function getProductHrefSlug(product) {
+  if ("product" in product && product.product?.slug) {
+    return product.product.slug;
+  }
+  if ("slug" in product && product.slug) return product.slug;
+  throw new ProductSelectionCodecError(
+    "Product slug is required to build a product href."
+  );
+}
+function joinProductPath(basePath, slug, trailingSlash) {
+  const base = basePath.replace(/\/+$/, "");
+  const encodedSlug = encodeURIComponent(slug);
+  return `${base}/${encodedSlug}${trailingSlash ? "/" : ""}`;
+}
+function getProductHrefGroupSelection(group, matrix) {
+  if (!group) return null;
+  if (group.variantId != null) return { variantId: group.variantId };
+  const optionId = group.optionId != null ? String(group.optionId) : group.optionSlug ? matrix?.optionBySlug.get(group.optionSlug)?.id : void 0;
+  if (!optionId) return null;
+  const option = matrix?.optionById.get(optionId);
+  const optionValueId = group.optionValueId != null ? String(group.optionValueId) : group.optionValueSlug && option ? option.values.find((value) => value.slug === group.optionValueSlug)?.id : void 0;
+  if (!optionValueId) return null;
+  return { byOptionId: { [optionId]: optionValueId } };
+}
+function getProductHrefCodecOptions(options) {
+  return options.emit != null ? { emit: options.emit } : void 0;
+}
+function appendGroupByOptionIdHrefParams(params, group, groupSelection, options) {
+  const emit = resolveProductSelectionUrlEmit(options.emit);
+  const byOptionId = groupSelection.byOptionId ?? {};
+  const entries = Object.entries(byOptionId);
+  if (entries.length === 0) return false;
+  for (const [optionId, valueId] of entries) {
+    const optionSlug = group?.optionSlug ?? options.matrix?.optionById.get(optionId)?.slug ?? null;
+    const valueSlug = group?.optionValueSlug ?? options.matrix?.valueById.get(String(valueId))?.slug ?? null;
+    if (emit === "slug-compat" && optionSlug && valueSlug && entries.length === 1) {
+      params.set(`opt.${optionSlug}`, valueSlug);
+      return true;
+    }
+    if (emit === "slug-compat" && options.matrix && appendSlugCompatSelectionParam(
+      params,
+      options.matrix,
+      optionId,
+      String(valueId)
+    )) {
+      continue;
+    }
+    appendCanonicalSelectionParam(params, optionId, String(valueId));
+  }
+  return params.size > 0;
+}
+function getPreferCompleteVariantFromHintSelection(group, options) {
+  if (!options.preferCompleteVariantFromHint) return null;
+  if (group?.optionValueId != null || group?.optionValueSlug) return null;
+  const hintVariantId = group?.listing?.selectionHintVariant;
+  if (hintVariantId == null) return null;
+  return { variantId: hintVariantId };
+}
+function buildProductHref(product, group, options = {}) {
+  const path = joinProductPath(
+    options.basePath ?? "/products",
+    getProductHrefSlug(product),
+    options.trailingSlash ?? false
+  );
+  const params = new URLSearchParams();
+  if (options.detail && options.selection) {
+    const selection = stringifyProductSelection(
+      options.detail,
+      options.selection,
+      getProductHrefCodecOptions(options)
+    );
+    return selection ? `${path}?${selection}` : path;
+  }
+  const preferVariantSelection = getPreferCompleteVariantFromHintSelection(
+    group,
+    options
+  );
+  if (preferVariantSelection) {
+    if (options.detail) {
+      const selection = stringifyProductSelection(
+        options.detail,
+        preferVariantSelection,
+        getProductHrefCodecOptions(options)
+      );
+      return selection ? `${path}?${selection}` : path;
+    }
+    if (preferVariantSelection.variantId != null) {
+      params.set("variant", String(preferVariantSelection.variantId));
+      return `${path}?${params.toString()}`;
+    }
+  }
+  const groupSelection = getProductHrefGroupSelection(group, options.matrix);
+  if (groupSelection) {
+    if (options.detail) {
+      const selection = stringifyProductSelection(
+        options.detail,
+        groupSelection,
+        getProductHrefCodecOptions(options)
+      );
+      return selection ? `${path}?${selection}` : path;
+    }
+    if (groupSelection.variantId != null) {
+      params.set("variant", String(groupSelection.variantId));
+      return `${path}?${params.toString()}`;
+    }
+    if (appendGroupByOptionIdHrefParams(params, group, groupSelection, options)) {
+      return `${path}?${params.toString()}`;
+    }
+  }
+  if (group?.optionValueSlug) {
+    const optionSlug = group.optionSlug ?? (group.optionId != null ? options.matrix?.optionById.get(String(group.optionId))?.slug : void 0);
+    if (optionSlug) {
+      params.set(`opt.${optionSlug}`, group.optionValueSlug);
+    }
+  }
+  return params.size > 0 ? `${path}?${params.toString()}` : path;
+}
+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) - (variant.reservedStock ?? 0) > 0;
+}
+function sortVariantsForMediaSelection(variants) {
+  const orderedVariants = [...variants].sort(compareVariantOrder);
+  const activeVariants = orderedVariants.filter(
+    (variant) => variant.isActive !== false
+  );
+  const availableVariants = activeVariants.filter(isVariantAvailableForSale);
+  const unavailableActiveVariants = activeVariants.filter(
+    (variant) => !isVariantAvailableForSale(variant)
+  );
+  return [...availableVariants, ...unavailableActiveVariants];
+}
+function variantHasPoolMedia(variant, productMediaPool) {
+  if (!variant?.images?.length) return false;
+  return variant.images.some((image) => {
+    const imageId = getRelationID(image);
+    return Boolean(
+      imageId && productMediaPool.some((poolItem) => getRelationID(poolItem) === imageId)
+    );
+  });
+}
+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 productMediaPool = product?.images ?? [];
+  const selectionHintHasPoolMedia = variantHasPoolMedia(
+    selectionHintVariant,
+    productMediaPool
+  );
+  const mediaSelectionVariants = sortVariantsForMediaSelection(variants);
+  const resolvedProductMedia = resolveProductSelectionMedia({
+    productMediaPool,
+    productPrimaryMediaItemId: getRelationID(product?.primaryMediaItemId),
+    selectedVariant: selectionHintVariant && selectionHintHasPoolMedia ? {
+      id: selectionHintVariant.id,
+      images: selectionHintVariant.images
+    } : null,
+    matchingVariants: selectionHintHasPoolMedia ? [] : mediaSelectionVariants
+  });
+  return {
+    selectionHintVariant: getRelationID(selectionHintVariant?.id) ?? null,
+    primaryImage: resolveGenericListingPrimaryImage(
+      product,
+      resolvedProductMedia.primaryImage,
+      resolvedProductMedia.source
+    ),
+    minPrice,
+    maxPrice,
+    minCompareAtPrice,
+    maxCompareAtPrice,
+    isPriceRange: minPrice !== null && maxPrice !== null ? minPrice !== maxPrice : false,
+    availableForSale: availableVariants.length > 0
+  };
+}
+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 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 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 swatches = groups.length > 1 ? groups.map((group) => buildListingSwatch(product, group, options)) : [];
+  return {
+    id: String(product.id),
+    href: buildProductHref(
+      { slug: product.slug },
+      { listing: { selectionHintVariant } },
+      options
+    ),
+    title: product.title,
+    representativeVariant,
+    primaryImage: listingPrimaryMedia,
+    priceRange,
+    availableForSale,
+    swatches
+  };
+}
+function getProductListingCardVariants(item) {
+  const productVariants = item.product.variants?.docs;
+  if (Array.isArray(productVariants) && productVariants.length > 0) {
+    return productVariants;
+  }
+  const variants = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const group of item.groups) {
+    for (const variant of group.variants) {
+      const id = getRelationID(variant.id);
+      if (id && seen.has(id)) continue;
+      if (id) seen.add(id);
+      variants.push(variant);
+    }
+  }
+  return variants;
+}
+function findListingCardRepresentativeVariant(variants, representativeVariantId) {
+  if (representativeVariantId == null) return null;
+  return variants.find(
+    (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 resolveListingCardPriceRange(product, projectedListing, groups) {
+  const listing = product.listing;
+  if (hasCompleteListingPriceProjection(listing)) {
+    const groupRange = groups.length > 0 ? aggregateListingPriceRange(groups) : null;
+    const definesCompareAt = listingDefinesCompareAtProjection(listing);
+    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
+    };
+  }
+  if (groups.length > 0) {
+    return aggregateListingPriceRange(groups);
+  }
+  return {
+    minPrice: projectedListing.minPrice,
+    maxPrice: projectedListing.maxPrice,
+    minCompareAtPrice: projectedListing.minCompareAtPrice,
+    maxCompareAtPrice: projectedListing.maxCompareAtPrice,
+    isPriceRange: projectedListing.isPriceRange
+  };
+}
+function aggregateListingPriceRange(groups) {
+  const minPrice = minOfNullable(groups.map((g) => g.listing.minPrice));
+  const maxPrice = maxOfNullable(groups.map((g) => g.listing.maxPrice));
+  const minCompareAtPrice = minOfNullable(
+    groups.map((g) => g.listing.minCompareAtPrice)
+  );
+  const maxCompareAtPrice = maxOfNullable(
+    groups.map((g) => g.listing.maxCompareAtPrice)
+  );
+  const isPriceRange = minPrice !== null && maxPrice !== null && minPrice !== maxPrice;
+  return {
+    minPrice,
+    maxPrice,
+    minCompareAtPrice,
+    maxCompareAtPrice,
+    isPriceRange
+  };
+}
+function buildListingSwatch(product, group, options) {
+  return {
+    optionId: group.optionId,
+    optionValueId: group.optionValueId,
+    label: group.optionValueLabel,
+    swatch: group.optionValueSwatch ?? null,
+    href: buildProductHref(
+      { slug: product.slug },
+      {
+        optionId: group.optionId,
+        optionSlug: group.optionSlug,
+        optionValueId: group.optionValueId,
+        optionValueSlug: group.optionValueSlug,
+        listing: group.listing
+      },
+      options
+    ),
+    availableForSale: group.listing.availableForSale
+  };
+}
+function minOfNullable(values) {
+  const numbers = values.filter((v) => v !== null);
+  return numbers.length === 0 ? null : Math.min(...numbers);
+}
+function maxOfNullable(values) {
+  const numbers = values.filter((v) => v !== null);
+  return numbers.length === 0 ? null : Math.max(...numbers);
+}
+
 // src/core/api/product-api.ts
 var PRODUCT_DETAIL_UNAVAILABLE_REASONS = /* @__PURE__ */ new Set([
   "not_found",
@@ -1651,13 +2732,71 @@ function productDetailResultFromError(error) {
   if (!reason) return void 0;
   return { found: false, reason };
 }
+function nonEmpty(values) {
+  return values?.length ? values : void 0;
+}
+function buildProductListingPageWhere(params) {
+  const clauses = [];
+  const search = params.search?.trim();
+  if (search) {
+    clauses.push({
+      or: [
+        { title: { like: search } },
+        { slug: { like: search } },
+        { handle: { like: search } }
+      ]
+    });
+  }
+  const filters = params.filters;
+  const ids = nonEmpty(filters?.ids);
+  if (ids) clauses.push({ id: { in: ids } });
+  const slugs = nonEmpty(filters?.slugs);
+  if (slugs) clauses.push({ slug: { in: slugs } });
+  const handles = nonEmpty(filters?.handles);
+  if (handles) clauses.push({ handle: { in: handles } });
+  const categoryIds = nonEmpty(filters?.categoryIds);
+  if (categoryIds) clauses.push({ categories: { in: categoryIds } });
+  const tagIds = nonEmpty(filters?.tagIds);
+  if (tagIds) clauses.push({ tags: { in: tagIds } });
+  const minPrice = filters?.price?.min;
+  if (minPrice != null) {
+    clauses.push({ "listing.maxPrice": { greater_than_equal: minPrice } });
+  }
+  const maxPrice = filters?.price?.max;
+  if (maxPrice != null) {
+    clauses.push({ "listing.minPrice": { less_than_equal: maxPrice } });
+  }
+  if (filters?.availableForSale != null) {
+    clauses.push({
+      "listing.availableForSale": { equals: filters.availableForSale }
+    });
+  }
+  if (clauses.length === 0) return void 0;
+  if (clauses.length === 1) return clauses[0];
+  return { and: clauses };
+}
+function buildProductListingPageUrl(params) {
+  const options = {
+    page: params.page,
+    limit: params.limit,
+    sort: params.sort,
+    where: buildProductListingPageWhere(params)
+  };
+  return params.mode === "full" ? listingGroupsQueryUrl(options) : listingGroupsQueryCatalogUrl(options);
+}
+function withProductListingCards(response, options) {
+  return {
+    ...response,
+    cards: response.docs.map((item) => buildProductListingCard(item, options))
+  };
+}
 function rejectLegacyOptionValueSwatchColor(value) {
   if (Object.prototype.hasOwnProperty.call(
     value,
     "swatchColor"
   )) {
     throw new TypeError(
-      'Product upsert option values no longer accept legacy flat "swatchColor"; use nested "swatch" instead.'
+      'Product upsert option values no longer accept removed flat "swatchColor"; use nested "swatch" instead.'
     );
   }
 }
@@ -1715,6 +2854,14 @@ var ProductApi = class extends BaseApi {
       { method: "GET" }
     );
   }
+  async listingPage(params = {}) {
+    if (params.mode === "full") {
+      const response2 = await this.request(buildProductListingPageUrl(params), void 0, { method: "GET" });
+      return withProductListingCards(response2, params);
+    }
+    const response = await this.request(buildProductListingPageUrl(params), void 0, { method: "GET" });
+    return withProductListingCards(response, params);
+  }
   /**
    * Fetch full product detail by slug or id.
    * Returns a discriminated result so storefronts can distinguish missing,
@@ -1986,6 +3133,7 @@ var ServerCommerceClient = class {
     this.product = {
       stockCheck: productApi.stockCheck.bind(productApi),
       listingGroups: productApi.listingGroups.bind(productApi),
+      listingPage: productApi.listingPage.bind(productApi),
       detail: productApi.detail.bind(productApi),
       previewDetail: productApi.previewDetail.bind(productApi),
       upsert: productApi.upsert.bind(productApi)