@01.software/sdk 0.27.0 → 0.29.0

package/dist/index.js

@@ -1141,6 +1141,7 @@ var INTERNAL_COLLECTIONS = [
   "analytics-event-schemas",
   "subscriptions",
   "billing-history",
+  "inventory-reservations",
   "order-status-logs",
   "api-keys",
   "personal-access-tokens",
@@ -1181,8 +1182,8 @@ var COLLECTIONS = [
   "carts",
   "cart-items",
   "discounts",
-  "promotions",
   "shipping-policies",
+  "shipping-zones",
   "documents",
   "document-categories",
   "document-types",
@@ -1851,7 +1852,15 @@ var CommerceClient = class {
     };
     this.product = {
       stockCheck: (params) => execute("/api/products/stock-check", params),
-      listingGroups: (params) => execute("/api/products/listing-groups", params)
+      listingGroups: (params) => execute("/api/products/listing-groups", params),
+      detail: async (params) => {
+        try {
+          return await execute("/api/products/detail", params);
+        } catch (err) {
+          if (err instanceof NotFoundError) return null;
+          throw err;
+        }
+      }
     };
     this.cart = {
       get: cartApi.getCart.bind(cartApi),
@@ -1894,6 +1903,29 @@ var ProductApi = class extends BaseApi {
       params
     );
   }
+  /**
+   * Fetch full product detail by slug or id.
+   * Returns `null` on 404 regardless of reason (`not_found` / `not_published` /
+   * `tenant_mismatch` / `feature_disabled`). For the reason behind a null,
+   * inspect `client.lastRequestId` against backend logs.
+   */
+  async detail(params) {
+    try {
+      return await this.request("/api/products/detail", params);
+    } catch (err) {
+      if (err instanceof NotFoundError) return null;
+      throw err;
+    }
+  }
+  /**
+   * Atomically create or update a product together with its options,
+   * option-values, and variants in a single transaction. Mirrors Shopify's
+   * `productSet` shape and is the canonical write path for the MCP
+   * `product-upsert` tool.
+   */
+  upsert(params) {
+    return this.request("/api/products/upsert", params);
+  }
 };
 
 // src/core/api/discount-api.ts
@@ -1986,7 +2018,9 @@ var ServerCommerceClient = class {
     const orderApi = new OrderApi(serverOptions);
     this.product = {
       stockCheck: productApi.stockCheck.bind(productApi),
-      listingGroups: productApi.listingGroups.bind(productApi)
+      listingGroups: productApi.listingGroups.bind(productApi),
+      detail: productApi.detail.bind(productApi),
+      upsert: productApi.upsert.bind(productApi)
     };
     this.cart = {
       get: cartApi.getCart.bind(cartApi),
@@ -2088,10 +2122,24 @@ var customerKeys = {
 };
 var productKeys = {
   listingGroups: (options) => ["products", "listing-groups", "list", options],
-  listingGroupsInfinite: (options) => ["products", "listing-groups", "infinite", options]
+  listingGroupsInfinite: (options) => ["products", "listing-groups", "infinite", options],
+  detail: (params) => ["products", "detail", params],
+  detailAll: () => ["products", "detail"]
 };
 
 // src/core/query/collection-hooks.ts
+var PRODUCT_DETAIL_INVALIDATING_COLLECTIONS = /* @__PURE__ */ new Set([
+  "products",
+  "product-variants",
+  "product-options",
+  "product-option-values",
+  "product-categories",
+  "product-tags",
+  "product-collections",
+  "brands",
+  "brand-logos",
+  "images"
+]);
 var DEFAULT_PAGE_SIZE = 20;
 var CollectionHooks = class {
   constructor(queryClient, collectionClient) {
@@ -2249,6 +2297,9 @@ var CollectionHooks = class {
         this.queryClient.invalidateQueries({
           queryKey: collectionKeys(collection).all
         });
+        if (PRODUCT_DETAIL_INVALIDATING_COLLECTIONS.has(collection)) {
+          this.queryClient.invalidateQueries({ queryKey: ["products", "detail"] });
+        }
         options?.onSuccess?.(data);
       },
       onError: options?.onError,
@@ -2269,6 +2320,9 @@ var CollectionHooks = class {
         this.queryClient.invalidateQueries({
           queryKey: collectionKeys(collection).all
         });
+        if (PRODUCT_DETAIL_INVALIDATING_COLLECTIONS.has(collection)) {
+          this.queryClient.invalidateQueries({ queryKey: ["products", "detail"] });
+        }
         options?.onSuccess?.(data);
       },
       onError: options?.onError,
@@ -2285,6 +2339,9 @@ var CollectionHooks = class {
         this.queryClient.invalidateQueries({
           queryKey: collectionKeys(collection).all
         });
+        if (PRODUCT_DETAIL_INVALIDATING_COLLECTIONS.has(collection)) {
+          this.queryClient.invalidateQueries({ queryKey: ["products", "detail"] });
+        }
         options?.onSuccess?.(data);
       },
       onError: options?.onError,
@@ -2440,7 +2497,7 @@ var CustomerHooks = class {
 
 // src/core/query/query-hooks.ts
 var QueryHooks = class extends CollectionHooks {
-  constructor(queryClient, collectionClient, customerAuth) {
+  constructor(queryClient, collectionClient, customerAuth, commerceClient) {
     super(queryClient, collectionClient);
     // --- Customer hooks delegation ---
     this.useCustomerMe = (...args) => this._customer.useCustomerMe(...args);
@@ -2457,6 +2514,7 @@ var QueryHooks = class extends CollectionHooks {
     this.getCustomerData = () => this._customer.getCustomerData();
     this.setCustomerData = (data) => this._customer.setCustomerData(data);
     this._customer = new CustomerHooks(queryClient, customerAuth);
+    this._commerce = commerceClient;
   }
   useProductListingGroupsQuery(params, options) {
     const queryOptions = params.options;
@@ -2550,6 +2608,21 @@ var QueryHooks = class extends CollectionHooks {
       staleTime: options?.staleTime
     });
   }
+  useProductDetail(params, options) {
+    const discriminator = "slug" in params ? params.slug : params.id;
+    const enabled = options?.enabled !== false && Boolean(discriminator);
+    return useQueryOriginal3({
+      queryKey: productKeys.detail(params),
+      queryFn: () => this._commerce.product.detail(params),
+      enabled
+    });
+  }
+  useProductDetailBySlug(slug, options) {
+    return this.useProductDetail({ slug }, options);
+  }
+  useProductDetailById(id, options) {
+    return this.useProductDetail({ id }, options);
+  }
 };
 
 // src/core/client/client.ts
@@ -2612,7 +2685,8 @@ var Client = class {
     this.query = new QueryHooks(
       this.queryClient,
       collectionClient,
-      this.customer.auth
+      this.customer.auth,
+      this.commerce
     );
   }
   getState() {
@@ -2674,7 +2748,7 @@ var ServerClient = class {
       onRequestId
     );
     this.queryClient = getQueryClient();
-    this.query = new QueryHooks(this.queryClient, this.collections);
+    this.query = new QueryHooks(this.queryClient, this.collections, void 0, this.commerce);
   }
   getState() {
     return { ...this.state };
@@ -2951,6 +3025,13 @@ function createTypedWebhookHandler(collection, handler) {
 }
 
 // src/utils/ecommerce.ts
+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);
@@ -2997,10 +3078,11 @@ function getFirstAvailableVariantPrimaryImage(variants) {
   }
   return null;
 }
-function normalizeOptionValue(value, fallbackOptionId) {
+function normalizeOptionValue(value, fallbackOptionId, fallbackOptionSlug) {
   return {
     id: String(value.id),
     optionId: getRelationID(value.option) ?? fallbackOptionId,
+    optionSlug: fallbackOptionSlug,
     label: value.value || value.slug || String(value.id),
     slug: value.slug ?? null,
     swatchColor: value.swatchColor ?? null,
@@ -3009,20 +3091,26 @@ function normalizeOptionValue(value, fallbackOptionId) {
     order: value._order ?? value["_product-option-values_values_order"] ?? ""
   };
 }
-function normalizeVariantOptionValues(variant, valueToOptionId, optionIds) {
+function normalizeVariantOptionValues(variant, optionById, valueToOptionId, optionIds) {
   const optionValueByOptionId = /* @__PURE__ */ new Map();
+  const optionValueByOptionSlug = /* @__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 optionSlug = optionById.get(optionId)?.slug;
+    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
   };
 }
@@ -3032,17 +3120,20 @@ function buildProductOptionMatrix({
 }) {
   const normalizedOptions = options.map((option) => {
     const valuesById = /* @__PURE__ */ new Map();
+    const optionSlug = option.slug ?? String(option.id);
     for (const rawValue of option.values?.docs ?? []) {
       if (!isProductOptionValueDoc(rawValue)) continue;
       const normalizedValue = normalizeOptionValue(
         rawValue,
-        String(option.id)
+        String(option.id),
+        optionSlug
       );
       valuesById.set(normalizedValue.id, normalizedValue);
     }
     return {
       id: String(option.id),
       title: option.title ?? String(option.id),
+      slug: optionSlug,
       order: option._order ?? option["_product-options_options_order"] ?? "",
       values: Array.from(valuesById.values()).sort(
         (left, right) => compareOrder(left.order, right.order)
@@ -3052,24 +3143,113 @@ function buildProductOptionMatrix({
   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 = variants.map(
-    (variant) => normalizeVariantOptionValues(variant, valueToOptionId, optionIds)
+    (variant) => normalizeVariantOptionValues(
+      variant,
+      optionById,
+      valueToOptionId,
+      optionIds
+    )
+  );
+  return {
+    options: normalizedOptions,
+    optionIds,
+    optionSlugs,
+    optionById,
+    optionBySlug,
+    valueById,
+    valueToOptionId,
+    valueToOptionSlug,
+    variants: normalizedVariants
+  };
+}
+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,
+      swatchColor: value.swatchColor ?? null,
+      thumbnail: value.thumbnail ?? null,
+      images: value.images ?? null,
+      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
   };
 }
@@ -3102,7 +3282,7 @@ function getAvailableOptionValues(matrix, optionId, selectedValueIds) {
     )
   );
   const availableValueIds = new Set(
-    matchingVariants.map((variant) => variant.optionValueByOptionId.get(optionId)).filter((valueId) => Boolean(valueId))
+    matchingVariants.filter((variant) => variant.source.isActive !== false).map((variant) => variant.optionValueByOptionId.get(optionId)).filter((valueId) => Boolean(valueId))
   );
   return option.values.filter((value) => availableValueIds.has(value.id));
 }
@@ -3117,6 +3297,432 @@ function resolveVariantForSelection(matrix, selectedValueIds) {
     )
   );
 }
+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;
+  const normalizedValueId = String(valueId);
+  if (matrix.valueToOptionId.get(normalizedValueId) !== optionId) return;
+  selectedByOptionId.set(optionId, normalizedValueId);
+}
+function assignSelectedValueSlugByOptionId(matrix, selectedByOptionId, optionId, valueSlug) {
+  if (!valueSlug) return;
+  const option = matrix.optionById.get(optionId);
+  if (!option) return;
+  const value = option.values.find((candidate) => candidate.slug === valueSlug);
+  if (!value) return;
+  selectedByOptionId.set(optionId, value.id);
+}
+function assignSelectedValueSlugByOptionSlug(matrix, selectedByOptionId, optionSlug, valueSlug) {
+  if (!valueSlug) return;
+  const option = matrix.optionBySlug.get(optionSlug);
+  if (!option) return;
+  const value = option.values.find((candidate) => candidate.slug === valueSlug);
+  if (!value) return;
+  selectedByOptionId.set(option.id, value.id);
+}
+function requireValueSlug(value) {
+  if (value.slug) return value.slug;
+  throw new ProductSelectionCodecError(
+    `Option value "${value.id}" does not have a slug and cannot be used in product selection URLs.`
+  );
+}
+function requireOptionSlug(option) {
+  if (option.slug) return option.slug;
+  throw new ProductSelectionCodecError(
+    `Option "${option.id}" does not have a slug and cannot be used in product selection URLs.`
+  );
+}
+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();
+  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.<optionSlug>=<valueSlug>.`
+        );
+      }
+      if (!value) {
+        throw new ProductSelectionCodecError(
+          `Product selection query parameter "${key}" requires a value slug.`
+        );
+      }
+      continue;
+    }
+    const keyToken = slugLike(key);
+    if (knownSelectionKeys.has(keyToken) || value === "" && knownSelectionKeys.has(keyToken)) {
+      throw new ProductSelectionCodecError(
+        `Ambiguous product selection query parameter "${key}". Use opt.<optionSlug>=<valueSlug>.`
+      );
+    }
+  }
+}
+function emitLegacyOptionIdParam(options, event) {
+  try {
+    options?.onLegacyOptionIdParam?.(event);
+  } catch {
+  }
+}
+function assignSearchSelection(matrix, selectedByOptionId, search, options) {
+  if (!search) return;
+  const params = toSearchParams(search);
+  assertNoAmbiguousSelectionParams(matrix, params);
+  for (const [key, valueSlug] of params.entries()) {
+    if (!key.startsWith("opt.")) continue;
+    const optionToken = key.slice(4);
+    const optionBySlug = matrix.optionBySlug.get(optionToken);
+    if (optionBySlug) {
+      assignSelectedValueSlugByOptionSlug(
+        matrix,
+        selectedByOptionId,
+        optionBySlug.slug,
+        valueSlug
+      );
+      continue;
+    }
+    const legacyOption = matrix.optionById.get(optionToken);
+    if (!legacyOption) continue;
+    const before = selectedByOptionId.get(legacyOption.id);
+    assignSelectedValueSlugByOptionId(
+      matrix,
+      selectedByOptionId,
+      legacyOption.id,
+      valueSlug
+    );
+    if (selectedByOptionId.get(legacyOption.id) !== before) {
+      emitLegacyOptionIdParam(options, {
+        optionId: legacyOption.id,
+        optionSlug: legacyOption.slug,
+        valueSlug,
+        searchParam: key
+      });
+    }
+  }
+}
+function normalizeProductSelection(detail, selection = {}, options) {
+  const matrix = buildProductOptionMatrixFromDetail(detail);
+  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);
+  }
+  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
+  };
+}
+function parseProductSelection(detail, search, options) {
+  return normalizeProductSelection(detail, { search }, options);
+}
+function stringifyProductSelection(detail, selection = {}, options) {
+  const matrix = buildProductOptionMatrixFromDetail(detail);
+  const normalized = normalizeProductSelection(detail, selection, options);
+  const params = new URLSearchParams();
+  for (const optionId of matrix.optionIds) {
+    const valueId = normalized.byOptionId[optionId];
+    if (!valueId) continue;
+    const option = matrix.optionById.get(optionId);
+    const value = matrix.valueById.get(valueId);
+    if (!option || !value) continue;
+    params.append(`opt.${requireOptionSlug(option)}`, requireValueSlug(value));
+  }
+  return params.toString();
+}
+function createProductSelectionCodec(detail, options) {
+  return {
+    parse: (search) => parseProductSelection(detail, search, options),
+    stringify: (selection = {}) => stringifyProductSelection(detail, selection, options)
+  };
+}
+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 activeVariantEntries(variants) {
+  return variants.filter((variant) => variant.source.isActive !== false);
+}
+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 buildSelectionPrice(variants) {
+  const { min, max } = getMinMax(variants.map((variant) => variant.price));
+  const { min: compareAtMin, max: compareAtMax } = getMinMax(
+    variants.map((variant) => variant.compareAtPrice)
+  );
+  return {
+    min,
+    max,
+    compareAtMin,
+    compareAtMax,
+    isRange: min !== null && max !== null ? min !== max : false
+  };
+}
+function firstMedia(value) {
+  if (value == null) return null;
+  if (Array.isArray(value)) return firstMedia(value[0]);
+  return value;
+}
+function isPresentMedia(value) {
+  return value != null;
+}
+function mediaArray(values) {
+  if (!Array.isArray(values)) return [];
+  return values.filter(isPresentMedia);
+}
+function buildSelectionMedia(detail, selectedVariant, matchingVariants, selectedValues) {
+  const selectedValueImages = selectedValues.flatMap(
+    (value) => mediaArray(value.images)
+  );
+  const selectedValuePrimary = selectedValues.map((value) => firstMedia(value.thumbnail) ?? firstMedia(value.images)).find((value) => value != null) ?? null;
+  const selectedVariantPrimary = firstMedia(selectedVariant?.thumbnail) ?? firstMedia(selectedVariant?.images);
+  const matchingVariantPrimary = matchingVariants.map(
+    (variant) => firstMedia(variant.thumbnail) ?? firstMedia(variant.images)
+  ).find((value) => value != null) ?? null;
+  const detailImages = mediaArray(detail.images);
+  const primaryImage = selectedVariantPrimary ?? selectedValuePrimary ?? firstMedia(detail.listing.primaryImage) ?? matchingVariantPrimary ?? firstMedia(detailImages);
+  const images = mediaArray(selectedVariant?.images).length > 0 ? mediaArray(selectedVariant?.images) : selectedValueImages.length > 0 ? selectedValueImages : detailImages;
+  return {
+    primaryImage,
+    images
+  };
+}
+function buildSelectionStock(selectedVariant, matchingVariants) {
+  if (selectedVariant) {
+    const availableStock = selectedVariant.isUnlimited ? null : Math.max(0, selectedVariant.stock - selectedVariant.reservedStock);
+    const isActive = selectedVariant.isActive !== false;
+    return {
+      availableForSale: isActive && (selectedVariant.isUnlimited || (availableStock ?? 0) > 0),
+      isUnlimited: selectedVariant.isUnlimited,
+      stock: selectedVariant.stock,
+      reservedStock: selectedVariant.reservedStock,
+      availableStock
+    };
+  }
+  return {
+    availableForSale: matchingVariants.some(isVariantAvailableForSale),
+    isUnlimited: matchingVariants.some((variant) => variant.isUnlimited),
+    stock: null,
+    reservedStock: null,
+    availableStock: null
+  };
+}
+function resolveProductSelection(detail, selection = {}, options) {
+  const matrix = buildProductOptionMatrixFromDetail(detail);
+  const effectiveSelection = hasExplicitSelection(selection) || detail.listing.selectionHintVariant == null ? selection : { ...selection, variantId: detail.listing.selectionHintVariant };
+  const normalizedSelection = normalizeProductSelection(
+    detail,
+    effectiveSelection,
+    options
+  );
+  const matchingVariantEntries = getMatchingVariantEntries(
+    matrix,
+    normalizedSelection
+  );
+  const activeMatchingVariantEntries = activeVariantEntries(
+    matchingVariantEntries
+  );
+  const selectedVariantEntry = getExactSelectedVariantEntry(
+    matrix,
+    normalizedSelection,
+    matchingVariantEntries
+  );
+  const selectedVariant = selectedVariantEntry?.source ?? null;
+  const matchingVariants = activeMatchingVariantEntries.map(
+    (variant) => variant.source
+  );
+  const selectedValues = matrix.optionIds.map((optionId) => normalizedSelection.byOptionId[optionId]).map((valueId) => valueId ? matrix.valueById.get(valueId) : void 0).filter((value) => value !== void 0);
+  const availableValuesByOptionId = Object.fromEntries(
+    matrix.options.map((option) => {
+      const availableValueIds = new Set(
+        getAvailableOptionValues(
+          matrix,
+          option.id,
+          normalizedSelection.valueIds
+        ).map((value) => value.id)
+      );
+      return [
+        option.id,
+        option.values.map((value) => ({
+          valueId: value.id,
+          value: value.label,
+          slug: requireValueSlug(value),
+          selected: normalizedSelection.byOptionId[option.id] === value.id,
+          available: availableValueIds.has(value.id),
+          swatchColor: value.swatchColor ?? null,
+          thumbnail: value.thumbnail ?? null,
+          images: value.images ?? null
+        }))
+      ];
+    })
+  );
+  const availableValuesByOptionSlug = Object.fromEntries(
+    matrix.options.map((option) => [
+      option.slug,
+      availableValuesByOptionId[option.id] ?? []
+    ])
+  );
+  const allOptionsSelected = matrix.optionIds.every(
+    (optionId) => Boolean(normalizedSelection.byOptionId[optionId])
+  );
+  const priceVariants = selectedVariant ? [selectedVariant] : matchingVariants;
+  return {
+    normalizedSelection,
+    selectedVariant,
+    matchingVariants,
+    partialVariants: selectedVariant ? [] : matchingVariants,
+    availableValuesByOptionSlug,
+    availableValuesByOptionId,
+    allOptionsSelected,
+    price: buildSelectionPrice(priceVariants),
+    media: buildSelectionMedia(
+      detail,
+      selectedVariant,
+      matchingVariants,
+      selectedValues
+    ),
+    stock: buildSelectionStock(selectedVariant, matchingVariants)
+  };
+}
 function compareVariantOrder(a, b) {
   const aOrder = Number(a._order ?? Number.MAX_SAFE_INTEGER);
   const bOrder = Number(b._order ?? Number.MAX_SAFE_INTEGER);
@@ -3524,6 +4130,7 @@ export {
   OrderApi,
   PermissionError,
   ProductApi,
+  ProductSelectionCodecError,
   QueryHooks,
   RateLimitError,
   ReadOnlyCollectionClient,
@@ -3543,6 +4150,7 @@ export {
   buildProductListingGroupsByOption,
   buildProductListingProjection,
   buildProductOptionMatrix,
+  buildProductOptionMatrixFromDetail,
   collectionKeys,
   createAnalytics,
   createAuthError,
@@ -3551,6 +4159,7 @@ export {
   createCustomerAuthWebhookHandler,
   createNotFoundError,
   createPermissionError,
+  createProductSelectionCodec,
   createRateLimitError,
   createServerClient,
   createTypedWebhookHandler,
@@ -3587,9 +4196,13 @@ export {
   isUsageLimitError,
   isValidWebhookEvent,
   isValidationError,
+  normalizeProductSelection,
   normalizeSelectedValueIds,
+  parseProductSelection,
   productKeys,
+  resolveProductSelection,
   resolveRelation,
-  resolveVariantForSelection
+  resolveVariantForSelection,
+  stringifyProductSelection
 };
 //# sourceMappingURL=index.js.map