@01.software/sdk 0.32.0 → 0.34.0

package/dist/index.cjs

@@ -24,6 +24,9 @@ __export(src_exports, {
   AuthError: () => AuthError,
   BaseApi: () => BaseApi,
   COLLECTIONS: () => COLLECTIONS,
+  COMMERCE_NOTIFICATION_EVENTS: () => COMMERCE_NOTIFICATION_EVENTS,
+  COMMERCE_NOTIFICATION_EVENT_TYPE: () => COMMERCE_NOTIFICATION_EVENT_TYPE,
+  COMMERCE_NOTIFICATION_OPERATION: () => COMMERCE_NOTIFICATION_OPERATION,
   CUSTOMER_PASSWORD_RESET_OPERATION: () => CUSTOMER_PASSWORD_RESET_OPERATION,
   CartApi: () => CartApi,
   CommerceClient: () => CommerceClient,
@@ -33,6 +36,7 @@ __export(src_exports, {
   CustomerAuth: () => CustomerAuth,
   CustomerNamespace: () => CustomerNamespace,
   DiscountApi: () => DiscountApi,
+  EventsClient: () => EventsClient,
   GoneError: () => GoneError,
   IMAGE_SIZES: () => IMAGE_SIZES,
   INTERNAL_COLLECTIONS: () => INTERNAL_COLLECTIONS,
@@ -40,6 +44,8 @@ __export(src_exports, {
   NotFoundError: () => NotFoundError,
   ORDER_CHANGED_EVENT_TYPE: () => ORDER_CHANGED_EVENT_TYPE,
   OrderApi: () => OrderApi,
+  PRODUCT_UPSERT_READONLY_FIELD_REASON: () => PRODUCT_UPSERT_READONLY_FIELD_REASON,
+  PRODUCT_UPSERT_UNKNOWN_FIELD_REASON: () => PRODUCT_UPSERT_UNKNOWN_FIELD_REASON,
   PermissionError: () => PermissionError,
   ProductApi: () => ProductApi,
   ProductSelectionCodecError: () => ProductSelectionCodecError,
@@ -62,6 +68,7 @@ __export(src_exports, {
   createAnalytics: () => createAnalytics,
   createAuthError: () => createAuthError,
   createClient: () => createClient2,
+  createCommerceEmailWebhookHandler: () => createCommerceEmailWebhookHandler,
   createConflictError: () => createConflictError,
   createCustomerAuthWebhookHandler: () => createCustomerAuthWebhookHandler,
   createNotFoundError: () => createNotFoundError,
@@ -69,9 +76,11 @@ __export(src_exports, {
   createProductSelectionCodec: () => createProductSelectionCodec,
   createRateLimitError: () => createRateLimitError,
   createTypedWebhookHandler: () => createTypedWebhookHandler,
+  defineCommerceEmailConfig: () => defineCommerceEmailConfig,
   formatOrderName: () => formatOrderName,
   generateOrderNumber: () => generateOrderNumber,
   getAvailableOptionValues: () => getAvailableOptionValues,
+  getCommerceNotificationIdempotencyKey: () => getCommerceNotificationIdempotencyKey,
   getImageLqip: () => getImageLqip,
   getImagePalette: () => getImagePalette,
   getImagePlaceholderStyle: () => getImagePlaceholderStyle,
@@ -87,6 +96,7 @@ __export(src_exports, {
   handleWebhook: () => handleWebhook,
   isApiError: () => isApiError,
   isAuthError: () => isAuthError,
+  isCommerceNotificationWebhookEvent: () => isCommerceNotificationWebhookEvent,
   isConfigError: () => isConfigError,
   isConflictError: () => isConflictError,
   isCustomerPasswordResetWebhookEvent: () => isCustomerPasswordResetWebhookEvent,
@@ -95,6 +105,7 @@ __export(src_exports, {
   isNotFoundError: () => isNotFoundError,
   isOrderChangedWebhookEvent: () => isOrderChangedWebhookEvent,
   isPermissionError: () => isPermissionError,
+  isProductUpsertFieldValidationErrorBody: () => isProductUpsertFieldValidationErrorBody,
   isRateLimitError: () => isRateLimitError,
   isSDKError: () => isSDKError,
   isServiceUnavailableError: () => isServiceUnavailableError,
@@ -104,14 +115,22 @@ __export(src_exports, {
   isValidationError: () => isValidationError,
   isWebhookCollection: () => isWebhookCollection,
   isWebhookOperation: () => isWebhookOperation,
+  mergeProductDetailWithStock: () => mergeProductDetailWithStock,
   normalizeProductSelection: () => normalizeProductSelection,
   normalizeProductSelectionFromMatrix: () => normalizeProductSelectionFromMatrix,
   normalizeSelectedValueIds: () => normalizeSelectedValueIds,
   parseProductSelection: () => parseProductSelection,
+  resolveListingPrimaryImagePointer: () => resolveListingPrimaryImagePointer,
+  resolveProductDisplayMedia: () => resolveProductDisplayMedia,
+  resolveProductGallery: () => resolveProductGallery,
+  resolveProductMedia: () => resolveProductMedia,
   resolveProductSelection: () => resolveProductSelection,
   resolveProductSelectionFromMatrix: () => resolveProductSelectionFromMatrix,
+  resolveProductSelectionMedia: () => resolveProductSelectionMedia,
   resolveRelation: () => resolveRelation,
   resolveVariantForSelection: () => resolveVariantForSelection,
+  selectNext: () => selectNext,
+  selectedSwatchMediaItemId: () => selectedSwatchMediaItemId,
   stringifyProductSelection: () => stringifyProductSelection
 });
 module.exports = __toCommonJS(src_exports);
@@ -371,9 +390,12 @@ function resolveApiUrl(apiUrl) {
 
 // src/core/internal/utils/http.ts
 var DEFAULT_TIMEOUT = 3e4;
+var STOREFRONT_BROWSER_TIMEOUT = 15e3;
 var DEFAULT_RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504];
 var NON_RETRYABLE_STATUSES = [400, 401, 403, 404, 409, 422];
 var SAFE_METHODS = ["GET", "HEAD", "OPTIONS"];
+var DEFAULT_MAX_RETRIES = 3;
+var STOREFRONT_BROWSER_MAX_RETRIES = 1;
 function debugLog(debug, type, message, data) {
   if (!debug) return;
   const shouldLog = debug === true || type === "request" && debug.logRequests || type === "response" && debug.logResponses || type === "error" && debug.logErrors;
@@ -566,15 +588,18 @@ async function httpFetch(url, options) {
     publishableKey,
     secretKey,
     customerToken,
-    timeout = DEFAULT_TIMEOUT,
+    timeout: timeoutOption = DEFAULT_TIMEOUT,
     debug,
     retry,
     onUnauthorized,
     ...requestInit
   } = options || {};
   const baseUrl = resolveApiUrl(apiUrl);
+  const method = (requestInit.method || "GET").toUpperCase();
+  const isPublishableKeyBrowserGet = typeof window !== "undefined" && !secretKey && !customerToken && Boolean(publishableKey) && SAFE_METHODS.includes(method);
+  const timeout = timeoutOption === DEFAULT_TIMEOUT && isPublishableKeyBrowserGet ? STOREFRONT_BROWSER_TIMEOUT : timeoutOption;
   const retryConfig = {
-    maxRetries: retry?.maxRetries ?? 3,
+    maxRetries: retry?.maxRetries ?? (isPublishableKeyBrowserGet ? STOREFRONT_BROWSER_MAX_RETRIES : DEFAULT_MAX_RETRIES),
     retryableStatuses: retry?.retryableStatuses ?? DEFAULT_RETRYABLE_STATUSES,
     retryDelay: retry?.retryDelay ?? ((attempt) => Math.min(1e3 * 2 ** attempt, 1e4))
   };
@@ -682,8 +707,8 @@ async function httpFetch(url, options) {
           ),
           requestId
         );
-        const method = (requestInit.method || "GET").toUpperCase();
-        if (attempt < retryConfig.maxRetries && SAFE_METHODS.includes(method) && retryConfig.retryableStatuses.includes(response.status)) {
+        const method2 = (requestInit.method || "GET").toUpperCase();
+        if (attempt < retryConfig.maxRetries && SAFE_METHODS.includes(method2) && retryConfig.retryableStatuses.includes(response.status)) {
           lastError = error;
           const retryDelay = retryConfig.retryDelay(attempt);
           debugLog(debug, "error", `Retrying in ${retryDelay}ms...`, error);
@@ -695,8 +720,8 @@ async function httpFetch(url, options) {
       return response;
     } catch (error) {
       debugLog(debug, "error", url, error);
-      const method = (requestInit.method || "GET").toUpperCase();
-      const isSafe = SAFE_METHODS.includes(method);
+      const method2 = (requestInit.method || "GET").toUpperCase();
+      const isSafe = SAFE_METHODS.includes(method2);
       if (error instanceof Error && error.name === "AbortError") {
         const timeoutError = createTimeoutError(
           `Request timed out after ${timeout}ms.`,
@@ -755,6 +780,35 @@ async function httpFetch(url, options) {
   throw lastError ?? new NetworkError("Request failed after retries");
 }
 
+// src/core/internal/utils/query-string.ts
+function productDetailQuery(params) {
+  const search = new URLSearchParams();
+  if ("slug" in params) {
+    search.set("slug", params.slug);
+  } else {
+    search.set("id", params.id);
+  }
+  return `/api/products/detail?${search}`;
+}
+function productDetailCatalogQuery(params) {
+  const search = new URLSearchParams();
+  if ("slug" in params) {
+    search.set("slug", params.slug);
+  } else {
+    search.set("id", params.id);
+  }
+  return `/api/products/detail/catalog?${search}`;
+}
+function listingGroupsQuery(params) {
+  return `/api/products/listing-groups?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
+}
+function listingGroupsCatalogQuery(params) {
+  return `/api/products/listing-groups/catalog?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
+}
+function stockSnapshotQuery(params) {
+  return `/api/products/stock?variantIds=${params.variantIds.map(encodeURIComponent).join(",")}`;
+}
+
 // src/core/collection/http-client.ts
 var HttpClient = class {
   constructor(publishableKey, secretKey, getCustomerToken, onUnauthorized, onRequestId, apiUrl) {
@@ -1073,6 +1127,8 @@ async function parseApiResponse(response, endpoint) {
 }
 
 // src/core/community/community-client.ts
+var DEFAULT_POST_LIST_SORT = "-lastActivityAt";
+var DEFAULT_COMMENT_LIST_SORT = "-createdAt";
 var CommunityClient = class {
   constructor(options) {
     this.publishableKey = requirePublishableKeyForSecret(
@@ -1091,6 +1147,40 @@ var CommunityClient = class {
     const entries = Object.entries(params).filter((e) => e[1] !== void 0).map(([k, v]) => [k, String(v)]);
     return entries.length ? `?${new URLSearchParams(entries).toString()}` : "";
   }
+  buildPostsListQuery(params) {
+    const urlParams = new URLSearchParams();
+    const sort = params?.sort ?? DEFAULT_POST_LIST_SORT;
+    urlParams.set("sort", sort);
+    if (params?.limit !== void 0) urlParams.set("limit", String(params.limit));
+    if (params?.page !== void 0) urlParams.set("page", String(params.page));
+    if (params?.categoryId !== void 0) {
+      urlParams.set("where[categories][in]", params.categoryId);
+    }
+    if (params?.tagId !== void 0) {
+      urlParams.set("where[tags][in]", params.tagId);
+    }
+    return `/api/posts?${urlParams.toString()}`;
+  }
+  buildCommentsListQuery(params) {
+    const urlParams = new URLSearchParams();
+    const sort = params.sort ?? DEFAULT_COMMENT_LIST_SORT;
+    urlParams.set("sort", sort);
+    if (params.postId !== void 0) {
+      urlParams.set("where[post][equals]", params.postId);
+    }
+    if (params.parentId !== void 0) {
+      urlParams.set("where[parent][equals]", params.parentId);
+    }
+    if (params.rootComment !== void 0) {
+      urlParams.set("where[rootComment][equals]", params.rootComment);
+    }
+    if (params.topLevelOnly) {
+      urlParams.set("where[parent][exists]", "false");
+    }
+    if (params.limit !== void 0) urlParams.set("limit", String(params.limit));
+    if (params.page !== void 0) urlParams.set("page", String(params.page));
+    return `/api/comments?${urlParams.toString()}`;
+  }
   async execute(endpoint, method, body) {
     const token = typeof this.customerToken === "function" ? this.customerToken() : this.customerToken;
     try {
@@ -1114,6 +1204,28 @@ var CommunityClient = class {
   createPost(params) {
     return this.execute("/api/posts", "POST", params);
   }
+  /**
+   * Public post feed. Server applies the same visibility contract as
+   * `communityPostRead` (published + visible + moderation-safe).
+   */
+  listPosts(params) {
+    return this.execute(
+      this.buildPostsListQuery(params),
+      "GET"
+    );
+  }
+  listPostCategories(params) {
+    return this.execute(
+      `/api/post-categories${this.buildQuery(params)}`,
+      "GET"
+    );
+  }
+  listPostTags(params) {
+    return this.execute(
+      `/api/post-tags${this.buildQuery(params)}`,
+      "GET"
+    );
+  }
   getMyPosts(params) {
     return this.execute(
       `/api/posts/my${this.buildQuery(params)}`,
@@ -1149,16 +1261,37 @@ var CommunityClient = class {
     }
     return this.execute("/api/comments", "POST", body);
   }
+  /**
+   * List comments for a post.
+   *
+   * - Default: all visible comments on the post (any depth).
+   * - `topLevelOnly: true`: only root comments (`parent` unset).
+   * - `rootComment`: comments belonging to a thread rooted at that comment.
+   */
   listComments(params) {
-    const { postId, page, limit, rootComment } = params;
-    const urlParams = new URLSearchParams();
-    urlParams.set("where[post][equals]", postId);
-    urlParams.set("sort", "-createdAt");
-    if (limit !== void 0) urlParams.set("limit", String(limit));
-    if (page !== void 0) urlParams.set("page", String(page));
-    if (rootComment !== void 0) urlParams.set("where[rootComment][equals]", rootComment);
+    const { postId, page, limit, rootComment, topLevelOnly, sort } = params;
+    return this.execute(
+      this.buildCommentsListQuery({
+        postId,
+        page,
+        limit,
+        rootComment,
+        topLevelOnly,
+        sort
+      }),
+      "GET"
+    );
+  }
+  /** Direct replies to a comment (`where[parent][equals]`). */
+  listReplies(params) {
+    const { commentId, page, limit, sort } = params;
     return this.execute(
-      `/api/comments?${urlParams.toString()}`,
+      this.buildCommentsListQuery({
+        parentId: commentId,
+        page,
+        limit,
+        sort
+      }),
       "GET"
     );
   }
@@ -1186,10 +1319,18 @@ var CommunityClient = class {
   }
   // Reactions
   addReaction(params) {
-    const { postId, type } = params;
+    const { postId, typeSlug, type } = params;
+    const reactionType = typeSlug ?? type;
+    if (!reactionType) {
+      throw new SDKError(
+        "validation_failed",
+        "addReaction requires typeSlug (or deprecated type)",
+        400
+      );
+    }
     return this.execute("/api/reactions", "POST", {
       post: postId,
-      type
+      type: reactionType
     });
   }
   removeReaction(params) {
@@ -1200,10 +1341,18 @@ var CommunityClient = class {
     );
   }
   addCommentReaction(params) {
-    const { commentId, type } = params;
+    const { commentId, typeSlug, type } = params;
+    const reactionType = typeSlug ?? type;
+    if (!reactionType) {
+      throw new SDKError(
+        "validation_failed",
+        "addCommentReaction requires typeSlug (or deprecated type)",
+        400
+      );
+    }
     return this.execute("/api/reactions", "POST", {
       comment: commentId,
-      type
+      type: reactionType
     });
   }
   removeCommentReaction(params) {
@@ -1219,6 +1368,12 @@ var CommunityClient = class {
       "GET"
     );
   }
+  getCommentReactionSummary(params) {
+    return this.execute(
+      `/api/comments/${params.commentId}/reactions`,
+      "GET"
+    );
+  }
   getReactionTypes() {
     return this.execute(
       "/api/reaction-types?limit=100",
@@ -1243,6 +1398,25 @@ var CommunityClient = class {
       "GET"
     );
   }
+  // Profiles
+  listProfileLists(params) {
+    return this.execute(
+      `/api/customer-profile-lists${this.buildQuery(params)}`,
+      "GET"
+    );
+  }
+  async getProfileList(params) {
+    const query = "slug" in params ? `?where[slug][equals]=${encodeURIComponent(params.slug)}&limit=1` : `?where[id][equals]=${encodeURIComponent(params.id)}&limit=1`;
+    const res = await this.execute(`/api/customer-profile-lists${query}`, "GET");
+    return res.docs[0] ?? null;
+  }
+  updatePublicProfile(body) {
+    return this.execute(
+      "/api/customers/me/profile",
+      "PATCH",
+      body
+    );
+  }
 };
 
 // src/core/customer/customer-auth.ts
@@ -1528,6 +1702,283 @@ var CartApi = class {
   }
 };
 
+// src/core/api/base-api.ts
+var BaseApi = class {
+  constructor(apiName, options) {
+    if (!options.secretKey) {
+      throw createConfigError(`secretKey is required for ${apiName}.`);
+    }
+    this.publishableKey = requirePublishableKeyForSecret(
+      apiName,
+      options.publishableKey,
+      options.secretKey
+    );
+    this.secretKey = options.secretKey;
+    this.apiUrl = options.apiUrl;
+    this.onRequestId = options.onRequestId;
+  }
+  async request(endpoint, body, options) {
+    const method = options?.method ?? "POST";
+    try {
+      const response = await httpFetch(endpoint, {
+        method,
+        apiUrl: this.apiUrl,
+        publishableKey: this.publishableKey,
+        secretKey: this.secretKey,
+        ...body !== void 0 && { body: JSON.stringify(body) },
+        ...options?.headers && { headers: options.headers }
+      });
+      this.onRequestId?.(response.headers.get("x-request-id") ?? null);
+      return parseApiResponse(response, endpoint);
+    } catch (err) {
+      const id = err instanceof SDKError ? err.requestId ?? null : null;
+      this.onRequestId?.(id);
+      throw err;
+    }
+  }
+};
+
+// src/core/api/product-api.ts
+var PRODUCT_DETAIL_UNAVAILABLE_REASONS = /* @__PURE__ */ new Set([
+  "not_found",
+  "not_published",
+  "feature_disabled"
+]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function readProductDetailUnavailableReason(value) {
+  if (!isRecord(value)) return void 0;
+  const directReason = value.reason ?? value.code;
+  if (typeof directReason === "string" && PRODUCT_DETAIL_UNAVAILABLE_REASONS.has(directReason)) {
+    return directReason;
+  }
+  return readProductDetailUnavailableReason(value.body);
+}
+function productDetailResultFromError(error) {
+  if (!(error instanceof SDKError) || error.status !== 404) return void 0;
+  const reason = readProductDetailUnavailableReason(error.details);
+  if (!reason) return void 0;
+  return { found: false, reason };
+}
+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.'
+    );
+  }
+}
+function normalizeProductUpsertOptionValue(value) {
+  rejectLegacyOptionValueSwatchColor(value);
+  return value;
+}
+function normalizeProductUpsertParams(params) {
+  const options = params.options ?? [];
+  const variants = params.variants ?? [];
+  if (!options.length) {
+    return { ...params, options, variants };
+  }
+  return {
+    ...params,
+    options: options.map((option) => ({
+      ...option,
+      values: option.values.map(
+        (value) => normalizeProductUpsertOptionValue(value)
+      )
+    })),
+    variants
+  };
+}
+var PRODUCT_UPSERT_UNKNOWN_FIELD_REASON = "unknown_field";
+var PRODUCT_UPSERT_READONLY_FIELD_REASON = "product_field_readonly";
+function isProductUpsertFieldValidationErrorBody(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const body = value;
+  const reason = body.reason;
+  return typeof body.error === "string" && typeof body.field === "string" && (reason === PRODUCT_UPSERT_UNKNOWN_FIELD_REASON || reason === PRODUCT_UPSERT_READONLY_FIELD_REASON);
+}
+var ProductApi = class extends BaseApi {
+  constructor(options) {
+    super("ProductApi", options);
+  }
+  /**
+   * Check point-in-time stock availability for one or more product variants.
+   * Results reflect available stock at the moment of the call and are not guaranteed
+   * to remain available by the time an order is placed.
+   */
+  stockCheck(params) {
+    return this.request("/api/products/stock-check", params);
+  }
+  stockSnapshot(params) {
+    return this.request(
+      stockSnapshotQuery(params),
+      void 0,
+      { method: "GET" }
+    );
+  }
+  listingGroups(params) {
+    return this.request(
+      listingGroupsQuery(params),
+      void 0,
+      { method: "GET" }
+    );
+  }
+  listingGroupsCatalog(params) {
+    return this.request(
+      listingGroupsCatalogQuery(params),
+      void 0,
+      { method: "GET" }
+    );
+  }
+  /**
+   * Fetch full product detail by slug or id.
+   * Returns a discriminated result so storefronts can distinguish missing,
+   * unpublished, and feature-disabled products.
+   *
+   * Only product-detail 404 responses carrying one of those allowlisted reasons
+   * are mapped to `{ found: false, reason }`. Unknown or uncoded 404s, plus
+   * permission/auth errors such as tenant mismatch, continue to throw typed SDK
+   * errors instead of being collapsed into a storefront absence result.
+   */
+  async detail(params) {
+    try {
+      const product = await this.request(
+        productDetailQuery(params),
+        void 0,
+        { method: "GET" }
+      );
+      return { found: true, product };
+    } catch (err) {
+      const notFoundResult = productDetailResultFromError(err);
+      if (notFoundResult) return notFoundResult;
+      throw err;
+    }
+  }
+  async detailCatalog(params) {
+    try {
+      const product = await this.request(
+        productDetailCatalogQuery(params),
+        void 0,
+        { method: "GET" }
+      );
+      return { found: true, product };
+    } catch (err) {
+      const notFoundResult = productDetailResultFromError(err);
+      if (notFoundResult?.found === false) return notFoundResult;
+      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",
+      normalizeProductUpsertParams(params)
+    );
+  }
+};
+
+// src/core/api/order-api.ts
+function idempotencyRequestOptions(idempotencyKey) {
+  return idempotencyKey ? { headers: { "X-Idempotency-Key": idempotencyKey } } : void 0;
+}
+function splitIdempotencyKey(params) {
+  const { idempotencyKey, ...body } = params;
+  return { body, idempotencyKey };
+}
+var OrderApi = class extends BaseApi {
+  constructor(options) {
+    super("OrderApi", options);
+  }
+  createOrder(params) {
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    return this.request(
+      "/api/orders/create",
+      body,
+      idempotencyRequestOptions(idempotencyKey)
+    );
+  }
+  updateOrder(params) {
+    return this.request("/api/orders/update", params);
+  }
+  updateTransaction(params) {
+    return this.request("/api/transactions/update", params);
+  }
+  confirmPayment(params) {
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    const headerKey = idempotencyKey ?? params.providerEventId;
+    return this.request(
+      "/api/orders/confirm-payment",
+      body,
+      idempotencyRequestOptions(headerKey)
+    );
+  }
+  cancelOrder(params) {
+    const { idempotencyKey } = params;
+    const body = {
+      orderNumber: params.orderNumber,
+      reasonCode: params.reasonCode,
+      reasonDetail: params.reasonDetail
+    };
+    return this.request(
+      "/api/orders/cancel",
+      body,
+      idempotencyKey ? { headers: { "X-Idempotency-Key": idempotencyKey } } : void 0
+    );
+  }
+  checkout(params) {
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    return this.request(
+      "/api/orders/checkout",
+      body,
+      idempotencyRequestOptions(idempotencyKey)
+    );
+  }
+  createFulfillment(params) {
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    return this.request(
+      "/api/orders/create-fulfillment",
+      body,
+      idempotencyRequestOptions(idempotencyKey)
+    );
+  }
+  updateFulfillment(params) {
+    return this.request("/api/orders/update-fulfillment", params);
+  }
+  bulkImportFulfillments(params) {
+    return this.request(
+      "/api/fulfillments/bulk-import",
+      params
+    );
+  }
+  returnWithRefund(params) {
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    return this.request(
+      "/api/returns/return-refund",
+      body,
+      idempotencyRequestOptions(idempotencyKey)
+    );
+  }
+  createReturn(params) {
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    return this.request(
+      "/api/returns/create",
+      body,
+      idempotencyRequestOptions(idempotencyKey)
+    );
+  }
+  updateReturn(params) {
+    return this.request("/api/returns/update", params);
+  }
+};
+
 // src/core/commerce/commerce-client.ts
 var CommerceClient = class {
   constructor(options) {
@@ -1538,7 +1989,7 @@ var CommerceClient = class {
       onUnauthorized: options.onUnauthorized,
       onRequestId: options.onRequestId
     });
-    const execute = async (endpoint, body) => {
+    const execute = async (endpoint, body, requestOptions) => {
       const token = options.customerToken();
       try {
         const response = await httpFetch(endpoint, {
@@ -1547,7 +1998,26 @@ var CommerceClient = class {
           publishableKey: options.publishableKey,
           customerToken: token ?? void 0,
           ...token && options.onUnauthorized && { onUnauthorized: options.onUnauthorized },
-          body: JSON.stringify(body)
+          body: JSON.stringify(body),
+          ...requestOptions?.headers && { headers: requestOptions.headers }
+        });
+        options.onRequestId?.(response.headers.get("x-request-id") ?? null);
+        return parseApiResponse(response, endpoint);
+      } catch (err) {
+        const id = err instanceof SDKError ? err.requestId ?? null : null;
+        options.onRequestId?.(id);
+        throw err;
+      }
+    };
+    const executeGet = async (endpoint) => {
+      const token = options.customerToken();
+      try {
+        const response = await httpFetch(endpoint, {
+          method: "GET",
+          apiUrl: options.apiUrl,
+          publishableKey: options.publishableKey,
+          customerToken: token ?? void 0,
+          ...token && options.onUnauthorized && { onUnauthorized: options.onUnauthorized }
         });
         options.onRequestId?.(response.headers.get("x-request-id") ?? null);
         return parseApiResponse(response, endpoint);
@@ -1559,12 +2029,28 @@ var CommerceClient = class {
     };
     this.product = {
       stockCheck: (params) => execute("/api/products/stock-check", params),
-      listingGroups: (params) => execute("/api/products/listing-groups", params),
+      stockSnapshot: (params) => executeGet(stockSnapshotQuery(params)),
+      listingGroups: (params) => executeGet(listingGroupsQuery(params)),
+      listingGroupsCatalog: (params) => executeGet(listingGroupsCatalogQuery(params)),
       detail: async (params) => {
         try {
-          return await execute("/api/products/detail", params);
+          const product = await executeGet(productDetailQuery(params));
+          return { found: true, product };
+        } catch (err) {
+          const notFoundResult = productDetailResultFromError(err);
+          if (notFoundResult) return notFoundResult;
+          throw err;
+        }
+      },
+      detailCatalog: async (params) => {
+        try {
+          const product = await executeGet(
+            productDetailCatalogQuery(params)
+          );
+          return { found: true, product };
         } catch (err) {
-          if (err instanceof NotFoundError) return null;
+          const notFoundResult = productDetailResultFromError(err);
+          if (notFoundResult?.found === false) return notFoundResult;
           throw err;
         }
       }
@@ -1579,7 +2065,14 @@ var CommerceClient = class {
       clear: cartApi.clearCart.bind(cartApi)
     };
     this.orders = {
-      checkout: (params) => execute("/api/orders/checkout", params),
+      checkout: (params) => {
+        const { body, idempotencyKey } = splitIdempotencyKey(params);
+        return execute(
+          "/api/orders/checkout",
+          body,
+          idempotencyRequestOptions(idempotencyKey)
+        );
+      },
       listMine: (params) => options.customerAuth.getMyOrders(params)
     };
     this.discounts = {
@@ -1591,15 +2084,122 @@ var CommerceClient = class {
   }
 };
 
-// src/core/client/client.ts
-var Client = class {
+// src/core/events/events-client.ts
+var EventsClient = class {
   constructor(options) {
-    this.lastRequestId = null;
-    const publishableKey = options.publishableKey;
-    if (!publishableKey) {
-      throw createConfigError("publishableKey is required.");
-    }
-    this.config = { ...options, publishableKey };
+    const secretKey = options.secretKey;
+    this.publishableKey = requirePublishableKeyForSecret(
+      "EventsClient",
+      options.publishableKey,
+      secretKey
+    );
+    this.apiUrl = options.apiUrl;
+    this.customerToken = options.customerToken;
+    this.onUnauthorized = options.onUnauthorized;
+    this.onRequestId = options.onRequestId;
+  }
+  getRange(params) {
+    return this.execute(
+      buildRangeEndpoint(params),
+      "GET",
+      void 0,
+      { useCustomerAuth: false }
+    );
+  }
+  register(params) {
+    return this.execute(
+      "/api/event-registrations/register",
+      "POST",
+      buildRegistrationRequestBody(params),
+      { useCustomerAuth: true }
+    );
+  }
+  getGuestRegistration(token) {
+    return this.execute(
+      "/api/event-registrations/guest/lookup",
+      "POST",
+      { token },
+      { useCustomerAuth: false }
+    );
+  }
+  cancelGuestRegistration(token, params = {}) {
+    return this.execute(
+      "/api/event-registrations/guest/cancel",
+      "POST",
+      buildGuestCancelRequestBody(token, params),
+      { useCustomerAuth: false }
+    );
+  }
+  async execute(endpoint, method, body, options = {}) {
+    const useCustomerAuth = options.useCustomerAuth === true;
+    const token = useCustomerAuth ? typeof this.customerToken === "function" ? this.customerToken() : this.customerToken : void 0;
+    try {
+      const response = await httpFetch(endpoint, {
+        method,
+        apiUrl: this.apiUrl,
+        publishableKey: this.publishableKey,
+        ...useCustomerAuth && token ? { customerToken: token } : {},
+        ...useCustomerAuth && token && this.onUnauthorized && { onUnauthorized: this.onUnauthorized },
+        ...body !== void 0 && { body: JSON.stringify(body) }
+      });
+      this.onRequestId?.(response.headers.get("x-request-id") ?? null);
+      return parseApiResponse(response, endpoint);
+    } catch (err) {
+      const id = err instanceof SDKError ? err.requestId ?? null : null;
+      this.onRequestId?.(id);
+      throw err;
+    }
+  }
+};
+function buildRegistrationRequestBody(params) {
+  return {
+    event: params.event,
+    occurrence: params.occurrence,
+    ...params.quantity !== void 0 && { quantity: params.quantity },
+    ...params.attendee !== void 0 && { attendee: params.attendee },
+    ...params.answers !== void 0 && { answers: params.answers }
+  };
+}
+function buildGuestCancelRequestBody(token, params) {
+  return {
+    token,
+    ...params.reason !== void 0 && { reason: params.reason }
+  };
+}
+function buildRangeEndpoint(params) {
+  const urlParams = new URLSearchParams();
+  urlParams.set("start", formatDateParam(params.start));
+  urlParams.set("end", formatDateParam(params.end));
+  if (params.limit !== void 0) urlParams.set("limit", String(params.limit));
+  if (params.page !== void 0) urlParams.set("page", String(params.page));
+  appendValues(urlParams, "calendar", params.calendar);
+  appendValues(urlParams, "calendarSlug", params.calendarSlug);
+  appendValues(urlParams, "category", params.category);
+  appendValues(urlParams, "categorySlug", params.categorySlug);
+  appendValues(urlParams, "tag", params.tag);
+  appendValues(urlParams, "tagSlug", params.tagSlug);
+  return `/api/event-occurrences/range?${urlParams.toString()}`;
+}
+function formatDateParam(value) {
+  return value instanceof Date ? value.toISOString() : value;
+}
+function appendValues(params, key, value) {
+  if (value === void 0) return;
+  const values = Array.isArray(value) ? value : [value];
+  for (const entry of values) {
+    if (entry) params.append(key, entry);
+  }
+}
+
+// src/core/client/client.ts
+var Client = class {
+  constructor(options) {
+    this.lastRequestId = null;
+    const publishableKey = options.publishableKey;
+    if (!publishableKey) {
+      throw createConfigError("publishableKey is required.");
+    }
+    this.config = { ...options, publishableKey };
     const metadata = {
       timestamp: Date.now(),
       userAgent: typeof window !== "undefined" ? window.navigator?.userAgent : "Node.js"
@@ -1636,6 +2236,13 @@ var Client = class {
       onUnauthorized,
       onRequestId
     });
+    this.events = new EventsClient({
+      publishableKey: this.config.publishableKey,
+      apiUrl: this.config.apiUrl,
+      customerToken: () => this.customer.auth.getToken(),
+      onUnauthorized,
+      onRequestId
+    });
     this.collections = new ReadOnlyCollectionClient(
       this.config.publishableKey,
       void 0,
@@ -1656,92 +2263,6 @@ function createClient(options) {
   return new Client(options);
 }
 
-// src/core/api/base-api.ts
-var BaseApi = class {
-  constructor(apiName, options) {
-    if (!options.secretKey) {
-      throw createConfigError(`secretKey is required for ${apiName}.`);
-    }
-    this.publishableKey = requirePublishableKeyForSecret(
-      apiName,
-      options.publishableKey,
-      options.secretKey
-    );
-    this.secretKey = options.secretKey;
-    this.apiUrl = options.apiUrl;
-    this.onRequestId = options.onRequestId;
-  }
-  async request(endpoint, body, options) {
-    const method = options?.method ?? "POST";
-    try {
-      const response = await httpFetch(endpoint, {
-        method,
-        apiUrl: this.apiUrl,
-        publishableKey: this.publishableKey,
-        secretKey: this.secretKey,
-        ...body !== void 0 && { body: JSON.stringify(body) },
-        ...options?.headers && { headers: options.headers }
-      });
-      this.onRequestId?.(response.headers.get("x-request-id") ?? null);
-      return parseApiResponse(response, endpoint);
-    } catch (err) {
-      const id = err instanceof SDKError ? err.requestId ?? null : null;
-      this.onRequestId?.(id);
-      throw err;
-    }
-  }
-};
-
-// src/core/api/order-api.ts
-var OrderApi = class extends BaseApi {
-  constructor(options) {
-    super("OrderApi", options);
-  }
-  createOrder(params) {
-    return this.request("/api/orders/create", params);
-  }
-  updateOrder(params) {
-    return this.request("/api/orders/update", params);
-  }
-  updateTransaction(params) {
-    return this.request("/api/transactions/update", params);
-  }
-  confirmPayment(params) {
-    return this.request(
-      "/api/orders/confirm-payment",
-      params,
-      params.providerEventId ? { headers: { "X-Idempotency-Key": params.providerEventId } } : void 0
-    );
-  }
-  checkout(params) {
-    return this.request("/api/orders/checkout", params);
-  }
-  createFulfillment(params) {
-    return this.request("/api/orders/create-fulfillment", params);
-  }
-  updateFulfillment(params) {
-    return this.request("/api/orders/update-fulfillment", params);
-  }
-  bulkImportFulfillments(params) {
-    return this.request(
-      "/api/orders/bulk-import-fulfillments",
-      params
-    );
-  }
-  returnWithRefund(params) {
-    return this.request(
-      "/api/returns/return-refund",
-      params
-    );
-  }
-  createReturn(params) {
-    return this.request("/api/returns/create", params);
-  }
-  updateReturn(params) {
-    return this.request("/api/returns/update", params);
-  }
-};
-
 // src/core/api/discount-api.ts
 var DiscountApi = class extends BaseApi {
   constructor(options) {
@@ -1762,62 +2283,66 @@ var ShippingApi = class extends BaseApi {
   }
 };
 
-// src/core/api/product-api.ts
-var ProductApi = class extends BaseApi {
-  constructor(options) {
-    super("ProductApi", options);
-  }
-  /**
-   * Check point-in-time stock availability for one or more product variants.
-   * Results reflect available stock at the moment of the call and are not guaranteed
-   * to remain available by the time an order is placed.
-   */
-  stockCheck(params) {
-    return this.request("/api/products/stock-check", params);
-  }
-  listingGroups(params) {
-    return this.request(
-      "/api/products/listing-groups",
-      params
-    );
-  }
-  /**
-   * Fetch full product detail by slug or id.
-   * Returns `null` on 404 regardless of reason (`not_found` / `not_published` /
-   * `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;
+// src/core/commerce/merge-catalog-stock.ts
+function mergeProductDetailWithStock(catalog, snapshot) {
+  const snapshotByVariantId = new Map(
+    snapshot.snapshots.map((item) => [item.variantId, item])
+  );
+  let missingSnapshotCount = 0;
+  const variants = catalog.variants.map((variant) => {
+    const snap = snapshotByVariantId.get(String(variant.id));
+    if (!snap) {
+      missingSnapshotCount += 1;
+      return { ...variant, stock: 0, reservedStock: 0 };
     }
-  }
-  /**
-   * 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);
-  }
-};
+    return {
+      ...variant,
+      stock: snap.isUnlimited ? 0 : snap.availableStock,
+      reservedStock: 0
+    };
+  });
+  const trackedVariants = variants.filter((variant) => !variant.isUnlimited);
+  const totalInventory = trackedVariants.length === 0 ? null : trackedVariants.reduce(
+    (sum, variant) => sum + Math.max(0, (variant.stock ?? 0) - (variant.reservedStock ?? 0)),
+    0
+  );
+  const { liveStockRequired: _liveStockRequired, ...listingBase } = catalog.listing;
+  const availableForSale = snapshot.snapshots.some(
+    (item) => item.status === "available" && item.availableForSale
+  );
+  return {
+    stockMergeStatus: missingSnapshotCount === 0 ? "complete" : "partial",
+    product: {
+      ...catalog,
+      product: { ...catalog.product, totalInventory },
+      variants,
+      listing: { ...listingBase, availableForSale }
+    }
+  };
+}
 
 // src/core/webhook/index.ts
 var ORDER_CHANGED_EVENT_TYPE = "collection.orderChanged";
+var COMMERCE_NOTIFICATION_EVENT_TYPE = "commerce.notification";
 function isValidWebhookEvent(data) {
   if (typeof data !== "object" || data === null) return false;
   const obj = data;
   return typeof obj.collection === "string" && typeof obj.operation === "string" && obj.operation.length > 0 && typeof obj.data === "object" && obj.data !== null;
 }
+var COMMERCE_NOTIFICATION_OPERATION = "notification";
+var COMMERCE_NOTIFICATION_EVENTS = [
+  "orderPaid",
+  "orderCanceled",
+  "fulfillmentShipped",
+  "orderDelivered",
+  "returnRequested",
+  "returnCompleted"
+];
 function isStringOrNumber(value) {
   return typeof value === "string" || typeof value === "number";
 }
 function isWebhookOrderScope(value) {
-  if (!isRecord(value)) return false;
+  if (!isRecord2(value)) return false;
   if (value.kind === "collection") {
     return typeof value.collection === "string";
   }
@@ -1827,16 +2352,40 @@ function isWebhookOrderScope(value) {
   return false;
 }
 function isWebhookOrderMoved(value) {
-  if (!isRecord(value)) return false;
+  if (!isRecord2(value)) return false;
   return typeof value.collection === "string" && isStringOrNumber(value.id) && (value.relatedCollection === void 0 || typeof value.relatedCollection === "string") && (value.relatedId === void 0 || isStringOrNumber(value.relatedId));
 }
 function hasOptionalOrderValue(value, key) {
   return value[key] === void 0 || value[key] === null || typeof value[key] === "string";
 }
 function isWebhookOrderChange(value) {
-  if (!isRecord(value)) return false;
+  if (!isRecord2(value)) return false;
   return value.type === "order" && value.source === "payload-orderable" && (value.orderableFieldName === void 0 || typeof value.orderableFieldName === "string") && hasOptionalOrderValue(value, "previousOrder") && hasOptionalOrderValue(value, "nextOrder") && isWebhookOrderScope(value.scope) && isWebhookOrderMoved(value.moved);
 }
+function isCommerceNotificationEventName(value) {
+  return typeof value === "string" && COMMERCE_NOTIFICATION_EVENTS.includes(value);
+}
+function isCommerceNotificationSourceCollection(value) {
+  return value === "orders" || value === "fulfillments" || value === "returns";
+}
+function isCommerceNotificationData(value) {
+  if (!isRecord2(value)) return false;
+  if (value.source !== void 0 && (!isRecord2(value.source) || !isCommerceNotificationSourceCollection(value.source.collection) || !isStringOrNumber(value.source.id))) {
+    return false;
+  }
+  return (value.orderId === void 0 || isStringOrNumber(value.orderId)) && (value.orderNumber === void 0 || typeof value.orderNumber === "string") && (value.status === void 0 || typeof value.status === "string") && (value.totalAmount === void 0 || typeof value.totalAmount === "number") && (value.currency === void 0 || typeof value.currency === "string") && (value.fulfillmentId === void 0 || isStringOrNumber(value.fulfillmentId)) && (value.fulfillmentStatus === void 0 || typeof value.fulfillmentStatus === "string") && (value.shippedAt === void 0 || typeof value.shippedAt === "string") && (value.returnId === void 0 || isStringOrNumber(value.returnId)) && (value.returnStatus === void 0 || typeof value.returnStatus === "string") && (value.refundAmount === void 0 || typeof value.refundAmount === "number") && (value.completedAt === void 0 || typeof value.completedAt === "string");
+}
+function isCommerceNotification(value) {
+  if (!isRecord2(value)) return false;
+  return isCommerceNotificationEventName(value.event) && typeof value.intentId === "string" && value.intentId.length > 0 && typeof value.dedupeKey === "string" && value.dedupeKey.length > 0 && (value.orderId === void 0 || typeof value.orderId === "string") && (value.fulfillmentId === void 0 || typeof value.fulfillmentId === "string") && (value.returnId === void 0 || typeof value.returnId === "string");
+}
+function isWebhookCommerceNotificationChange(value) {
+  if (!isRecord2(value)) return false;
+  return value.type === "notification" && value.source === "commerce-notifications" && isCommerceNotificationEventName(value.event) && isCommerceNotificationSourceCollection(value.sourceCollection) && isStringOrNumber(value.sourceId);
+}
+function matchesOptionalId(actual, expected) {
+  return actual === void 0 || expected === void 0 || actual === expected;
+}
 function isOrderChangedWebhookEvent(event) {
   if (!isValidWebhookEvent(event) || event.operation !== "update" || event.eventType !== ORDER_CHANGED_EVENT_TYPE || !isWebhookOrderChange(event.change)) {
     return false;
@@ -1849,6 +2398,60 @@ function isOrderChangedWebhookEvent(event) {
   }
   return true;
 }
+function isCommerceNotificationWebhookEvent(event) {
+  if (!isValidWebhookEvent(event) || event.operation !== COMMERCE_NOTIFICATION_OPERATION || event.eventType !== COMMERCE_NOTIFICATION_EVENT_TYPE || !isCommerceNotificationData(event.data) || !isCommerceNotification(event.notification)) {
+    return false;
+  }
+  const notification = event.notification;
+  const data = event.data;
+  const change = event.change;
+  const sourceCollection = data.source?.collection ?? event.collection;
+  const sourceId = data.source?.id;
+  if (!isCommerceNotificationSourceCollection(sourceCollection)) return false;
+  if (data.source !== void 0 && event.collection !== data.source.collection) {
+    return false;
+  }
+  if (change !== void 0) {
+    if (!isWebhookCommerceNotificationChange(change)) return false;
+    if (change.sourceCollection !== sourceCollection) return false;
+    if (change.event !== notification.event) return false;
+    if (!matchesOptionalId(change.sourceId, sourceId)) return false;
+  }
+  const changeSourceId = isWebhookCommerceNotificationChange(change) ? change.sourceId : void 0;
+  if (notification.event === "orderPaid" || notification.event === "orderCanceled" || notification.event === "orderDelivered") {
+    return sourceCollection === "orders" && typeof notification.orderId === "string" && notification.orderId.length > 0 && matchesOptionalId(data.orderId, sourceId) && matchesOptionalId(notification.orderId, sourceId) && matchesOptionalId(data.orderId, notification.orderId) && matchesOptionalId(changeSourceId, data.orderId ?? notification.orderId);
+  }
+  if (notification.event === "fulfillmentShipped") {
+    return sourceCollection === "fulfillments" && matchesOptionalId(data.fulfillmentId, sourceId) && typeof notification.fulfillmentId === "string" && notification.fulfillmentId.length > 0 && matchesOptionalId(notification.fulfillmentId, sourceId) && matchesOptionalId(data.fulfillmentId, notification.fulfillmentId) && matchesOptionalId(changeSourceId, notification.fulfillmentId);
+  }
+  if (notification.event === "returnRequested" || notification.event === "returnCompleted") {
+    return sourceCollection === "returns" && matchesOptionalId(data.returnId, sourceId) && typeof notification.returnId === "string" && notification.returnId.length > 0 && matchesOptionalId(notification.returnId, sourceId) && matchesOptionalId(data.returnId, notification.returnId) && matchesOptionalId(changeSourceId, notification.returnId);
+  }
+  return false;
+}
+function getCommerceNotificationIdempotencyKey(event) {
+  return `${event.notification.intentId}:${event.notification.dedupeKey}`;
+}
+function defineCommerceEmailConfig(config) {
+  return config;
+}
+function createCommerceEmailWebhookHandler(handlers) {
+  return async (event) => {
+    if (!isCommerceNotificationWebhookEvent(event)) {
+      await handlers.unhandled?.(event);
+      return;
+    }
+    const handler = handlers[event.notification.event];
+    if (!handler) {
+      await handlers.unhandled?.(event);
+      return;
+    }
+    await handler({
+      event,
+      idempotencyKey: getCommerceNotificationIdempotencyKey(event)
+    });
+  };
+}
 function isWebhookCollection(event, collection) {
   return isValidWebhookEvent(event) && event.collection === collection;
 }
@@ -1856,7 +2459,7 @@ function isWebhookOperation(event, operation) {
   return isValidWebhookEvent(event) && event.operation === operation;
 }
 var CUSTOMER_PASSWORD_RESET_OPERATION = "password-reset";
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null;
 }
 function hasString(value, key) {
@@ -1866,7 +2469,7 @@ function hasStringOrNumber(value, key) {
   return typeof value[key] === "string" || typeof value[key] === "number";
 }
 function isCustomerPasswordResetWebhookEvent(event) {
-  if (event.collection !== "customers" || event.operation !== CUSTOMER_PASSWORD_RESET_OPERATION || !isRecord(event.data)) {
+  if (event.collection !== "customers" || event.operation !== CUSTOMER_PASSWORD_RESET_OPERATION || !isRecord2(event.data)) {
     return false;
   }
   return hasStringOrNumber(event.data, "customerId") && hasString(event.data, "email") && hasString(event.data, "name") && hasString(event.data, "resetPasswordToken") && hasString(event.data, "resetPasswordExpiresAt");
@@ -1986,6 +2589,7 @@ var INTERNAL_COLLECTIONS = [
   "subscriptions",
   "billing-history",
   "inventory-reservations",
+  "commerce-notification-intents",
   "product-collection-items",
   "order-status-logs",
   "api-keys",
@@ -2069,6 +2673,7 @@ var COLLECTIONS = [
   "reaction-types",
   "bookmarks",
   "post-categories",
+  "post-tags",
   "customer-profile-lists",
   // Events
   "event-calendars",
@@ -2217,22 +2822,252 @@ var RealtimeConnection = class {
       }
     }
   }
-  scheduleReconnect() {
-    if (this.reconnectTimer) return;
-    const delay2 = Math.min(
-      INITIAL_RECONNECT_DELAY * Math.pow(RECONNECT_BACKOFF_FACTOR, this.reconnectAttempt),
-      MAX_RECONNECT_DELAY
-    );
-    this.reconnectAttempt++;
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      this.abortController = new AbortController();
-      this.startStream(this.abortController.signal);
-    }, delay2);
+  scheduleReconnect() {
+    if (this.reconnectTimer) return;
+    const delay2 = Math.min(
+      INITIAL_RECONNECT_DELAY * Math.pow(RECONNECT_BACKOFF_FACTOR, this.reconnectAttempt),
+      MAX_RECONNECT_DELAY
+    );
+    this.reconnectAttempt++;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.abortController = new AbortController();
+      this.startStream(this.abortController.signal);
+    }, delay2);
+  }
+};
+
+// 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 mediaId2 = getMediaId(entry);
+    if (mediaId2) {
+      const pooled = poolById.get(mediaId2);
+      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 resolveProductDisplayMedia(input) {
+  const pool = mediaArray(input.productMediaPool);
+  const poolById = buildPoolById(pool);
+  const listingPointer = toPointerId(input.listingPrimaryImage);
+  if (listingPointer) {
+    const listingPrimary = poolById.get(listingPointer);
+    if (listingPrimary) {
+      return {
+        primaryImage: listingPrimary,
+        images: uniqueWithPrimaryFirst(listingPrimary, pool),
+        source: "listing_primary"
+      };
+    }
+  }
+  const productPrimaryPointer = getMediaId(input.productPrimaryMediaItemId);
+  if (productPrimaryPointer) {
+    const productPrimary = poolById.get(productPrimaryPointer);
+    if (productPrimary) {
+      return {
+        primaryImage: productPrimary,
+        images: uniqueWithPrimaryFirst(productPrimary, pool),
+        source: "product_primary"
+      };
+    }
   }
-};
+  if (pool.length > 0) {
+    const productPoolPrimary = pool[0] ?? null;
+    if (productPoolPrimary) {
+      return {
+        primaryImage: productPoolPrimary,
+        images: uniqueWithPrimaryFirst(productPoolPrimary, pool),
+        source: "product_pool"
+      };
+    }
+  }
+  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
+function normalizeMatrixSwatch(swatch) {
+  if (!swatch) return null;
+  const rawMedia = swatch.mediaItemId;
+  const inlineMedia = rawMedia != null && typeof rawMedia === "object" && "url" in rawMedia && typeof rawMedia.url === "string" ? rawMedia : null;
+  return {
+    type: swatch.type ?? null,
+    color: swatch.color ?? null,
+    mediaItemId: extractEntityId(rawMedia),
+    inlineMedia
+  };
+}
+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);
@@ -2277,6 +3112,18 @@ function getVariantPrimaryImage(variant) {
   if (!variant) return null;
   return extractEntityId(variant.thumbnail) ?? getFirstMediaId(variant.images);
 }
+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 getFirstAvailableVariantPrimaryImage(variants) {
   const orderedVariants = [...variants].sort(compareVariantOrder);
   for (const variant of orderedVariants) {
@@ -2286,6 +3133,27 @@ function getFirstAvailableVariantPrimaryImage(variants) {
   }
   return null;
 }
+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 normalizeOptionValue(value, fallbackOptionId, fallbackOptionSlug) {
   return {
     id: String(value.id),
@@ -2293,9 +3161,7 @@ function normalizeOptionValue(value, fallbackOptionId, fallbackOptionSlug) {
     optionSlug: fallbackOptionSlug,
     label: value.value || value.slug || String(value.id),
     slug: value.slug ?? null,
-    swatchColor: value.swatchColor ?? null,
-    thumbnail: value.thumbnail ?? null,
-    images: value.images ?? null,
+    swatch: normalizeProductOptionValueSwatch(value.swatch),
     order: value._order ?? value["_product-option-values_values_order"] ?? ""
   };
 }
@@ -2401,9 +3267,7 @@ function buildProductOptionMatrixFromDetail(detail) {
       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,
+      swatch: normalizeProductOptionValueSwatch(value.swatch),
       order: matrixOrder(valueIndex)
     }))
   }));
@@ -2839,13 +3703,19 @@ function stringifyProductSelection(detail, selection = {}, options) {
       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;
     }
-    params.append(`opt.${optionId}`, valueId);
+    if (emit === "slug-compat") {
+      if (appendSlugCompatSelectionParam(params, matrix, optionId, valueId)) {
+        continue;
+      }
+    }
+    appendCanonicalSelectionParam(params, optionId, valueId);
   }
   return params.toString();
 }
@@ -2884,6 +3754,100 @@ function getExactSelectedVariantEntry(matrix, selection, matchingVariants) {
     )
   ) ?? null;
 }
+function normalizedSelectionFromByOptionId(matrix, selectedByOptionId, variantId) {
+  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 buildFilledNormalizedSelection(matrix, normalizedSelection, listing) {
+  const selectedByOptionId = new Map(
+    Object.entries(normalizedSelection.byOptionId)
+  );
+  if (matrix.optionIds.every((optionId) => selectedByOptionId.has(optionId))) {
+    const variantId = normalizedSelection.variantId ?? resolveVariantIdForCompleteSelection(matrix, selectedByOptionId);
+    if (variantId === normalizedSelection.variantId) {
+      return normalizedSelection;
+    }
+    return normalizedSelectionFromByOptionId(
+      matrix,
+      selectedByOptionId,
+      variantId
+    );
+  }
+  for (const option of matrix.options) {
+    if (selectedByOptionId.has(option.id)) continue;
+    if (option.values.length === 1) {
+      selectedByOptionId.set(option.id, option.values[0].id);
+    }
+  }
+  if (matrix.optionIds.every((optionId) => selectedByOptionId.has(optionId))) {
+    const variantId = normalizedSelection.variantId ?? resolveVariantIdForCompleteSelection(matrix, selectedByOptionId);
+    return normalizedSelectionFromByOptionId(
+      matrix,
+      selectedByOptionId,
+      variantId
+    );
+  }
+  const partialNormalized = normalizedSelectionFromByOptionId(
+    matrix,
+    selectedByOptionId,
+    normalizedSelection.variantId
+  );
+  const matchingVariantEntries = getMatchingVariantEntries(
+    matrix,
+    partialNormalized
+  );
+  const orderedMatches = [...matchingVariantEntries].sort(
+    (left, right) => compareVariantOrder(left.source, right.source)
+  );
+  const hintVariantId = listing.selectionHintVariant != null ? String(listing.selectionHintVariant) : null;
+  const hintedEntry = hintVariantId != null ? orderedMatches.find((entry) => entry.id === hintVariantId) : void 0;
+  const availableEntry = orderedMatches.find(
+    (entry) => isVariantAvailableForSale(entry.source)
+  );
+  const chosenEntry = hintedEntry ?? availableEntry ?? orderedMatches[0];
+  if (!chosenEntry) {
+    return normalizedSelection;
+  }
+  for (const optionId of matrix.optionIds) {
+    if (selectedByOptionId.has(optionId)) continue;
+    const valueId = chosenEntry.optionValueByOptionId.get(optionId);
+    if (valueId) selectedByOptionId.set(optionId, valueId);
+  }
+  const filledVariantId = matrix.optionIds.every(
+    (optionId) => selectedByOptionId.has(optionId)
+  ) ? resolveVariantIdForCompleteSelection(matrix, selectedByOptionId) ?? chosenEntry.id : normalizedSelection.variantId;
+  return normalizedSelectionFromByOptionId(
+    matrix,
+    selectedByOptionId,
+    filledVariantId
+  );
+}
+function resolveVariantIdForCompleteSelection(matrix, selectedByOptionId) {
+  if (!matrix.optionIds.every((optionId) => selectedByOptionId.has(optionId))) {
+    return null;
+  }
+  const normalized = normalizedSelectionFromByOptionId(
+    matrix,
+    selectedByOptionId,
+    null
+  );
+  const matchingVariantEntries = getMatchingVariantEntries(matrix, normalized);
+  return getExactSelectedVariantEntry(matrix, normalized, matchingVariantEntries)?.id ?? null;
+}
 function buildSelectionPrice(variants) {
   const { min, max } = getMinMax(variants.map((variant) => variant.price));
   const { min: compareAtMin, max: compareAtMax } = getMinMax(
@@ -2897,38 +3861,51 @@ function buildSelectionPrice(variants) {
     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) {
+function mediaArray2(values) {
   if (!Array.isArray(values)) return [];
   return values.filter(isPresentMedia);
 }
 function buildSelectionMedia(detail, selectedVariant, matchingVariants, selectedValues) {
-  const selectedVariantImages = mediaArray(selectedVariant?.images);
-  const selectedValueImages = selectedValues.flatMap(
-    (value) => mediaArray(value.images)
-  );
-  const matchingVariantImages = matchingVariants.flatMap(
-    (variant) => mediaArray(variant.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 ?? matchingVariantPrimary ?? firstMedia(detail.listing.primaryImage) ?? firstMedia(detailImages);
-  const images = selectedVariantImages.length > 0 ? selectedVariantImages : selectedValueImages.length > 0 ? selectedValueImages : matchingVariantImages.length > 0 ? matchingVariantImages : detailImages;
-  return {
-    primaryImage,
-    images
-  };
+  const productPool = mediaArray2(detail.images);
+  const resolvedMedia = resolveProductSelectionMedia({
+    productMediaPool: productPool,
+    productPrimaryMediaItemId: getRelationID(detail.primaryMediaItemId),
+    selectedVariant: selectedVariant ? {
+      id: selectedVariant.id,
+      images: selectedVariant.images
+    } : null,
+    matchingVariants: matchingVariants.map((variant) => ({
+      id: variant.id,
+      images: variant.images
+    })),
+    selectedOptionValues: selectedValues.map((value) => ({
+      id: value.id,
+      swatch: normalizeMatrixSwatch(value.swatch)
+    }))
+  });
+  if (resolvedMedia.source !== "none") {
+    return {
+      primaryImage: resolvedMedia.primaryImage,
+      images: resolvedMedia.images,
+      source: resolvedMedia.source
+    };
+  }
+  const displayMedia = resolveProductDisplayMedia({
+    productMediaPool: productPool,
+    productPrimaryMediaItemId: getRelationID(detail.primaryMediaItemId),
+    listingPrimaryImage: detail.listing.primaryImage ?? null
+  });
+  if (displayMedia.source !== "none") {
+    return {
+      primaryImage: displayMedia.primaryImage,
+      images: displayMedia.images,
+      source: displayMedia.source
+    };
+  }
+  return { primaryImage: null, images: [], source: "none" };
 }
 function buildSelectionStock(selectedVariant, matchingVariants) {
   if (selectedVariant) {
@@ -2951,7 +3928,9 @@ function buildSelectionStock(selectedVariant, matchingVariants) {
   };
 }
 function buildAvailableValueStock(variants) {
-  const activeVariants = variants.filter((variant) => variant.isActive !== false);
+  const activeVariants = variants.filter(
+    (variant) => variant.isActive !== false
+  );
   const isUnlimited = activeVariants.some((variant) => variant.isUnlimited);
   const availableStock = isUnlimited ? null : activeVariants.reduce(
     (sum, variant) => sum + Math.max(0, variant.stock - variant.reservedStock),
@@ -2963,6 +3942,19 @@ function buildAvailableValueStock(variants) {
     availableStock
   };
 }
+function buildProductSelectionAvailableValue(matrixValue, _productImages, selected, available, stock) {
+  return {
+    valueId: matrixValue.id,
+    value: matrixValue.label,
+    label: matrixValue.label,
+    slug: matrixValue.slug ?? "",
+    selected,
+    available,
+    exists: available,
+    ...stock,
+    swatch: matrixValue.swatch ?? null
+  };
+}
 function getCandidateVariantsForValue(matrix, optionId, valueId, selectedValueIds) {
   const selectedByOption = getSelectedValueByOptionId(matrix, selectedValueIds);
   selectedByOption.set(optionId, valueId);
@@ -2975,17 +3967,25 @@ function getCandidateVariantsForValue(matrix, optionId, valueId, selectedValueId
 function getResolutionContext(context) {
   return {
     images: context?.images ?? context?.detail?.images ?? [],
-    listing: context?.listing ?? context?.detail?.listing ?? {}
+    listing: context?.listing ?? context?.detail?.listing ?? {},
+    primaryMediaItemId: context?.primaryMediaItemId ?? context?.detail?.primaryMediaItemId ?? null
   };
 }
 function resolveProductSelectionFromMatrix(matrix, selection = {}, options, context) {
-  const { images, listing } = getResolutionContext(context);
+  const { images, listing, primaryMediaItemId } = getResolutionContext(context);
   const effectiveSelection = hasExplicitSelection(selection) || listing.selectionHintVariant == null ? selection : { ...selection, variantId: listing.selectionHintVariant };
-  const normalizedSelection = normalizeProductSelectionFromMatrix(
+  let normalizedSelection = normalizeProductSelectionFromMatrix(
     matrix,
     effectiveSelection,
     options
   );
+  if (options?.fillDefaults) {
+    normalizedSelection = buildFilledNormalizedSelection(
+      matrix,
+      normalizedSelection,
+      listing
+    );
+  }
   const matchingVariantEntries = getMatchingVariantEntries(
     matrix,
     normalizedSelection
@@ -3014,24 +4014,22 @@ function resolveProductSelectionFromMatrix(matrix, selection = {}, options, cont
       );
       return [
         option.id,
-        option.values.map((value) => ({
-          valueId: value.id,
-          value: value.label,
-          slug: value.slug ?? "",
-          selected: normalizedSelection.byOptionId[option.id] === value.id,
-          available: availableValueIds.has(value.id),
-          ...buildAvailableValueStock(
-            getCandidateVariantsForValue(
-              matrix,
-              option.id,
-              value.id,
-              normalizedSelection.valueIds
+        option.values.map(
+          (value) => buildProductSelectionAvailableValue(
+            value,
+            images,
+            normalizedSelection.byOptionId[option.id] === value.id,
+            availableValueIds.has(value.id),
+            buildAvailableValueStock(
+              getCandidateVariantsForValue(
+                matrix,
+                option.id,
+                value.id,
+                normalizedSelection.valueIds
+              )
             )
-          ),
-          swatchColor: value.swatchColor ?? null,
-          thumbnail: value.thumbnail ?? null,
-          images: value.images ?? null
-        }))
+          )
+        )
       ];
     })
   );
@@ -3059,7 +4057,8 @@ function resolveProductSelectionFromMatrix(matrix, selection = {}, options, cont
         images,
         listing: {
           primaryImage: listing.primaryImage ?? null
-        }
+        },
+        primaryMediaItemId
       },
       selectedVariant,
       matchingVariants,
@@ -3074,6 +4073,78 @@ function resolveProductSelection(detail, selection = {}, options) {
     detail
   });
 }
+function selectNext(detail, current = {}, optionSlug, valueSlug, options) {
+  const matrix = buildProductOptionMatrixFromDetail(detail);
+  const listing = detail.listing ?? {};
+  const normalizedCurrent = normalizeProductSelectionFromMatrix(
+    matrix,
+    current,
+    options
+  );
+  const option = matrix.optionBySlug.get(optionSlug);
+  if (!option) return normalizedCurrent;
+  const valueMatches = option.values.filter(
+    (candidate) => candidate.slug === valueSlug
+  );
+  if (valueMatches.length !== 1) return normalizedCurrent;
+  const clickedValueId = valueMatches[0].id;
+  const keepClickedSelection = () => {
+    const selectedByOptionId = /* @__PURE__ */ new Map();
+    selectedByOptionId.set(option.id, clickedValueId);
+    for (const otherOptionId of matrix.optionIds) {
+      if (otherOptionId === option.id) continue;
+      const otherValueId = normalizedCurrent.byOptionId[otherOptionId];
+      if (!otherValueId) continue;
+      const constraintIds = normalizeSelectedValueIds(
+        matrix,
+        Array.from(selectedByOptionId.values())
+      );
+      const available = getAvailableOptionValues(
+        matrix,
+        otherOptionId,
+        constraintIds
+      );
+      if (available.some((candidate) => candidate.id === otherValueId)) {
+        selectedByOptionId.set(otherOptionId, otherValueId);
+      }
+    }
+    return buildFilledNormalizedSelection(
+      matrix,
+      normalizedSelectionFromByOptionId(matrix, selectedByOptionId, null),
+      listing
+    );
+  };
+  const keepPriorSelection = () => {
+    const selectedByOptionId = new Map(
+      Object.entries(normalizedCurrent.byOptionId)
+    );
+    selectedByOptionId.delete(option.id);
+    return buildFilledNormalizedSelection(
+      matrix,
+      normalizedSelectionFromByOptionId(matrix, selectedByOptionId, null),
+      listing
+    );
+  };
+  const clickedResult = keepClickedSelection();
+  const clickedVariantId = resolveVariantIdForCompleteSelection(
+    matrix,
+    new Map(Object.entries(clickedResult.byOptionId))
+  );
+  const priorValueIds = Object.entries(normalizedCurrent.byOptionId).filter(([otherOptionId]) => otherOptionId !== option.id).map(([, valueId]) => valueId);
+  const clickedAvailableWithPrior = priorValueIds.length === 0 || getAvailableOptionValues(matrix, option.id, priorValueIds).some(
+    (candidate) => candidate.id === clickedValueId
+  );
+  if (clickedVariantId != null) {
+    const priorClickedValue = normalizedCurrent.byOptionId[option.id];
+    if (priorClickedValue != null && priorClickedValue !== clickedValueId) {
+      return clickedResult;
+    }
+    if (clickedAvailableWithPrior) {
+      return clickedResult;
+    }
+  }
+  return keepPriorSelection();
+}
 function isProductDetailImageMedia(value) {
   return typeof value === "object" && value !== null;
 }
@@ -3114,18 +4185,47 @@ function joinProductPath(basePath, slug, trailingSlash) {
 function getProductHrefGroupSelection(group, matrix) {
   if (!group) return null;
   if (group.variantId != null) return { variantId: group.variantId };
-  const listingVariantId = group.listing?.selectionHintVariant;
   const optionId = group.optionId != null ? String(group.optionId) : group.optionSlug ? matrix?.optionBySlug.get(group.optionSlug)?.id : void 0;
-  if (!optionId) {
-    return listingVariantId != null ? { variantId: listingVariantId } : null;
-  }
+  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 listingVariantId != null ? { variantId: listingVariantId } : null;
-  }
+  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",
@@ -3134,23 +4234,46 @@ function buildProductHref(product, group, options = {}) {
   );
   const params = new URLSearchParams();
   if (options.detail && options.selection) {
-    const selection = stringifyProductSelection(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);
+      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()}`;
     }
-    const [selectionEntry] = Object.entries(groupSelection.byOptionId ?? {});
-    if (selectionEntry) {
-      const [optionId, valueId] = selectionEntry;
-      params.set(`opt.${optionId}`, String(valueId));
+    if (appendGroupByOptionIdHrefParams(params, group, groupSelection, options)) {
       return `${path}?${params.toString()}`;
     }
   }
@@ -3177,6 +4300,26 @@ function isVariantAvailableForSale(variant) {
   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"
@@ -3202,11 +4345,28 @@ function buildProductListingProjection(product, variants) {
   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]);
+  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: productPrimaryImage ?? variantPrimaryImage,
+    primaryImage: resolveGenericListingPrimaryImage(
+      product,
+      resolvedProductMedia.primaryImage,
+      resolvedProductMedia.source
+    ),
     minPrice,
     maxPrice,
     minCompareAtPrice,
@@ -3218,7 +4378,40 @@ function buildProductListingProjection(product, variants) {
 function buildProductListingCard(item, options = {}) {
   const product = item.product;
   const groups = item.groups;
-  const primaryImage = firstMedia(product.thumbnail) ?? firstMedia(product.images ?? null) ?? null;
+  const variants = getProductListingCardVariants(item);
+  const projectedListing = buildProductListingProjection(product, variants);
+  const selectionHintVariant = getRelationID(product.listing?.selectionHintVariant) ?? 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 = aggregateListingPriceRange(groups);
   const availableForSale = groups.some(
     (group) => group.listing.availableForSale
@@ -3226,14 +4419,42 @@ function buildProductListingCard(item, options = {}) {
   const swatches = groups.length > 1 ? groups.map((group) => buildListingSwatch(product, group, options)) : [];
   return {
     id: String(product.id),
-    href: buildProductHref({ slug: product.slug }, void 0, options),
+    href: buildProductHref(
+      { slug: product.slug },
+      { listing: { selectionHintVariant } },
+      options
+    ),
     title: product.title,
-    primaryImage,
+    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 aggregateListingPriceRange(groups) {
   const minPrice = minOfNullable(groups.map((g) => g.listing.minPrice));
   const maxPrice = maxOfNullable(groups.map((g) => g.listing.maxPrice));
@@ -3253,17 +4474,16 @@ function aggregateListingPriceRange(groups) {
   };
 }
 function buildListingSwatch(product, group, options) {
-  const thumbnail = firstMedia(group.optionValueThumbnail) ?? firstMedia(group.optionValueImages) ?? null;
   return {
     optionId: group.optionId,
     optionValueId: group.optionValueId,
     label: group.optionValueLabel,
-    swatchColor: group.optionValueSwatchColor ?? null,
-    thumbnail,
+    swatch: group.optionValueSwatch ?? null,
     href: buildProductHref(
       { slug: product.slug },
       {
         optionId: group.optionId,
+        optionSlug: group.optionSlug,
         optionValueId: group.optionValueId,
         optionValueSlug: group.optionValueSlug,
         listing: group.listing
@@ -3298,19 +4518,34 @@ function buildProductListingGroupsByOption(args) {
       return [];
     }
     const listingBase = buildProductListingProjection(void 0, variants);
-    const optionValuePrimaryImage = extractEntityId(value.thumbnail) ?? getFirstMediaId(value.images);
-    const productFallbackImage = extractEntityId(args.product?.thumbnail) ?? getFirstMediaId(args.product?.images);
-    const groupPrimaryImage = getFirstAvailableVariantPrimaryImage(variants) ?? optionValuePrimaryImage ?? productFallbackImage;
+    const orderedVariants = sortVariantsForMediaSelection(variants);
+    const productMediaPool = (args.product?.images ?? []).filter(
+      (image) => image != null && typeof image === "object"
+    );
+    const resolvedMedia = resolveProductSelectionMedia({
+      productMediaPool,
+      productPrimaryMediaItemId: extractEntityId(
+        args.product?.primaryMediaItemId ?? null
+      ),
+      selectedVariant: null,
+      matchingVariants: orderedVariants,
+      selectedOptionValues: [
+        {
+          id: value.id,
+          swatch: normalizeMatrixSwatch(value.swatch)
+        }
+      ]
+    });
+    const groupPrimaryImage = extractEntityId(resolvedMedia.primaryImage) ?? getFirstAvailableVariantPrimaryImage(variants) ?? extractEntityId(args.product?.thumbnail) ?? getFirstMediaId(args.product?.images);
     return [
       {
         optionId: primaryOption.id,
         optionTitle: primaryOption.title,
+        optionSlug: primaryOption.slug,
         optionValueId: value.id,
         optionValueLabel: value.label,
         optionValueSlug: value.slug,
-        optionValueSwatchColor: value.swatchColor ?? null,
-        optionValueThumbnail: value.thumbnail ?? null,
-        optionValueImages: value.images ?? null,
+        optionValueSwatch: value.swatch ?? null,
         variantIds: variants.map((variant) => String(variant.id)),
         variantCount: variants.length,
         variants,
@@ -3323,6 +4558,162 @@ function buildProductListingGroupsByOption(args) {
   });
 }
 
+// src/utils/product-media.ts
+function mediaPointerOptionValues(values) {
+  return (values ?? []).filter((value) => value != null && value !== "").map((value) => ({
+    swatch: {
+      type: "media",
+      mediaItemId: value
+    }
+  }));
+}
+function resolveProductMedia(input) {
+  const resolved = resolveProductSelectionMedia({
+    ...input,
+    selectedVariant: input.selectedVariant ?? (input.variantFeaturedMediaItemId ? { images: [input.variantFeaturedMediaItemId] } : null),
+    selectedOptionValues: input.selectedOptionValues ?? mediaPointerOptionValues(input.selectedOptionValueMediaItemIds)
+  });
+  if (resolved.source !== "none") {
+    return {
+      ...resolved,
+      source: resolved.source === "variant_media_selected" ? "variant_featured" : resolved.source
+    };
+  }
+  const display = resolveProductDisplayMedia({
+    productMediaPool: input.productMediaPool,
+    productPrimaryMediaItemId: input.productPrimaryMediaItemId
+  });
+  return {
+    primaryImage: display.primaryImage,
+    images: display.images,
+    source: display.source
+  };
+}
+
+// src/utils/product-gallery.ts
+function mediaId(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 relationshipIds(values) {
+  if (!Array.isArray(values)) return [];
+  return values.map((value) => mediaId(value)).filter((value) => Boolean(value));
+}
+function buildPoolById2(pool) {
+  const poolById = /* @__PURE__ */ new Map();
+  for (const item of pool) {
+    const id = mediaId(item);
+    if (id) poolById.set(id, item);
+  }
+  return poolById;
+}
+function mediaSetItemsInPool(mediaSet, poolById) {
+  const seen = /* @__PURE__ */ new Set();
+  const items = [];
+  const primaryId = mediaId(mediaSet.primaryMediaItemId);
+  if (primaryId) {
+    const primary = poolById.get(primaryId);
+    if (primary) {
+      seen.add(primaryId);
+      items.push(primary);
+    }
+  }
+  for (const itemId of relationshipIds(mediaSet.items)) {
+    if (seen.has(itemId)) continue;
+    const item = poolById.get(itemId);
+    if (!item) continue;
+    seen.add(itemId);
+    items.push(item);
+  }
+  return items;
+}
+function resolveLegacyMediaSet(input) {
+  if (!Array.isArray(input.mediaSets)) return null;
+  const pool = input.productMediaPool ?? input.pool ?? [];
+  const poolById = buildPoolById2(pool);
+  const selectedVariantId = mediaId(input.selectedVariantId);
+  if (selectedVariantId) {
+    const exactSet = input.mediaSets.find(
+      (set) => set.matchType === "exact-variant" && relationshipIds(set.variantIds).includes(selectedVariantId)
+    );
+    if (exactSet) {
+      const images = mediaSetItemsInPool(exactSet, poolById);
+      if (images.length > 0) {
+        return {
+          primaryImage: images[0] ?? null,
+          images,
+          source: "exact_variant_set"
+        };
+      }
+    }
+  }
+  const selectedOptionValueIds = new Set(
+    relationshipIds(input.selectedOptionValueIds)
+  );
+  const optionSetMatches = input.mediaSets.filter((set) => set.matchType === "option-values").map((set) => {
+    const optionValueIds = relationshipIds(set.optionValueIds);
+    if (optionValueIds.length === 0) return null;
+    if (!optionValueIds.every((id) => selectedOptionValueIds.has(id))) {
+      return null;
+    }
+    const images = mediaSetItemsInPool(set, poolById);
+    if (images.length === 0) return null;
+    return { optionValueCount: optionValueIds.length, images };
+  }).filter(
+    (match) => Boolean(match)
+  ).sort((a, b) => b.optionValueCount - a.optionValueCount);
+  if (optionSetMatches.length > 0) {
+    const images = optionSetMatches[0].images;
+    return {
+      primaryImage: images[0] ?? null,
+      images,
+      source: "option_value_set"
+    };
+  }
+  const defaultSet = input.mediaSets.find((set) => set.matchType === "default");
+  if (defaultSet) {
+    const images = mediaSetItemsInPool(defaultSet, poolById);
+    if (images.length > 0) {
+      return {
+        primaryImage: images[0] ?? null,
+        images,
+        source: "default_set"
+      };
+    }
+  }
+  return {
+    primaryImage: null,
+    images: [],
+    source: "none"
+  };
+}
+function resolveProductGallery(input) {
+  const legacyResolved = resolveLegacyMediaSet(input);
+  if (legacyResolved && legacyResolved.source !== "none") return legacyResolved;
+  const selectedVariantId = mediaId(input.selectedVariantId);
+  const selectedOptionValueIds = relationshipIds(input.selectedOptionValueIds);
+  const selection = resolveProductSelectionMedia({
+    ...input,
+    productMediaPool: input.productMediaPool ?? input.pool ?? null,
+    selectedVariant: input.selectedVariant ?? (selectedVariantId ? { id: selectedVariantId } : null),
+    selectedOptionValues: input.selectedOptionValues ?? selectedOptionValueIds.map((id) => ({ id }))
+  });
+  if (selection.source !== "none") {
+    return selection;
+  }
+  return resolveProductDisplayMedia({
+    productMediaPool: input.productMediaPool ?? input.pool ?? null,
+    productPrimaryMediaItemId: input.productPrimaryMediaItemId,
+    listingPrimaryImage: input.listingPrimaryImage
+  });
+}
+
 // src/utils/image.ts
 var IMAGE_SIZES = [384, 768, 1536];
 function getImageUrl(image, displayWidth, dpr = 1) {