@01.software/sdk 0.29.0 → 0.31.0

package/dist/index.cjs

@@ -26,61 +26,48 @@ __export(src_exports, {
   COLLECTIONS: () => COLLECTIONS,
   CUSTOMER_PASSWORD_RESET_OPERATION: () => CUSTOMER_PASSWORD_RESET_OPERATION,
   CartApi: () => CartApi,
-  Client: () => Client,
-  CollectionClient: () => CollectionClient,
-  CollectionHooks: () => CollectionHooks,
-  CollectionQueryBuilder: () => CollectionQueryBuilder,
   CommerceClient: () => CommerceClient,
   CommunityClient: () => CommunityClient,
   ConfigError: () => ConfigError,
   ConflictError: () => ConflictError,
   CustomerAuth: () => CustomerAuth,
-  CustomerHooks: () => CustomerHooks,
   CustomerNamespace: () => CustomerNamespace,
   DiscountApi: () => DiscountApi,
   GoneError: () => GoneError,
   IMAGE_SIZES: () => IMAGE_SIZES,
   INTERNAL_COLLECTIONS: () => INTERNAL_COLLECTIONS,
-  ModerationApi: () => ModerationApi,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
   OrderApi: () => OrderApi,
   PermissionError: () => PermissionError,
   ProductApi: () => ProductApi,
   ProductSelectionCodecError: () => ProductSelectionCodecError,
-  QueryHooks: () => QueryHooks,
   RateLimitError: () => RateLimitError,
-  ReadOnlyCollectionClient: () => ReadOnlyCollectionClient,
   RealtimeConnection: () => RealtimeConnection,
   SDKError: () => SDKError,
   SERVER_COLLECTIONS: () => SERVER_COLLECTIONS,
   SERVER_ONLY_COLLECTIONS: () => SERVER_ONLY_COLLECTIONS,
-  ServerClient: () => ServerClient,
-  ServerCollectionClient: () => ServerCollectionClient,
-  ServerCollectionQueryBuilder: () => ServerCollectionQueryBuilder,
-  ServerCommerceClient: () => ServerCommerceClient,
   ServiceUnavailableError: () => ServiceUnavailableError,
   ShippingApi: () => ShippingApi,
   TimeoutError: () => TimeoutError,
   UsageLimitError: () => UsageLimitError,
   ValidationError: () => ValidationError,
+  buildProductHref: () => buildProductHref,
+  buildProductListingCard: () => buildProductListingCard,
   buildProductListingGroupsByOption: () => buildProductListingGroupsByOption,
   buildProductListingProjection: () => buildProductListingProjection,
   buildProductOptionMatrix: () => buildProductOptionMatrix,
   buildProductOptionMatrixFromDetail: () => buildProductOptionMatrixFromDetail,
-  collectionKeys: () => collectionKeys,
   createAnalytics: () => createAnalytics,
   createAuthError: () => createAuthError,
-  createClient: () => createClient,
+  createClient: () => createClient2,
   createConflictError: () => createConflictError,
   createCustomerAuthWebhookHandler: () => createCustomerAuthWebhookHandler,
   createNotFoundError: () => createNotFoundError,
   createPermissionError: () => createPermissionError,
   createProductSelectionCodec: () => createProductSelectionCodec,
   createRateLimitError: () => createRateLimitError,
-  createServerClient: () => createServerClient,
   createTypedWebhookHandler: () => createTypedWebhookHandler,
-  customerKeys: () => customerKeys,
   formatOrderName: () => formatOrderName,
   generateOrderNumber: () => generateOrderNumber,
   getAvailableOptionValues: () => getAvailableOptionValues,
@@ -89,7 +76,7 @@ __export(src_exports, {
   getImagePlaceholderStyle: () => getImagePlaceholderStyle,
   getImageSrcSet: () => getImageSrcSet,
   getImageUrl: () => getImageUrl,
-  getQueryClient: () => getQueryClient,
+  getProductSelectionImages: () => getProductSelectionImages,
   getSelectedValueByOptionId: () => getSelectedValueByOptionId,
   getVideoGif: () => getVideoGif,
   getVideoMp4Url: () => getVideoMp4Url,
@@ -114,255 +101,17 @@ __export(src_exports, {
   isValidWebhookEvent: () => isValidWebhookEvent,
   isValidationError: () => isValidationError,
   normalizeProductSelection: () => normalizeProductSelection,
+  normalizeProductSelectionFromMatrix: () => normalizeProductSelectionFromMatrix,
   normalizeSelectedValueIds: () => normalizeSelectedValueIds,
   parseProductSelection: () => parseProductSelection,
-  productKeys: () => productKeys,
   resolveProductSelection: () => resolveProductSelection,
+  resolveProductSelectionFromMatrix: () => resolveProductSelectionFromMatrix,
   resolveRelation: () => resolveRelation,
   resolveVariantForSelection: () => resolveVariantForSelection,
   stringifyProductSelection: () => stringifyProductSelection
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/utils/types.ts
-var resolveRelation = (ref) => {
-  if (typeof ref === "string" || typeof ref === "number" || ref === null || ref === void 0)
-    return null;
-  return ref;
-};
-
-// src/core/metadata/index.ts
-function extractSeo(doc) {
-  const seo = doc.seo ?? {};
-  const og = seo.openGraph ?? {};
-  return {
-    title: seo.title ?? doc.title ?? null,
-    description: seo.description ?? null,
-    noIndex: seo.noIndex ?? null,
-    canonical: seo.canonical ?? null,
-    openGraph: {
-      title: og.title ?? null,
-      description: og.description ?? null,
-      image: og.image ?? null
-    }
-  };
-}
-function generateMetadata(input, options) {
-  const title = input.title ?? void 0;
-  const description = input.description ?? void 0;
-  const ogTitle = input.openGraph?.title ?? title;
-  const ogDescription = input.openGraph?.description ?? description;
-  const image = resolveMetaImage(input.openGraph?.image);
-  return {
-    title,
-    description,
-    ...input.noIndex && { robots: { index: false, follow: false } },
-    ...input.canonical && { alternates: { canonical: input.canonical } },
-    openGraph: {
-      ...ogTitle && { title: ogTitle },
-      ...ogDescription && { description: ogDescription },
-      ...options?.siteName && { siteName: options.siteName },
-      ...image && { images: [image] }
-    },
-    twitter: {
-      card: image ? "summary_large_image" : "summary",
-      ...ogTitle && { title: ogTitle },
-      ...ogDescription && { description: ogDescription },
-      ...image && { images: [image.url] }
-    }
-  };
-}
-function resolveMetaImage(ref) {
-  const image = resolveRelation(ref);
-  if (!image) return null;
-  const sized = image.sizes?.["1536"];
-  const url = sized?.url || image.url;
-  if (!url) return null;
-  const width = sized?.url ? sized.width : image.width;
-  const height = sized?.url ? sized.height : image.height;
-  return {
-    url,
-    ...width && { width },
-    ...height && { height },
-    ...image.alt && { alt: image.alt }
-  };
-}
-
-// src/core/collection/query-builder.ts
-var ReadOnlyCollectionQueryBuilder = class {
-  constructor(api, collection) {
-    this.api = api;
-    this.collection = collection;
-  }
-  async find(options) {
-    return this.api.requestFind(
-      `/api/${String(this.collection)}`,
-      options
-    );
-  }
-  async findById(id, options) {
-    return this.api.requestFindById(
-      `/api/${String(this.collection)}/${String(id)}`,
-      options
-    );
-  }
-  async count(options) {
-    return this.api.requestCount(
-      `/api/${String(this.collection)}/count`,
-      options
-    );
-  }
-  async findMetadata(options, metadataOptions) {
-    const { docs } = await this.find({ ...options, limit: 1, depth: 1 });
-    const doc = docs[0];
-    if (!doc) return null;
-    return generateMetadata(
-      extractSeo(doc),
-      metadataOptions
-    );
-  }
-  async findMetadataById(id, metadataOptions) {
-    const doc = await this.findById(id, { depth: 1 });
-    return generateMetadata(
-      extractSeo(doc),
-      metadataOptions
-    );
-  }
-};
-var CollectionQueryBuilder = class {
-  constructor(api, collection) {
-    this.api = api;
-    this.collection = collection;
-  }
-  /**
-   * Find documents (list query)
-   * GET /api/{collection}
-   * @returns Payload CMS find response with docs array and pagination
-   */
-  async find(options) {
-    return this.api.requestFind(
-      `/api/${String(this.collection)}`,
-      options
-    );
-  }
-  /**
-   * Find document by ID
-   * GET /api/{collection}/{id}
-   * @returns Document object directly (no wrapper)
-   */
-  async findById(id, options) {
-    return this.api.requestFindById(
-      `/api/${String(this.collection)}/${String(id)}`,
-      options
-    );
-  }
-  /**
-   * Create a new document
-   * POST /api/{collection}
-   * @returns Payload CMS mutation response with doc and message
-   */
-  async create(data, options) {
-    const endpoint = `/api/${String(this.collection)}`;
-    if (options?.file) {
-      return this.api.requestCreateWithFile(
-        endpoint,
-        data,
-        options.file,
-        options.filename
-      );
-    }
-    return this.api.requestCreate(endpoint, data);
-  }
-  /**
-   * Update a document by ID
-   * PATCH /api/{collection}/{id}
-   * @returns Payload CMS mutation response with doc and message
-   */
-  async update(id, data, options) {
-    const endpoint = `/api/${String(this.collection)}/${String(id)}`;
-    if (options?.file) {
-      return this.api.requestUpdateWithFile(
-        endpoint,
-        data,
-        options.file,
-        options.filename
-      );
-    }
-    return this.api.requestUpdate(endpoint, data);
-  }
-  /**
-   * Count documents
-   * GET /api/{collection}/count
-   * @returns Count response with totalDocs
-   */
-  async count(options) {
-    return this.api.requestCount(
-      `/api/${String(this.collection)}/count`,
-      options
-    );
-  }
-  /**
-   * Find first matching document and return its Next.js Metadata.
-   * Applies depth: 1 (SEO image populate) and limit: 1 automatically.
-   * @returns Metadata or null if no document matches
-   */
-  async findMetadata(options, metadataOptions) {
-    const { docs } = await this.find({ ...options, limit: 1, depth: 1 });
-    const doc = docs[0];
-    if (!doc) return null;
-    return generateMetadata(
-      extractSeo(doc),
-      metadataOptions
-    );
-  }
-  /**
-   * Find document by ID and return its Next.js Metadata.
-   * Applies depth: 1 (SEO image populate) automatically.
-   * @returns Metadata (throws on 404)
-   */
-  async findMetadataById(id, metadataOptions) {
-    const doc = await this.findById(id, { depth: 1 });
-    return generateMetadata(
-      extractSeo(doc),
-      metadataOptions
-    );
-  }
-  /**
-   * Update multiple documents (bulk update)
-   * PATCH /api/{collection}
-   * @returns Payload CMS find response with updated docs
-   */
-  async updateMany(where, data) {
-    return this.api.requestUpdateMany(
-      `/api/${String(this.collection)}`,
-      { where, data }
-    );
-  }
-  /**
-   * Delete a document by ID
-   * DELETE /api/{collection}/{id}
-   * @returns Deleted document object directly (no wrapper)
-   */
-  async remove(id) {
-    return this.api.requestDelete(
-      `/api/${String(this.collection)}/${String(id)}`
-    );
-  }
-  /**
-   * Delete multiple documents (bulk delete)
-   * DELETE /api/{collection}
-   * @returns Payload CMS find response with deleted docs
-   */
-  async removeMany(where) {
-    return this.api.requestDeleteMany(
-      `/api/${String(this.collection)}`,
-      { where }
-    );
-  }
-};
-var ServerCollectionQueryBuilder = class extends CollectionQueryBuilder {
-};
-
 // src/core/collection/http-client.ts
 var import_qs_esm = require("qs-esm");
 
@@ -410,8 +159,16 @@ var ValidationError = class extends SDKError {
   }
 };
 var ApiError = class extends SDKError {
-  constructor(message, status, details, userMessage, suggestion) {
-    super("API_ERROR", message, status, details, userMessage, suggestion);
+  constructor(message, status, details, userMessage, suggestion, requestId) {
+    super(
+      "API_ERROR",
+      message,
+      status,
+      details,
+      userMessage,
+      suggestion,
+      requestId
+    );
     this.name = "ApiError";
   }
 };
@@ -462,19 +219,43 @@ var UsageLimitError = class extends SDKError {
 };
 var AuthError = class extends SDKError {
   constructor(message, details, userMessage, suggestion, requestId) {
-    super("auth_error", message, 401, details, userMessage, suggestion, requestId);
+    super(
+      "auth_error",
+      message,
+      401,
+      details,
+      userMessage,
+      suggestion,
+      requestId
+    );
     this.name = "AuthError";
   }
 };
 var PermissionError = class extends SDKError {
   constructor(message, details, userMessage, suggestion, requestId) {
-    super("permission_error", message, 403, details, userMessage, suggestion, requestId);
+    super(
+      "permission_error",
+      message,
+      403,
+      details,
+      userMessage,
+      suggestion,
+      requestId
+    );
     this.name = "PermissionError";
   }
 };
 var NotFoundError = class extends SDKError {
   constructor(message, details, userMessage, suggestion, requestId) {
-    super("not_found", message, 404, details, userMessage, suggestion, requestId);
+    super(
+      "not_found",
+      message,
+      404,
+      details,
+      userMessage,
+      suggestion,
+      requestId
+    );
     this.name = "NotFoundError";
   }
 };
@@ -486,7 +267,15 @@ var ConflictError = class extends SDKError {
 };
 var RateLimitError = class extends SDKError {
   constructor(message, retryAfter, details, userMessage, suggestion, requestId) {
-    super("rate_limit_exceeded", message, 429, details, userMessage, suggestion, requestId);
+    super(
+      "rate_limit_exceeded",
+      message,
+      429,
+      details,
+      userMessage,
+      suggestion,
+      requestId
+    );
     this.name = "RateLimitError";
     this.retryAfter = retryAfter;
   }
@@ -535,7 +324,7 @@ function isRateLimitError(error) {
 }
 var createNetworkError = (message, status, details, userMessage, suggestion) => new NetworkError(message, status, details, userMessage, suggestion);
 var createValidationError = (message, details, userMessage, suggestion, status) => new ValidationError(message, details, userMessage, suggestion, status);
-var createApiError = (message, status, details, userMessage, suggestion) => new ApiError(message, status, details, userMessage, suggestion);
+var createApiError = (message, status, details, userMessage, suggestion, requestId) => new ApiError(message, status, details, userMessage, suggestion, requestId);
 var createConfigError = (message, details, userMessage, suggestion) => new ConfigError(message, details, userMessage, suggestion);
 var createTimeoutError = (message, details, userMessage, suggestion) => new TimeoutError(message, details, userMessage, suggestion);
 var createUsageLimitError = (message, usage, details, userMessage, suggestion) => new UsageLimitError(message, usage, details, userMessage, suggestion);
@@ -543,7 +332,14 @@ var createAuthError = (message, details, userMessage, suggestion, requestId) =>
 var createPermissionError = (message, details, userMessage, suggestion, requestId) => new PermissionError(message, details, userMessage, suggestion, requestId);
 var createNotFoundError = (message, details, userMessage, suggestion, requestId) => new NotFoundError(message, details, userMessage, suggestion, requestId);
 var createConflictError = (message, details, userMessage, suggestion, requestId) => new ConflictError(message, details, userMessage, suggestion, requestId);
-var createRateLimitError = (message, retryAfter, details, userMessage, suggestion, requestId) => new RateLimitError(message, retryAfter, details, userMessage, suggestion, requestId);
+var createRateLimitError = (message, retryAfter, details, userMessage, suggestion, requestId) => new RateLimitError(
+  message,
+  retryAfter,
+  details,
+  userMessage,
+  suggestion,
+  requestId
+);
 
 // src/core/internal/utils/credentials.ts
 function requirePublishableKeyForSecret(apiName, publishableKey, secretKey) {
@@ -556,7 +352,10 @@ function requirePublishableKeyForSecret(apiName, publishableKey, secretKey) {
 }
 
 // src/core/client/types.ts
-function resolveApiUrl() {
+function resolveApiUrl(apiUrl) {
+  if (apiUrl) {
+    return apiUrl.replace(/\/$/, "");
+  }
   if (typeof process !== "undefined" && process.env) {
     const envUrl = process.env.SOFTWARE_API_URL || process.env.NEXT_PUBLIC_SOFTWARE_API_URL;
     if (envUrl) {
@@ -580,6 +379,22 @@ function debugLog(debug, type, message, data) {
     console.groupEnd();
   }
 }
+function redactSensitiveHeader(value) {
+  const prefix = value.toLowerCase().startsWith("bearer ") ? "Bearer " : "";
+  return value.length > 20 ? `${prefix}...****${value.slice(-8)}` : "****";
+}
+function redactSensitiveHeaders(headers) {
+  const redacted = Object.fromEntries(headers.entries());
+  if (redacted.authorization) {
+    redacted.authorization = redactSensitiveHeader(redacted.authorization);
+  }
+  if (redacted["x-preview-token"]) {
+    redacted["x-preview-token"] = redactSensitiveHeader(
+      redacted["x-preview-token"]
+    );
+  }
+  return redacted;
+}
 function getErrorSuggestion(status) {
   if (status === 400)
     return "The request data failed validation. Check field values and types.";
@@ -654,6 +469,12 @@ async function parseErrorBody(response) {
     return fallback;
   }
 }
+function getParsedErrorSuggestion(status, parsed) {
+  if (status === 403 && parsed.reason === "origin_not_allowed") {
+    return "Add the request origin to the tenant Browser API origins, then retry the browser request.";
+  }
+  return getErrorSuggestion(status);
+}
 async function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -667,7 +488,7 @@ function createHttpStatusError(status, parsed, details, requestId) {
     ...parsed.errors && { errors: parsed.errors },
     ...parsed.body && { body: parsed.body }
   };
-  const suggestion = getErrorSuggestion(status);
+  const suggestion = getParsedErrorSuggestion(status, parsed);
   if (status === 400 || status === 422) {
     return attachRequestId(
       createValidationError(
@@ -737,6 +558,7 @@ function createHttpStatusError(status, parsed, details, requestId) {
 }
 async function httpFetch(url, options) {
   const {
+    apiUrl,
     publishableKey,
     secretKey,
     customerToken,
@@ -746,7 +568,7 @@ async function httpFetch(url, options) {
     onUnauthorized,
     ...requestInit
   } = options || {};
-  const baseUrl = resolveApiUrl();
+  const baseUrl = resolveApiUrl(apiUrl);
   const retryConfig = {
     maxRetries: retry?.maxRetries ?? 3,
     retryableStatuses: retry?.retryableStatuses ?? DEFAULT_RETRYABLE_STATUSES,
@@ -772,11 +594,7 @@ async function httpFetch(url, options) {
       if (!headers.has("Content-Type") && requestInit.body && !(requestInit.body instanceof FormData)) {
         headers.set("Content-Type", "application/json");
       }
-      const redactedHeaders = Object.fromEntries(headers.entries());
-      if (redactedHeaders["authorization"]) {
-        const token = redactedHeaders["authorization"];
-        redactedHeaders["authorization"] = token.length > 20 ? `Bearer ...****${token.slice(-8)}` : "****";
-      }
+      const redactedHeaders = redactSensitiveHeaders(headers);
       debugLog(debug, "request", url, {
         method: requestInit.method || "GET",
         headers: redactedHeaders,
@@ -794,7 +612,7 @@ async function httpFetch(url, options) {
       debugLog(debug, "response", url, {
         status: response.status,
         statusText: response.statusText,
-        headers: Object.fromEntries(response.headers.entries())
+        headers: redactSensitiveHeaders(response.headers)
       });
       if (!response.ok) {
         if (isUsageLimitExceededResponse(response)) {
@@ -935,7 +753,7 @@ async function httpFetch(url, options) {
 
 // src/core/collection/http-client.ts
 var HttpClient = class {
-  constructor(publishableKey, secretKey, getCustomerToken, onUnauthorized, onRequestId) {
+  constructor(publishableKey, secretKey, getCustomerToken, onUnauthorized, onRequestId, apiUrl) {
     this.publishableKey = requirePublishableKeyForSecret(
       "CollectionClient",
       publishableKey,
@@ -945,9 +763,11 @@ var HttpClient = class {
     this.getCustomerToken = getCustomerToken;
     this.onUnauthorized = onUnauthorized;
     this.onRequestId = onRequestId;
+    this.apiUrl = apiUrl;
   }
   get defaultOptions() {
     const opts = {
+      apiUrl: this.apiUrl,
       publishableKey: this.publishableKey,
       secretKey: this.secretKey
     };
@@ -1065,159 +885,113 @@ var HttpClient = class {
   }
 };
 
-// src/core/collection/collection-client.ts
-function buildPayloadFormData(data, file, filename) {
-  const formData = new FormData();
-  formData.append("file", file, filename);
-  if (data != null) {
-    formData.append("_payload", JSON.stringify(data));
-  }
-  return formData;
+// src/utils/types.ts
+var resolveRelation = (ref) => {
+  if (typeof ref === "string" || typeof ref === "number" || ref === null || ref === void 0)
+    return null;
+  return ref;
+};
+
+// src/core/metadata/index.ts
+function extractSeo(doc) {
+  const seo = doc.seo ?? {};
+  const og = seo.openGraph ?? {};
+  return {
+    title: seo.title ?? doc.title ?? null,
+    description: seo.description ?? null,
+    noIndex: seo.noIndex ?? null,
+    canonical: seo.canonical ?? null,
+    openGraph: {
+      title: og.title ?? null,
+      description: og.description ?? null,
+      image: og.image ?? null
+    }
+  };
 }
-var CollectionClient = class extends HttpClient {
-  from(collection) {
-    return new CollectionQueryBuilder(this, collection);
-  }
-  // ============================================================================
-  // Payload-native methods
-  // ============================================================================
-  /**
-   * Find documents (list query)
-   * GET /api/{collection}
-   */
-  async requestFind(endpoint, options) {
-    const url = this.buildUrl(endpoint, options);
-    const response = await this.fetchWithTracking(url, {
-      ...this.defaultOptions,
-      method: "GET"
-    });
-    return this.parseFindResponse(response);
-  }
-  /**
-   * Find-like response from a custom endpoint
-   * POST /api/...custom-endpoint
-   */
-  async requestFindEndpoint(endpoint, data) {
-    const response = await this.fetchWithTracking(endpoint, {
-      ...this.defaultOptions,
-      method: "POST",
-      body: data ? JSON.stringify(data) : void 0
-    });
-    return this.parseFindResponse(response);
-  }
-  /**
-   * Find document by ID
-   * GET /api/{collection}/{id}
-   */
-  async requestFindById(endpoint, options) {
-    const url = this.buildUrl(endpoint, options);
-    const response = await this.fetchWithTracking(url, {
-      ...this.defaultOptions,
-      method: "GET"
-    });
-    return this.parseDocumentResponse(response);
-  }
-  /**
-   * Create document
-   * POST /api/{collection}
-   */
-  async requestCreate(endpoint, data) {
-    const response = await this.fetchWithTracking(endpoint, {
-      ...this.defaultOptions,
-      method: "POST",
-      body: data ? JSON.stringify(data) : void 0
-    });
-    return this.parseMutationResponse(response);
-  }
-  /**
-   * Update document
-   * PATCH /api/{collection}/{id}
-   */
-  async requestUpdate(endpoint, data) {
-    const response = await this.fetchWithTracking(endpoint, {
-      ...this.defaultOptions,
-      method: "PATCH",
-      body: data ? JSON.stringify(data) : void 0
-    });
-    return this.parseMutationResponse(response);
-  }
-  /**
-   * Count documents
-   * GET /api/{collection}/count
-   */
-  async requestCount(endpoint, options) {
-    const url = this.buildUrl(endpoint, options);
-    const response = await this.fetchWithTracking(url, {
-      ...this.defaultOptions,
-      method: "GET"
-    });
-    return this.parseDocumentResponse(response);
-  }
-  /**
-   * Update multiple documents (bulk update)
-   * PATCH /api/{collection}
-   */
-  async requestUpdateMany(endpoint, data) {
-    const response = await this.fetchWithTracking(endpoint, {
-      ...this.defaultOptions,
-      method: "PATCH",
-      body: JSON.stringify(data)
-    });
-    return this.parseFindResponse(response);
+function generateMetadata(input, options) {
+  const title = input.title ?? void 0;
+  const description = input.description ?? void 0;
+  const ogTitle = input.openGraph?.title ?? title;
+  const ogDescription = input.openGraph?.description ?? description;
+  const image = resolveMetaImage(input.openGraph?.image);
+  return {
+    title,
+    description,
+    ...input.noIndex && { robots: { index: false, follow: false } },
+    ...input.canonical && { alternates: { canonical: input.canonical } },
+    openGraph: {
+      ...ogTitle && { title: ogTitle },
+      ...ogDescription && { description: ogDescription },
+      ...options?.siteName && { siteName: options.siteName },
+      ...image && { images: [image] }
+    },
+    twitter: {
+      card: image ? "summary_large_image" : "summary",
+      ...ogTitle && { title: ogTitle },
+      ...ogDescription && { description: ogDescription },
+      ...image && { images: [image.url] }
+    }
+  };
+}
+function resolveMetaImage(ref) {
+  const image = resolveRelation(ref);
+  if (!image) return null;
+  const sized = image.sizes?.["1536"];
+  const url = sized?.url || image.url;
+  if (!url) return null;
+  const width = sized?.url ? sized.width : image.width;
+  const height = sized?.url ? sized.height : image.height;
+  return {
+    url,
+    ...width && { width },
+    ...height && { height },
+    ...image.alt && { alt: image.alt }
+  };
+}
+
+// src/core/collection/query-builder.ts
+var ReadOnlyCollectionQueryBuilder = class {
+  constructor(api, collection) {
+    this.api = api;
+    this.collection = collection;
   }
-  /**
-   * Delete document
-   * DELETE /api/{collection}/{id}
-   */
-  async requestDelete(endpoint) {
-    const response = await this.fetchWithTracking(endpoint, {
-      ...this.defaultOptions,
-      method: "DELETE"
-    });
-    return this.parseDocumentResponse(response);
+  async find(options) {
+    return this.api.requestFind(
+      `/api/${String(this.collection)}`,
+      options
+    );
   }
-  /**
-   * Delete multiple documents (bulk delete)
-   * DELETE /api/{collection}
-   */
-  async requestDeleteMany(endpoint, data) {
-    const response = await this.fetchWithTracking(endpoint, {
-      ...this.defaultOptions,
-      method: "DELETE",
-      body: JSON.stringify(data)
-    });
-    return this.parseFindResponse(response);
+  async findById(id, options) {
+    return this.api.requestFindById(
+      `/api/${String(this.collection)}/${String(id)}`,
+      options
+    );
   }
-  /**
-   * Create document with file upload
-   * POST /api/{collection} (multipart/form-data)
-   */
-  async requestCreateWithFile(endpoint, data, file, filename) {
-    const response = await this.fetchWithTracking(endpoint, {
-      ...this.defaultOptions,
-      method: "POST",
-      body: buildPayloadFormData(data, file, filename)
-    });
-    return this.parseMutationResponse(response);
+  async count(options) {
+    return this.api.requestCount(
+      `/api/${String(this.collection)}/count`,
+      options
+    );
   }
-  /**
-   * Update document with file upload
-   * PATCH /api/{collection}/{id} (multipart/form-data)
-   */
-  async requestUpdateWithFile(endpoint, data, file, filename) {
-    const response = await this.fetchWithTracking(endpoint, {
-      ...this.defaultOptions,
-      method: "PATCH",
-      body: buildPayloadFormData(data, file, filename)
-    });
-    return this.parseMutationResponse(response);
+  async findMetadata(options, metadataOptions) {
+    const { docs } = await this.find({ ...options, limit: 1, depth: 1 });
+    const doc = docs[0];
+    if (!doc) return null;
+    return generateMetadata(
+      extractSeo(doc),
+      metadataOptions
+    );
   }
-};
-var ServerCollectionClient = class extends CollectionClient {
-  from(collection) {
-    return new ServerCollectionQueryBuilder(this, collection);
+  async findMetadataById(id, metadataOptions) {
+    const doc = await this.findById(id, { depth: 1 });
+    return generateMetadata(
+      extractSeo(doc),
+      metadataOptions
+    );
   }
 };
+
+// src/core/collection/collection-client.ts
 var ReadOnlyCollectionClient = class extends HttpClient {
   from(collection) {
     return new ReadOnlyCollectionQueryBuilder(this, collection);
@@ -1248,126 +1022,6 @@ var ReadOnlyCollectionClient = class extends HttpClient {
   }
 };
 
-// src/core/collection/const.ts
-var INTERNAL_COLLECTIONS = [
-  "users",
-  "payload-kv",
-  "payload-locked-documents",
-  "payload-preferences",
-  "payload-migrations",
-  "payload-folders",
-  "field-configs",
-  "system-media",
-  "track-assets",
-  "audiences",
-  "email-logs",
-  "api-usage",
-  "tenant-analytics-daily",
-  "tenant-web-analytics-config",
-  "analytics-event-schemas",
-  "subscriptions",
-  "billing-history",
-  "inventory-reservations",
-  "order-status-logs",
-  "api-keys",
-  "personal-access-tokens",
-  "tenant-entitlements",
-  "tenant-purge-jobs",
-  "direct-upload-sessions",
-  "webhook-events",
-  "webhook-deliveries",
-  "audit-logs",
-  "plans",
-  "webhooks",
-  "event-registrations"
-];
-var COLLECTIONS = [
-  "tenants",
-  "tenant-metadata",
-  "tenant-logos",
-  "products",
-  "product-variants",
-  "product-options",
-  "product-option-values",
-  "product-categories",
-  "product-tags",
-  "product-collections",
-  "brands",
-  "brand-logos",
-  "orders",
-  "order-items",
-  "returns",
-  "return-items",
-  "fulfillments",
-  "fulfillment-items",
-  "transactions",
-  "customers",
-  "customer-profiles",
-  "customer-profile-lists",
-  "customer-addresses",
-  "carts",
-  "cart-items",
-  "discounts",
-  "shipping-policies",
-  "shipping-zones",
-  "documents",
-  "document-categories",
-  "document-types",
-  "articles",
-  "article-authors",
-  "article-categories",
-  "article-tags",
-  "playlists",
-  "playlist-categories",
-  "playlist-tags",
-  "tracks",
-  "track-categories",
-  "track-tags",
-  "galleries",
-  "gallery-categories",
-  "gallery-tags",
-  "gallery-items",
-  "links",
-  "link-categories",
-  "link-tags",
-  "canvases",
-  "canvas-node-types",
-  "canvas-edge-types",
-  "canvas-categories",
-  "canvas-tags",
-  "canvas-nodes",
-  "canvas-edges",
-  "videos",
-  "video-categories",
-  "video-tags",
-  "live-streams",
-  "images",
-  "forms",
-  "form-submissions",
-  // Community
-  "posts",
-  "comments",
-  "reactions",
-  "reaction-types",
-  "bookmarks",
-  "post-categories",
-  // Events
-  "event-calendars",
-  "events",
-  "event-categories",
-  "event-occurrences",
-  "event-tags"
-];
-var SERVER_ONLY_COLLECTIONS = [
-  "customer-groups",
-  "reports",
-  "community-bans"
-];
-var SERVER_COLLECTIONS = [
-  ...COLLECTIONS,
-  ...SERVER_ONLY_COLLECTIONS
-];
-
 // src/core/api/parse-response.ts
 async function parseApiResponse(response, endpoint) {
   let data;
@@ -1391,7 +1045,7 @@ async function parseApiResponse(response, endpoint) {
     if (reason === "validation_failed") {
       throw attachRequestId(createValidationError(errorMessage, data, errorMessage), requestId);
     }
-    if (reason === "token_expired" || reason === "token_invalid" || reason === "key_invalid" || reason === "key_revoked") {
+    if (reason === "token_expired" || reason === "token_invalid" || reason === "preview_token_invalid" || reason === "preview_token_required" || reason === "key_invalid" || reason === "key_revoked") {
       throw attachRequestId(createAuthError(errorMessage, data, errorMessage), requestId);
     }
     if (reason === "forbidden") {
@@ -1423,6 +1077,7 @@ var CommunityClient = class {
       options.secretKey
     );
     this.secretKey = options.secretKey;
+    this.apiUrl = options.apiUrl;
     this.customerToken = options.customerToken;
     this.onUnauthorized = options.onUnauthorized;
     this.onRequestId = options.onRequestId;
@@ -1437,6 +1092,7 @@ var CommunityClient = class {
     try {
       const response = await httpFetch(endpoint, {
         method,
+        apiUrl: this.apiUrl,
         publishableKey: this.publishableKey,
         secretKey: this.secretKey,
         customerToken: token ?? void 0,
@@ -1585,53 +1241,6 @@ var CommunityClient = 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.onRequestId = options.onRequestId;
-  }
-  async request(endpoint, body, options) {
-    const method = options?.method ?? "POST";
-    try {
-      const response = await httpFetch(endpoint, {
-        method,
-        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/community/moderation-api.ts
-var ModerationApi = class extends BaseApi {
-  constructor(options) {
-    super("ModerationApi", options);
-  }
-  banCustomer(params) {
-    return this.request("/api/community-bans/ban", params);
-  }
-  unbanCustomer(params) {
-    return this.request("/api/community-bans/unban", params);
-  }
-};
-
 // src/core/customer/customer-auth.ts
 var DEFAULT_TIMEOUT2 = 15e3;
 function safeGetItem(key) {
@@ -1642,10 +1251,10 @@ function safeGetItem(key) {
   }
 }
 var CustomerAuth = class {
-  constructor(publishableKey, options) {
+  constructor(publishableKey, options, apiUrl) {
     this.refreshPromise = null;
     this.publishableKey = publishableKey;
-    this.baseUrl = resolveApiUrl();
+    this.baseUrl = resolveApiUrl(apiUrl);
     const persist = options?.persist ?? true;
     if (persist) {
       const key = typeof persist === "string" ? persist : "customer-token";
@@ -1876,8 +1485,8 @@ var CustomerAuth = class {
 
 // src/core/customer/customer-namespace.ts
 var CustomerNamespace = class {
-  constructor(publishableKey, options) {
-    this.auth = new CustomerAuth(publishableKey, options);
+  constructor(publishableKey, options, apiUrl) {
+    this.auth = new CustomerAuth(publishableKey, options, apiUrl);
   }
 };
 
@@ -1895,6 +1504,7 @@ var CartApi = class {
       options.secretKey
     );
     this.secretKey = options.secretKey;
+    this.apiUrl = options.apiUrl;
     this.customerToken = options.customerToken;
     this.onUnauthorized = options.onUnauthorized;
     this.onRequestId = options.onRequestId;
@@ -1904,6 +1514,7 @@ var CartApi = class {
     try {
       const response = await httpFetch(endpoint, {
         method,
+        apiUrl: this.apiUrl,
         publishableKey: this.publishableKey,
         secretKey: this.secretKey,
         customerToken: token ?? void 0,
@@ -1954,6 +1565,7 @@ var CommerceClient = class {
   constructor(options) {
     const cartApi = new CartApi({
       publishableKey: options.publishableKey,
+      apiUrl: options.apiUrl,
       customerToken: options.customerToken,
       onUnauthorized: options.onUnauthorized,
       onRequestId: options.onRequestId
@@ -1963,6 +1575,7 @@ var CommerceClient = class {
       try {
         const response = await httpFetch(endpoint, {
           method: "POST",
+          apiUrl: options.apiUrl,
           publishableKey: options.publishableKey,
           customerToken: token ?? void 0,
           ...token && options.onUnauthorized && { onUnauthorized: options.onUnauthorized },
@@ -2006,730 +1619,7 @@ var CommerceClient = class {
     };
     this.shipping = {
       calculate: (params) => execute("/api/shipping-policies/calculate", params)
-    };
-  }
-};
-
-// 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` /
-   * `tenant_mismatch` / `feature_disabled`). For the reason behind a null,
-   * inspect `client.lastRequestId` against backend logs.
-   */
-  async detail(params) {
-    try {
-      return await this.request("/api/products/detail", params);
-    } catch (err) {
-      if (err instanceof NotFoundError) return null;
-      throw err;
-    }
-  }
-  /**
-   * Atomically create or update a product together with its options,
-   * option-values, and variants in a single transaction. Mirrors Shopify's
-   * `productSet` shape and is the canonical write path for the MCP
-   * `product-upsert` tool.
-   */
-  upsert(params) {
-    return this.request("/api/products/upsert", params);
-  }
-};
-
-// src/core/api/discount-api.ts
-var DiscountApi = class extends BaseApi {
-  constructor(options) {
-    super("DiscountApi", options);
-  }
-  validate(params) {
-    return this.request("/api/discounts/validate", params);
-  }
-};
-
-// src/core/api/shipping-api.ts
-var ShippingApi = class extends BaseApi {
-  constructor(options) {
-    super("ShippingApi", options);
-  }
-  calculate(params) {
-    return this.request("/api/shipping-policies/calculate", params);
-  }
-};
-
-// 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/commerce/server-commerce-client.ts
-var ServerCommerceClient = class {
-  constructor(options) {
-    const publishableKey = requirePublishableKeyForSecret(
-      "ServerCommerceClient",
-      options.publishableKey,
-      options.secretKey
-    );
-    const serverOptions = {
-      publishableKey,
-      secretKey: options.secretKey,
-      onRequestId: options.onRequestId
-    };
-    const productApi = new ProductApi(serverOptions);
-    const cartApi = new CartApi(serverOptions);
-    const discountApi = new DiscountApi(serverOptions);
-    const shippingApi = new ShippingApi(serverOptions);
-    const orderApi = new OrderApi(serverOptions);
-    this.product = {
-      stockCheck: productApi.stockCheck.bind(productApi),
-      listingGroups: productApi.listingGroups.bind(productApi),
-      detail: productApi.detail.bind(productApi),
-      upsert: productApi.upsert.bind(productApi)
-    };
-    this.cart = {
-      get: cartApi.getCart.bind(cartApi),
-      addItem: cartApi.addItem.bind(cartApi),
-      updateItem: cartApi.updateItem.bind(cartApi),
-      removeItem: cartApi.removeItem.bind(cartApi),
-      applyDiscount: cartApi.applyDiscount.bind(cartApi),
-      removeDiscount: cartApi.removeDiscount.bind(cartApi),
-      clear: cartApi.clearCart.bind(cartApi)
-    };
-    this.orders = {
-      checkout: orderApi.checkout.bind(orderApi),
-      create: orderApi.createOrder.bind(orderApi),
-      update: orderApi.updateOrder.bind(orderApi),
-      updateTransaction: orderApi.updateTransaction.bind(orderApi),
-      confirmPayment: orderApi.confirmPayment.bind(orderApi),
-      createFulfillment: orderApi.createFulfillment.bind(orderApi),
-      updateFulfillment: orderApi.updateFulfillment.bind(orderApi),
-      bulkImportFulfillments: orderApi.bulkImportFulfillments.bind(orderApi),
-      createReturn: orderApi.createReturn.bind(orderApi),
-      updateReturn: orderApi.updateReturn.bind(orderApi),
-      returnWithRefund: orderApi.returnWithRefund.bind(orderApi)
-    };
-    this.discounts = {
-      validate: discountApi.validate.bind(discountApi)
-    };
-    this.shipping = {
-      calculate: shippingApi.calculate.bind(shippingApi)
-    };
-  }
-};
-
-// src/core/query/get-query-client.ts
-var import_react_query = require("@tanstack/react-query");
-function makeQueryClient() {
-  return new import_react_query.QueryClient({
-    defaultOptions: {
-      queries: {
-        // Infinite staleTime: server-fetched data persists until explicitly invalidated.
-        // For browser clients needing fresher data, override per-query:
-        //   useQuery({ ..., staleTime: 5 * 60 * 1000 })
-        staleTime: Number.POSITIVE_INFINITY,
-        refetchOnWindowFocus: false
-      },
-      dehydrate: {
-        shouldDehydrateQuery: (query) => (0, import_react_query.defaultShouldDehydrateQuery)(query) || query.state.status === "pending",
-        shouldRedactErrors: () => false
-      }
-    }
-  });
-}
-var browserQueryClient;
-function getQueryClient() {
-  if (import_react_query.isServer) {
-    return makeQueryClient();
-  }
-  if (!browserQueryClient) {
-    browserQueryClient = makeQueryClient();
-  }
-  return browserQueryClient;
-}
-
-// src/core/query/query-hooks.ts
-var import_react_query4 = require("@tanstack/react-query");
-
-// src/core/query/collection-hooks.ts
-var import_react_query2 = require("@tanstack/react-query");
-
-// src/core/query/query-keys.ts
-function collectionKeys(collection) {
-  return {
-    all: [collection],
-    lists: () => [collection, "list"],
-    list: (options) => [collection, "list", options],
-    details: () => [collection, "detail"],
-    detail: (id, options) => [collection, "detail", id, options],
-    infinites: () => [collection, "infinite"],
-    infinite: (options) => [collection, "infinite", options]
-  };
-}
-var customerKeys = {
-  all: ["customer"],
-  me: () => ["customer", "me"]
-};
-var productKeys = {
-  listingGroups: (options) => ["products", "listing-groups", "list", options],
-  listingGroupsInfinite: (options) => ["products", "listing-groups", "infinite", options],
-  detail: (params) => ["products", "detail", params],
-  detailAll: () => ["products", "detail"]
-};
-
-// src/core/query/collection-hooks.ts
-var PRODUCT_DETAIL_INVALIDATING_COLLECTIONS = /* @__PURE__ */ new Set([
-  "products",
-  "product-variants",
-  "product-options",
-  "product-option-values",
-  "product-categories",
-  "product-tags",
-  "product-collections",
-  "brands",
-  "brand-logos",
-  "images"
-]);
-var DEFAULT_PAGE_SIZE = 20;
-var CollectionHooks = class {
-  constructor(queryClient, collectionClient) {
-    this.queryClient = queryClient;
-    this.collectionClient = collectionClient;
-  }
-  // ===== useQuery =====
-  useQuery(params, options) {
-    const { collection, options: queryOptions } = params;
-    const { placeholderData, ...restOptions } = options ?? {};
-    return (0, import_react_query2.useQuery)({
-      queryKey: collectionKeys(collection).list(queryOptions),
-      queryFn: async () => {
-        return await this.collectionClient.from(collection).find(queryOptions);
-      },
-      ...restOptions,
-      // NonFunctionGuard<T> incompatible with generic union types — safe cast
-      ...placeholderData !== void 0 && {
-        placeholderData
-      }
-    });
-  }
-  // ===== useSuspenseQuery =====
-  useSuspenseQuery(params, options) {
-    const { collection, options: queryOptions } = params;
-    return (0, import_react_query2.useSuspenseQuery)({
-      queryKey: collectionKeys(collection).list(queryOptions),
-      queryFn: async () => {
-        return await this.collectionClient.from(collection).find(queryOptions);
-      },
-      ...options
-    });
-  }
-  // ===== useQueryById =====
-  useQueryById(params, options) {
-    const { collection, id, options: queryOptions } = params;
-    const { placeholderData, ...restOptions } = options ?? {};
-    return (0, import_react_query2.useQuery)({
-      queryKey: collectionKeys(collection).detail(id, queryOptions),
-      queryFn: async () => {
-        return await this.collectionClient.from(collection).findById(id, queryOptions);
-      },
-      ...restOptions,
-      // NonFunctionGuard<T> incompatible with generic union types — safe cast
-      ...placeholderData !== void 0 && {
-        placeholderData
-      }
-    });
-  }
-  // ===== useSuspenseQueryById =====
-  useSuspenseQueryById(params, options) {
-    const { collection, id, options: queryOptions } = params;
-    return (0, import_react_query2.useSuspenseQuery)({
-      queryKey: collectionKeys(collection).detail(id, queryOptions),
-      queryFn: async () => {
-        return await this.collectionClient.from(collection).findById(id, queryOptions);
-      },
-      ...options
-    });
-  }
-  // ===== useInfiniteQuery =====
-  useInfiniteQuery(params, options) {
-    const {
-      collection,
-      options: queryOptions,
-      pageSize = DEFAULT_PAGE_SIZE
-    } = params;
-    return (0, import_react_query2.useInfiniteQuery)({
-      queryKey: collectionKeys(collection).infinite(queryOptions),
-      queryFn: async ({ pageParam }) => {
-        const response = await this.collectionClient.from(collection).find({ ...queryOptions, page: pageParam, limit: pageSize });
-        return response;
-      },
-      initialPageParam: 1,
-      getNextPageParam: (lastPage) => {
-        return lastPage.hasNextPage ? lastPage.nextPage : void 0;
-      },
-      ...options
-    });
-  }
-  // ===== useSuspenseInfiniteQuery =====
-  useSuspenseInfiniteQuery(params, options) {
-    const {
-      collection,
-      options: queryOptions,
-      pageSize = DEFAULT_PAGE_SIZE
-    } = params;
-    return (0, import_react_query2.useSuspenseInfiniteQuery)({
-      queryKey: collectionKeys(collection).infinite(queryOptions),
-      queryFn: async ({ pageParam }) => {
-        const response = await this.collectionClient.from(collection).find({ ...queryOptions, page: pageParam, limit: pageSize });
-        return response;
-      },
-      initialPageParam: 1,
-      getNextPageParam: (lastPage) => {
-        return lastPage.hasNextPage ? lastPage.nextPage : void 0;
-      },
-      ...options
-    });
-  }
-  // ===== prefetchQuery =====
-  async prefetchQuery(params, options) {
-    const { collection, options: queryOptions } = params;
-    return this.queryClient.prefetchQuery({
-      queryKey: collectionKeys(collection).list(queryOptions),
-      queryFn: async () => {
-        return await this.collectionClient.from(collection).find(queryOptions);
-      },
-      ...options
-    });
-  }
-  // ===== prefetchQueryById =====
-  async prefetchQueryById(params, options) {
-    const { collection, id, options: queryOptions } = params;
-    return this.queryClient.prefetchQuery({
-      queryKey: collectionKeys(collection).detail(id, queryOptions),
-      queryFn: async () => {
-        return await this.collectionClient.from(collection).findById(id, queryOptions);
-      },
-      ...options
-    });
-  }
-  // ===== prefetchInfiniteQuery =====
-  async prefetchInfiniteQuery(params, options) {
-    const {
-      collection,
-      options: queryOptions,
-      pageSize = DEFAULT_PAGE_SIZE
-    } = params;
-    return this.queryClient.prefetchInfiniteQuery({
-      queryKey: collectionKeys(collection).infinite(queryOptions),
-      queryFn: async ({ pageParam }) => {
-        const response = await this.collectionClient.from(collection).find({ ...queryOptions, page: pageParam, limit: pageSize });
-        return response;
-      },
-      initialPageParam: 1,
-      getNextPageParam: (lastPage) => {
-        return lastPage.hasNextPage ? lastPage.nextPage : void 0;
-      },
-      pages: options?.pages ?? 1,
-      staleTime: options?.staleTime
-    });
-  }
-  // ===== Mutation Hooks =====
-  useCreate(params, options) {
-    const { collection } = params;
-    return (0, import_react_query2.useMutation)({
-      mutationFn: async (variables) => {
-        return await this.collectionClient.from(collection).create(
-          variables.data,
-          variables.file ? { file: variables.file, filename: variables.filename } : void 0
-        );
-      },
-      onSuccess: (data) => {
-        this.queryClient.invalidateQueries({
-          queryKey: collectionKeys(collection).all
-        });
-        if (PRODUCT_DETAIL_INVALIDATING_COLLECTIONS.has(collection)) {
-          this.queryClient.invalidateQueries({ queryKey: ["products", "detail"] });
-        }
-        options?.onSuccess?.(data);
-      },
-      onError: options?.onError,
-      onSettled: options?.onSettled
-    });
-  }
-  useUpdate(params, options) {
-    const { collection } = params;
-    return (0, import_react_query2.useMutation)({
-      mutationFn: async (variables) => {
-        return await this.collectionClient.from(collection).update(
-          variables.id,
-          variables.data,
-          variables.file ? { file: variables.file, filename: variables.filename } : void 0
-        );
-      },
-      onSuccess: (data) => {
-        this.queryClient.invalidateQueries({
-          queryKey: collectionKeys(collection).all
-        });
-        if (PRODUCT_DETAIL_INVALIDATING_COLLECTIONS.has(collection)) {
-          this.queryClient.invalidateQueries({ queryKey: ["products", "detail"] });
-        }
-        options?.onSuccess?.(data);
-      },
-      onError: options?.onError,
-      onSettled: options?.onSettled
-    });
-  }
-  useRemove(params, options) {
-    const { collection } = params;
-    return (0, import_react_query2.useMutation)({
-      mutationFn: async (id) => {
-        return await this.collectionClient.from(collection).remove(id);
-      },
-      onSuccess: (data) => {
-        this.queryClient.invalidateQueries({
-          queryKey: collectionKeys(collection).all
-        });
-        if (PRODUCT_DETAIL_INVALIDATING_COLLECTIONS.has(collection)) {
-          this.queryClient.invalidateQueries({ queryKey: ["products", "detail"] });
-        }
-        options?.onSuccess?.(data);
-      },
-      onError: options?.onError,
-      onSettled: options?.onSettled
-    });
-  }
-  // ===== Cache Utilities =====
-  invalidateQueries(collection, type) {
-    const queryKey = type ? [collection, type] : [collection];
-    return this.queryClient.invalidateQueries({ queryKey });
-  }
-  getQueryData(collection, type, idOrOptions, options) {
-    if (type === "list") {
-      return this.queryClient.getQueryData(
-        collectionKeys(collection).list(idOrOptions)
-      );
-    }
-    return this.queryClient.getQueryData(
-      collectionKeys(collection).detail(idOrOptions, options)
-    );
-  }
-  setQueryData(collection, type, dataOrId, dataOrOptions, options) {
-    if (type === "list") {
-      this.queryClient.setQueryData(
-        collectionKeys(collection).list(dataOrOptions),
-        dataOrId
-      );
-    } else {
-      this.queryClient.setQueryData(
-        collectionKeys(collection).detail(dataOrId, options),
-        dataOrOptions
-      );
-    }
-  }
-};
-
-// src/core/query/customer-hooks.ts
-var import_react_query3 = require("@tanstack/react-query");
-function createMutation(mutationFn, callbacks, onSuccessExtra) {
-  return (0, import_react_query3.useMutation)({
-    mutationFn,
-    onSuccess: (data) => {
-      onSuccessExtra?.(data);
-      callbacks?.onSuccess?.(data);
-    },
-    onError: callbacks?.onError,
-    onSettled: callbacks?.onSettled
-  });
-}
-var CustomerHooks = class {
-  constructor(queryClient, customerAuth) {
-    this.invalidateMe = () => {
-      this.queryClient.invalidateQueries({ queryKey: customerKeys.me() });
-    };
-    this.queryClient = queryClient;
-    this.customerAuth = customerAuth;
-  }
-  ensureCustomerAuth() {
-    if (!this.customerAuth) {
-      throw createConfigError(
-        "Customer hooks require Client. Use createClient() instead of createServerClient()."
-      );
-    }
-    return this.customerAuth;
-  }
-  // ===== useCustomerMe =====
-  useCustomerMe(options) {
-    return (0, import_react_query3.useQuery)({
-      queryKey: customerKeys.me(),
-      queryFn: async () => {
-        return await this.ensureCustomerAuth().me();
-      },
-      ...options,
-      enabled: (options?.enabled ?? true) && !!this.customerAuth?.isAuthenticated()
-    });
-  }
-  // ===== Mutations =====
-  useCustomerLogin(options) {
-    return createMutation(
-      (data) => this.ensureCustomerAuth().login(data),
-      options,
-      this.invalidateMe
-    );
-  }
-  useCustomerRegister(options) {
-    return createMutation(
-      (data) => this.ensureCustomerAuth().register(data),
-      options
-    );
-  }
-  useCustomerLogout(options) {
-    return (0, import_react_query3.useMutation)({
-      mutationFn: async () => {
-        this.ensureCustomerAuth().logout();
-      },
-      onSuccess: () => {
-        this.queryClient.removeQueries({ queryKey: customerKeys.all });
-        options?.onSuccess?.();
-      },
-      onError: options?.onError,
-      onSettled: options?.onSettled
-    });
-  }
-  useCustomerForgotPassword(options) {
-    return createMutation(
-      (email) => this.ensureCustomerAuth().forgotPassword(email).then(() => {
-      }),
-      options
-    );
-  }
-  useCustomerResetPassword(options) {
-    return createMutation(
-      (data) => this.ensureCustomerAuth().resetPassword(data.token, data.password).then(() => {
-      }),
-      options
-    );
-  }
-  useCustomerRefreshToken(options) {
-    return createMutation(
-      () => this.ensureCustomerAuth().refreshToken(),
-      options,
-      this.invalidateMe
-    );
-  }
-  useCustomerUpdateProfile(options) {
-    return createMutation(
-      (data) => this.ensureCustomerAuth().updateProfile(data),
-      options,
-      this.invalidateMe
-    );
-  }
-  useCustomerChangePassword(options) {
-    return createMutation(
-      (data) => this.ensureCustomerAuth().changePassword(data.currentPassword, data.newPassword).then(() => {
-      }),
-      options
-    );
-  }
-  // ===== Customer Cache Utilities =====
-  invalidateCustomerQueries() {
-    return this.queryClient.invalidateQueries({ queryKey: customerKeys.all });
-  }
-  getCustomerData() {
-    return this.queryClient.getQueryData(customerKeys.me());
-  }
-  setCustomerData(data) {
-    this.queryClient.setQueryData(customerKeys.me(), data);
-  }
-};
-
-// src/core/query/query-hooks.ts
-var QueryHooks = class extends CollectionHooks {
-  constructor(queryClient, collectionClient, customerAuth, commerceClient) {
-    super(queryClient, collectionClient);
-    // --- Customer hooks delegation ---
-    this.useCustomerMe = (...args) => this._customer.useCustomerMe(...args);
-    this.useCustomerLogin = (...args) => this._customer.useCustomerLogin(...args);
-    this.useCustomerRegister = (...args) => this._customer.useCustomerRegister(...args);
-    this.useCustomerLogout = (...args) => this._customer.useCustomerLogout(...args);
-    this.useCustomerForgotPassword = (...args) => this._customer.useCustomerForgotPassword(...args);
-    this.useCustomerResetPassword = (...args) => this._customer.useCustomerResetPassword(...args);
-    this.useCustomerRefreshToken = (...args) => this._customer.useCustomerRefreshToken(...args);
-    this.useCustomerUpdateProfile = (...args) => this._customer.useCustomerUpdateProfile(...args);
-    this.useCustomerChangePassword = (...args) => this._customer.useCustomerChangePassword(...args);
-    // --- Customer cache delegation ---
-    this.invalidateCustomerQueries = () => this._customer.invalidateCustomerQueries();
-    this.getCustomerData = () => this._customer.getCustomerData();
-    this.setCustomerData = (data) => this._customer.setCustomerData(data);
-    this._customer = new CustomerHooks(queryClient, customerAuth);
-    this._commerce = commerceClient;
-  }
-  useProductListingGroupsQuery(params, options) {
-    const queryOptions = params.options;
-    const { placeholderData, ...restOptions } = options ?? {};
-    return (0, import_react_query4.useQuery)({
-      queryKey: productKeys.listingGroups(queryOptions),
-      queryFn: async () => this.collectionClient.requestFindEndpoint(
-        "/api/products/listing-groups/query",
-        { options: queryOptions }
-      ),
-      ...restOptions,
-      ...placeholderData !== void 0 && {
-        placeholderData
-      }
-    });
-  }
-  useSuspenseProductListingGroupsQuery(params, options) {
-    const queryOptions = params.options;
-    return (0, import_react_query4.useSuspenseQuery)({
-      queryKey: productKeys.listingGroups(queryOptions),
-      queryFn: async () => this.collectionClient.requestFindEndpoint(
-        "/api/products/listing-groups/query",
-        { options: queryOptions }
-      ),
-      ...options
-    });
-  }
-  useInfiniteProductListingGroupsQuery(params, options) {
-    const {
-      options: queryOptions,
-      pageSize = 20
-    } = params;
-    return (0, import_react_query4.useInfiniteQuery)({
-      queryKey: productKeys.listingGroupsInfinite(queryOptions),
-      queryFn: async ({ pageParam }) => this.collectionClient.requestFindEndpoint(
-        "/api/products/listing-groups/query",
-        {
-          options: { ...queryOptions, page: pageParam, limit: pageSize }
-        }
-      ),
-      initialPageParam: 1,
-      getNextPageParam: (lastPage) => lastPage.hasNextPage ? lastPage.nextPage : void 0,
-      ...options
-    });
-  }
-  useSuspenseInfiniteProductListingGroupsQuery(params, options) {
-    const {
-      options: queryOptions,
-      pageSize = 20
-    } = params;
-    return (0, import_react_query4.useSuspenseInfiniteQuery)({
-      queryKey: productKeys.listingGroupsInfinite(queryOptions),
-      queryFn: async ({ pageParam }) => this.collectionClient.requestFindEndpoint(
-        "/api/products/listing-groups/query",
-        {
-          options: { ...queryOptions, page: pageParam, limit: pageSize }
-        }
-      ),
-      initialPageParam: 1,
-      getNextPageParam: (lastPage) => lastPage.hasNextPage ? lastPage.nextPage : void 0,
-      ...options
-    });
-  }
-  async prefetchProductListingGroupsQuery(params, options) {
-    const queryOptions = params.options;
-    return this.queryClient.prefetchQuery({
-      queryKey: productKeys.listingGroups(queryOptions),
-      queryFn: async () => this.collectionClient.requestFindEndpoint(
-        "/api/products/listing-groups/query",
-        { options: queryOptions }
-      ),
-      ...options
-    });
-  }
-  async prefetchInfiniteProductListingGroupsQuery(params, options) {
-    const {
-      options: queryOptions,
-      pageSize = 20
-    } = params;
-    return this.queryClient.prefetchInfiniteQuery({
-      queryKey: productKeys.listingGroupsInfinite(queryOptions),
-      queryFn: async ({ pageParam }) => this.collectionClient.requestFindEndpoint(
-        "/api/products/listing-groups/query",
-        {
-          options: { ...queryOptions, page: pageParam, limit: pageSize }
-        }
-      ),
-      initialPageParam: 1,
-      getNextPageParam: (lastPage) => lastPage.hasNextPage ? lastPage.nextPage : void 0,
-      pages: options?.pages ?? 1,
-      staleTime: options?.staleTime
-    });
-  }
-  useProductDetail(params, options) {
-    const discriminator = "slug" in params ? params.slug : params.id;
-    const enabled = options?.enabled !== false && Boolean(discriminator);
-    return (0, import_react_query4.useQuery)({
-      queryKey: productKeys.detail(params),
-      queryFn: () => this._commerce.product.detail(params),
-      enabled
-    });
-  }
-  useProductDetailBySlug(slug, options) {
-    return this.useProductDetail({ slug }, options);
-  }
-  useProductDetailById(id, options) {
-    return this.useProductDetail({ id }, options);
+    };
   }
 };
 
@@ -2747,10 +1637,10 @@ var Client = class {
       userAgent: typeof window !== "undefined" ? window.navigator?.userAgent : "Node.js"
     };
     this.state = { metadata };
-    this.queryClient = getQueryClient();
     this.customer = new CustomerNamespace(
       this.config.publishableKey,
-      options.customer
+      options.customer,
+      this.config.apiUrl
     );
     const onUnauthorized = async () => {
       try {
@@ -2765,6 +1655,7 @@ var Client = class {
     };
     this.commerce = new CommerceClient({
       publishableKey: this.config.publishableKey,
+      apiUrl: this.config.apiUrl,
       customerToken: () => this.customer.auth.getToken(),
       onUnauthorized,
       onRequestId,
@@ -2772,29 +1663,18 @@ var Client = class {
     });
     this.community = new CommunityClient({
       publishableKey: this.config.publishableKey,
+      apiUrl: this.config.apiUrl,
       customerToken: () => this.customer.auth.getToken(),
       onUnauthorized,
       onRequestId
     });
-    const collectionClient = new CollectionClient(
-      this.config.publishableKey,
-      void 0,
-      () => this.customer.auth.getToken(),
-      onUnauthorized,
-      onRequestId
-    );
     this.collections = new ReadOnlyCollectionClient(
       this.config.publishableKey,
       void 0,
       () => this.customer.auth.getToken(),
       onUnauthorized,
-      onRequestId
-    );
-    this.query = new QueryHooks(
-      this.queryClient,
-      collectionClient,
-      this.customer.auth,
-      this.commerce
+      onRequestId,
+      this.config.apiUrl
     );
   }
   getState() {
@@ -2808,210 +1688,153 @@ function createClient(options) {
   return new Client(options);
 }
 
-// src/core/client/client.server.ts
-var ServerClient = class {
-  constructor(options) {
-    this.lastRequestId = null;
-    if (typeof window !== "undefined") {
-      throw createConfigError(
-        "ServerClient must not be used in a browser environment. This risks exposing your secretKey in client bundles. Use createClient() for browser code instead."
-      );
-    }
+// src/core/api/base-api.ts
+var BaseApi = class {
+  constructor(apiName, options) {
     if (!options.secretKey) {
-      throw createConfigError("secretKey is required.");
+      throw createConfigError(`secretKey is required for ${apiName}.`);
     }
-    if (!options.publishableKey) {
-      throw createConfigError(
-        "publishableKey is required. It is used for rate limiting and monthly quota enforcement via the X-Publishable-Key header. Get it from Console > Settings > API Keys."
-      );
+    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;
     }
-    this.config = { ...options, publishableKey: options.publishableKey };
-    const metadata = {
-      timestamp: Date.now(),
-      userAgent: "Node.js"
-    };
-    this.state = { metadata };
-    const onRequestId = (id) => {
-      this.lastRequestId = id;
-    };
-    const serverOptions = {
-      publishableKey: this.config.publishableKey,
-      secretKey: this.config.secretKey,
-      onRequestId
-    };
-    this.commerce = new ServerCommerceClient(serverOptions);
-    const communityClient = new CommunityClient(serverOptions);
-    const moderationApi = new ModerationApi(serverOptions);
-    this.community = Object.assign(communityClient, {
-      moderation: {
-        banCustomer: moderationApi.banCustomer.bind(moderationApi),
-        unbanCustomer: moderationApi.unbanCustomer.bind(moderationApi)
-      }
-    });
-    this.collections = new ServerCollectionClient(
-      this.config.publishableKey,
-      this.config.secretKey,
-      void 0,
-      void 0,
-      onRequestId
+  }
+};
+
+// 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
     );
-    this.queryClient = getQueryClient();
-    this.query = new QueryHooks(this.queryClient, this.collections, void 0, this.commerce);
   }
-  getState() {
-    return { ...this.state };
+  checkout(params) {
+    return this.request("/api/orders/checkout", params);
   }
-  getConfig() {
-    const { secretKey: _, ...safeConfig } = this.config;
-    return safeConfig;
+  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);
   }
 };
-function createServerClient(options) {
-  return new ServerClient(options);
-}
 
-// src/core/query/realtime.ts
-var INITIAL_RECONNECT_DELAY = 1e3;
-var MAX_RECONNECT_DELAY = 3e4;
-var RECONNECT_BACKOFF_FACTOR = 2;
-var MAX_NO_TOKEN_RETRIES = 5;
-var RealtimeConnection = class {
-  constructor(baseUrl, publishableKey, getToken, collections) {
-    this.baseUrl = baseUrl;
-    this.publishableKey = publishableKey;
-    this.getToken = getToken;
-    this.collections = collections;
-    this.abortController = null;
-    this.reconnectAttempt = 0;
-    this.noTokenAttempts = 0;
-    this.reconnectTimer = null;
-    this.listeners = /* @__PURE__ */ new Set();
-    this._connected = false;
-  }
-  get connected() {
-    return this._connected;
+// src/core/api/discount-api.ts
+var DiscountApi = class extends BaseApi {
+  constructor(options) {
+    super("DiscountApi", options);
   }
-  addListener(fn) {
-    this.listeners.add(fn);
-    return () => this.listeners.delete(fn);
+  validate(params) {
+    return this.request("/api/discounts/validate", params);
   }
-  connect() {
-    if (this.abortController) return;
-    this.abortController = new AbortController();
-    this.startStream(this.abortController.signal);
+};
+
+// src/core/api/shipping-api.ts
+var ShippingApi = class extends BaseApi {
+  constructor(options) {
+    super("ShippingApi", options);
   }
-  disconnect() {
-    this._connected = false;
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-    if (this.abortController) {
-      this.abortController.abort();
-      this.abortController = null;
-    }
-    this.reconnectAttempt = 0;
-    this.noTokenAttempts = 0;
+  calculate(params) {
+    return this.request("/api/shipping-policies/calculate", params);
   }
-  async startStream(signal) {
-    const token = this.getToken();
-    if (!token) {
-      this.noTokenAttempts++;
-      if (this.noTokenAttempts >= MAX_NO_TOKEN_RETRIES) {
-        this._connected = false;
-        this.abortController = null;
-        return;
-      }
-      this.scheduleReconnect();
-      return;
-    }
-    this.noTokenAttempts = 0;
-    const params = this.collections?.length ? `?collections=${this.collections.join(",")}` : "";
-    const url = `${this.baseUrl}/api/events/stream${params}`;
-    try {
-      const response = await fetch(url, {
-        headers: {
-          "X-Publishable-Key": this.publishableKey,
-          Authorization: `Bearer ${token}`
-        },
-        signal
-      });
-      if (!response.ok) {
-        if (response.status === 401) {
-          this.scheduleReconnect();
-          return;
-        }
-        throw new Error(`SSE connection failed: ${response.status}`);
-      }
-      if (!response.body) {
-        throw new Error("SSE response has no body");
-      }
-      this._connected = true;
-      this.reconnectAttempt = 0;
-      await this.readStream(response.body, signal);
-    } catch {
-      if (signal.aborted) return;
-      this._connected = false;
-      this.scheduleReconnect();
-    }
+};
+
+// src/core/api/product-api.ts
+var ProductApi = class extends BaseApi {
+  constructor(options) {
+    super("ProductApi", options);
   }
-  async readStream(body, signal) {
-    const reader = body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    let currentEvent = "";
-    let currentData = "";
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done || signal.aborted) break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() ?? "";
-        for (const line of lines) {
-          if (line.startsWith("event: ")) {
-            currentEvent = line.slice(7);
-          } else if (line.startsWith("data: ")) {
-            currentData += (currentData ? "\n" : "") + line.slice(6);
-          } else if (line === "") {
-            if (currentEvent === "collection:change" && currentData) {
-              try {
-                const event = JSON.parse(currentData);
-                for (const listener of this.listeners) {
-                  try {
-                    listener(event);
-                  } catch {
-                  }
-                }
-              } catch {
-              }
-            }
-            currentEvent = "";
-            currentData = "";
-          }
-        }
-      }
-    } catch {
-    } finally {
-      reader.releaseLock();
-      this._connected = false;
-      if (!signal.aborted) {
-        this.scheduleReconnect();
-      }
-    }
+  /**
+   * 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);
   }
-  scheduleReconnect() {
-    if (this.reconnectTimer) return;
-    const delay2 = Math.min(
-      INITIAL_RECONNECT_DELAY * Math.pow(RECONNECT_BACKOFF_FACTOR, this.reconnectAttempt),
-      MAX_RECONNECT_DELAY
+  listingGroups(params) {
+    return this.request(
+      "/api/products/listing-groups",
+      params
     );
-    this.reconnectAttempt++;
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      this.abortController = new AbortController();
-      this.startStream(this.abortController.signal);
-    }, delay2);
+  }
+  /**
+   * Fetch full product detail by slug or id.
+   * Returns `null` on 404 regardless of reason (`not_found` / `not_published` /
+   * `tenant_mismatch` / `feature_disabled`). For the reason behind a null,
+   * inspect `client.lastRequestId` against backend logs.
+   */
+  async detail(params) {
+    try {
+      return await this.request("/api/products/detail", params);
+    } catch (err) {
+      if (err instanceof NotFoundError) return null;
+      throw err;
+    }
+  }
+  /**
+   * Atomically create or update a product together with its options,
+   * option-values, and variants in a single transaction. Mirrors Shopify's
+   * `productSet` shape and is the canonical write path for the MCP
+   * `product-upsert` tool.
+   */
+  upsert(params) {
+    return this.request("/api/products/upsert", params);
   }
 };
 
@@ -3096,41 +1919,307 @@ async function handleWebhook(request, handler, options) {
           { status: 401, headers: { "Content-Type": "application/json" } }
         );
       }
-    } else {
-      console.warn(
-        "[@01.software/sdk] Webhook signature verification is disabled. Set { secret } in handleWebhook() options to enable HMAC-SHA256 verification."
-      );
+    } else {
+      console.warn(
+        "[@01.software/sdk] Webhook signature verification is disabled. Set { secret } in handleWebhook() options to enable HMAC-SHA256 verification."
+      );
+    }
+    const body = JSON.parse(rawBody);
+    if (!isValidWebhookEvent(body)) {
+      return new Response(
+        JSON.stringify({ error: "Invalid webhook event format" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+    await handler(body);
+    return new Response(
+      JSON.stringify({ success: true, message: "Webhook processed" }),
+      { status: 200, headers: { "Content-Type": "application/json" } }
+    );
+  } catch (error) {
+    console.error("Webhook processing error:", error);
+    return new Response(JSON.stringify({ error: "Internal server error" }), {
+      status: 500,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+}
+function createTypedWebhookHandler(collection, handler) {
+  return async (event) => {
+    if (event.collection !== collection) {
+      throw new Error(
+        `Expected collection "${collection}", got "${event.collection}"`
+      );
+    }
+    return handler(event);
+  };
+}
+
+// src/core/collection/const.ts
+var INTERNAL_COLLECTIONS = [
+  "users",
+  "payload-kv",
+  "payload-locked-documents",
+  "payload-preferences",
+  "payload-migrations",
+  "payload-folders",
+  "field-configs",
+  "system-media",
+  "track-assets",
+  "audiences",
+  "email-logs",
+  "api-usage",
+  "tenant-analytics-daily",
+  "tenant-web-analytics-config",
+  "analytics-event-schemas",
+  "subscriptions",
+  "billing-history",
+  "inventory-reservations",
+  "product-collection-items",
+  "order-status-logs",
+  "api-keys",
+  "personal-access-tokens",
+  "tenant-entitlements",
+  "tenant-purge-jobs",
+  "direct-upload-sessions",
+  "webhook-events",
+  "webhook-deliveries",
+  "audit-logs",
+  "plans",
+  "webhooks",
+  "event-registrations"
+];
+var COLLECTIONS = [
+  "tenants",
+  "tenant-metadata",
+  "tenant-logos",
+  "products",
+  "product-variants",
+  "product-options",
+  "product-option-values",
+  "product-categories",
+  "product-tags",
+  "product-collections",
+  "brands",
+  "brand-logos",
+  "orders",
+  "order-items",
+  "returns",
+  "return-items",
+  "fulfillments",
+  "fulfillment-items",
+  "transactions",
+  "customers",
+  "customer-profiles",
+  "customer-addresses",
+  "carts",
+  "cart-items",
+  "discounts",
+  "shipping-policies",
+  "shipping-zones",
+  "documents",
+  "document-categories",
+  "document-types",
+  "articles",
+  "article-authors",
+  "article-categories",
+  "article-tags",
+  "playlists",
+  "playlist-categories",
+  "playlist-tags",
+  "tracks",
+  "track-categories",
+  "track-tags",
+  "galleries",
+  "gallery-categories",
+  "gallery-tags",
+  "gallery-items",
+  "links",
+  "link-categories",
+  "link-tags",
+  "canvases",
+  "canvas-node-types",
+  "canvas-edge-types",
+  "canvas-categories",
+  "canvas-tags",
+  "canvas-nodes",
+  "canvas-edges",
+  "videos",
+  "video-categories",
+  "video-tags",
+  "live-streams",
+  "images",
+  "forms",
+  "form-submissions",
+  // Community
+  "posts",
+  "comments",
+  "reactions",
+  "reaction-types",
+  "bookmarks",
+  "post-categories",
+  "customer-profile-lists",
+  // Events
+  "event-calendars",
+  "events",
+  "event-categories",
+  "event-occurrences",
+  "event-tags"
+];
+var SERVER_ONLY_COLLECTIONS = [
+  "customer-groups",
+  "reports",
+  "community-bans"
+];
+var SERVER_COLLECTIONS = [
+  ...COLLECTIONS,
+  ...SERVER_ONLY_COLLECTIONS
+];
+
+// src/core/query/realtime.ts
+var INITIAL_RECONNECT_DELAY = 1e3;
+var MAX_RECONNECT_DELAY = 3e4;
+var RECONNECT_BACKOFF_FACTOR = 2;
+var MAX_NO_TOKEN_RETRIES = 5;
+var RealtimeConnection = class {
+  constructor(baseUrl, publishableKey, getToken, collections) {
+    this.baseUrl = baseUrl;
+    this.publishableKey = publishableKey;
+    this.getToken = getToken;
+    this.collections = collections;
+    this.abortController = null;
+    this.reconnectAttempt = 0;
+    this.noTokenAttempts = 0;
+    this.reconnectTimer = null;
+    this.listeners = /* @__PURE__ */ new Set();
+    this._connected = false;
+  }
+  get connected() {
+    return this._connected;
+  }
+  addListener(fn) {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+  connect() {
+    if (this.abortController) return;
+    this.abortController = new AbortController();
+    this.startStream(this.abortController.signal);
+  }
+  disconnect() {
+    this._connected = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.reconnectAttempt = 0;
+    this.noTokenAttempts = 0;
+  }
+  async startStream(signal) {
+    const token = this.getToken();
+    if (!token) {
+      this.noTokenAttempts++;
+      if (this.noTokenAttempts >= MAX_NO_TOKEN_RETRIES) {
+        this._connected = false;
+        this.abortController = null;
+        return;
+      }
+      this.scheduleReconnect();
+      return;
+    }
+    this.noTokenAttempts = 0;
+    const params = this.collections?.length ? `?collections=${this.collections.join(",")}` : "";
+    const url = `${this.baseUrl}/api/events/stream${params}`;
+    try {
+      const response = await fetch(url, {
+        headers: {
+          "X-Publishable-Key": this.publishableKey,
+          Authorization: `Bearer ${token}`
+        },
+        signal
+      });
+      if (!response.ok) {
+        if (response.status === 401) {
+          this.scheduleReconnect();
+          return;
+        }
+        throw new Error(`SSE connection failed: ${response.status}`);
+      }
+      if (!response.body) {
+        throw new Error("SSE response has no body");
+      }
+      this._connected = true;
+      this.reconnectAttempt = 0;
+      await this.readStream(response.body, signal);
+    } catch {
+      if (signal.aborted) return;
+      this._connected = false;
+      this.scheduleReconnect();
     }
-    const body = JSON.parse(rawBody);
-    if (!isValidWebhookEvent(body)) {
-      return new Response(
-        JSON.stringify({ error: "Invalid webhook event format" }),
-        { status: 400, headers: { "Content-Type": "application/json" } }
-      );
+  }
+  async readStream(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let currentEvent = "";
+    let currentData = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done || signal.aborted) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line.startsWith("event: ")) {
+            currentEvent = line.slice(7);
+          } else if (line.startsWith("data: ")) {
+            currentData += (currentData ? "\n" : "") + line.slice(6);
+          } else if (line === "") {
+            if (currentEvent === "collection:change" && currentData) {
+              try {
+                const event = JSON.parse(currentData);
+                for (const listener of this.listeners) {
+                  try {
+                    listener(event);
+                  } catch {
+                  }
+                }
+              } catch {
+              }
+            }
+            currentEvent = "";
+            currentData = "";
+          }
+        }
+      }
+    } catch {
+    } finally {
+      reader.releaseLock();
+      this._connected = false;
+      if (!signal.aborted) {
+        this.scheduleReconnect();
+      }
     }
-    await handler(body);
-    return new Response(
-      JSON.stringify({ success: true, message: "Webhook processed" }),
-      { status: 200, headers: { "Content-Type": "application/json" } }
+  }
+  scheduleReconnect() {
+    if (this.reconnectTimer) return;
+    const delay2 = Math.min(
+      INITIAL_RECONNECT_DELAY * Math.pow(RECONNECT_BACKOFF_FACTOR, this.reconnectAttempt),
+      MAX_RECONNECT_DELAY
     );
-  } catch (error) {
-    console.error("Webhook processing error:", error);
-    return new Response(JSON.stringify({ error: "Internal server error" }), {
-      status: 500,
-      headers: { "Content-Type": "application/json" }
-    });
+    this.reconnectAttempt++;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.abortController = new AbortController();
+      this.startStream(this.abortController.signal);
+    }, delay2);
   }
-}
-function createTypedWebhookHandler(collection, handler) {
-  return async (event) => {
-    if (event.collection !== collection) {
-      throw new Error(
-        `Expected collection "${collection}", got "${event.collection}"`
-      );
-    }
-    return handler(event);
-  };
-}
+};
 
 // src/utils/ecommerce.ts
 var ProductSelectionCodecError = class extends Error {
@@ -3416,38 +2505,45 @@ function hasExplicitSelection(selection) {
   );
 }
 function assignSelectedValue(matrix, selectedByOptionId, optionId, valueId) {
-  if (valueId == null) return;
+  if (valueId == null) return false;
   const normalizedValueId = String(valueId);
-  if (matrix.valueToOptionId.get(normalizedValueId) !== optionId) return;
+  if (matrix.valueToOptionId.get(normalizedValueId) !== optionId) return false;
   selectedByOptionId.set(optionId, normalizedValueId);
+  return true;
 }
 function assignSelectedValueSlugByOptionId(matrix, selectedByOptionId, optionId, valueSlug) {
-  if (!valueSlug) return;
+  if (!valueSlug) return false;
   const option = matrix.optionById.get(optionId);
-  if (!option) return;
-  const value = option.values.find((candidate) => candidate.slug === valueSlug);
-  if (!value) return;
+  if (!option) return false;
+  const values = option.values.filter(
+    (candidate) => candidate.slug === valueSlug
+  );
+  if (values.length > 1) {
+    throw new ProductSelectionCodecError(
+      `Ambiguous product selection value slug "${valueSlug}" for option "${optionId}". Use opt.<optionId>=<valueId>.`
+    );
+  }
+  const value = values[0];
+  if (!value) return false;
   selectedByOptionId.set(optionId, value.id);
+  return true;
 }
 function assignSelectedValueSlugByOptionSlug(matrix, selectedByOptionId, optionSlug, valueSlug) {
-  if (!valueSlug) return;
+  if (!valueSlug) return false;
   const option = matrix.optionBySlug.get(optionSlug);
-  if (!option) return;
-  const value = option.values.find((candidate) => candidate.slug === valueSlug);
-  if (!value) return;
-  selectedByOptionId.set(option.id, value.id);
-}
-function requireValueSlug(value) {
-  if (value.slug) return value.slug;
-  throw new ProductSelectionCodecError(
-    `Option value "${value.id}" does not have a slug and cannot be used in product selection URLs.`
-  );
-}
-function requireOptionSlug(option) {
-  if (option.slug) return option.slug;
-  throw new ProductSelectionCodecError(
-    `Option "${option.id}" does not have a slug and cannot be used in product selection URLs.`
+  if (!option) return false;
+  const values = option.values.filter(
+    (candidate) => candidate.slug === valueSlug
   );
+  if (values.length > 1) {
+    throw new ProductSelectionCodecError(
+      `Ambiguous product selection value slug "${valueSlug}" for option "${optionSlug}". Use opt.<optionId>=<valueId>.`
+    );
+  }
+  const value = values[0];
+  if (!value) return false;
+  selectedByOptionId.set(option.id, value.id);
+  return true;
 }
 function toSearchParams(search) {
   if (!search) return new URLSearchParams();
@@ -3471,6 +2567,15 @@ function slugLike(value) {
 }
 function assertNoAmbiguousSelectionParams(matrix, params) {
   const knownSelectionKeys = /* @__PURE__ */ new Set();
+  const hasVariantParam = params.has("variant");
+  const hasOptionParams = Array.from(params.keys()).some(
+    (key) => key.startsWith("opt.")
+  );
+  if (hasVariantParam && hasOptionParams) {
+    throw new ProductSelectionCodecError(
+      "Product selection URL cannot mix variant=<variantId> with opt.<optionId>=<valueId> params."
+    );
+  }
   for (const option of matrix.options) {
     knownSelectionKeys.add(slugLike(option.slug));
     knownSelectionKeys.add(slugLike(option.title));
@@ -3483,12 +2588,25 @@ function assertNoAmbiguousSelectionParams(matrix, params) {
       const optionToken = key.slice(4);
       if (!optionToken || !matrix.optionBySlug.has(optionToken) && !matrix.optionById.has(optionToken)) {
         throw new ProductSelectionCodecError(
-          `Unknown product selection query parameter "${key}". Use opt.<optionSlug>=<valueSlug>.`
+          `Unknown product selection query parameter "${key}". Use opt.<optionId>=<valueId>.`
+        );
+      }
+      if (!value) {
+        throw new ProductSelectionCodecError(
+          `Product selection query parameter "${key}" requires a value ID or compatibility value slug.`
         );
       }
+      continue;
+    }
+    if (key === "variant") {
       if (!value) {
         throw new ProductSelectionCodecError(
-          `Product selection query parameter "${key}" requires a value slug.`
+          'Product selection query parameter "variant" requires a variant ID.'
+        );
+      }
+      if (!getVariantSelection(matrix, value)) {
+        throw new ProductSelectionCodecError(
+          `Unknown product selection variant "${value}".`
         );
       }
       continue;
@@ -3496,55 +2614,97 @@ function assertNoAmbiguousSelectionParams(matrix, params) {
     const keyToken = slugLike(key);
     if (knownSelectionKeys.has(keyToken) || value === "" && knownSelectionKeys.has(keyToken)) {
       throw new ProductSelectionCodecError(
-        `Ambiguous product selection query parameter "${key}". Use opt.<optionSlug>=<valueSlug>.`
+        `Ambiguous product selection query parameter "${key}". Use opt.<optionId>=<valueId>.`
       );
     }
   }
 }
-function emitLegacyOptionIdParam(options, event) {
+function emitCompatibilityOptionIdParam(options, event) {
   try {
+    if (options?.onCompatibilityOptionIdParam) {
+      options.onCompatibilityOptionIdParam(event);
+      return;
+    }
     options?.onLegacyOptionIdParam?.(event);
   } catch {
   }
 }
 function assignSearchSelection(matrix, selectedByOptionId, search, options) {
-  if (!search) return;
+  if (!search) return null;
   const params = toSearchParams(search);
   assertNoAmbiguousSelectionParams(matrix, params);
-  for (const [key, valueSlug] of params.entries()) {
+  const variantParam = params.get("variant");
+  if (variantParam != null) {
+    const variantSelection = getVariantSelection(matrix, variantParam);
+    if (!variantSelection) {
+      throw new ProductSelectionCodecError(
+        `Unknown product selection variant "${variantParam}".`
+      );
+    }
+    for (const [optionId, valueId] of variantSelection.optionValueByOptionId) {
+      selectedByOptionId.set(optionId, valueId);
+    }
+    return variantSelection.id;
+  }
+  for (const [key, valueToken] of params.entries()) {
     if (!key.startsWith("opt.")) continue;
     const optionToken = key.slice(4);
+    const optionById = matrix.optionById.get(optionToken);
+    if (optionById) {
+      if (assignSelectedValue(
+        matrix,
+        selectedByOptionId,
+        optionById.id,
+        valueToken
+      )) {
+        continue;
+      }
+      const before = selectedByOptionId.get(optionById.id);
+      if (assignSelectedValueSlugByOptionId(
+        matrix,
+        selectedByOptionId,
+        optionById.id,
+        valueToken
+      ) && selectedByOptionId.get(optionById.id) !== before) {
+        emitCompatibilityOptionIdParam(options, {
+          optionId: optionById.id,
+          optionSlug: optionById.slug,
+          valueSlug: valueToken,
+          searchParam: key
+        });
+        continue;
+      }
+      throw new ProductSelectionCodecError(
+        `Unknown product selection value "${valueToken}" for option "${optionToken}". Use opt.<optionId>=<valueId>.`
+      );
+    }
     const optionBySlug = matrix.optionBySlug.get(optionToken);
     if (optionBySlug) {
-      assignSelectedValueSlugByOptionSlug(
+      if (assignSelectedValueSlugByOptionSlug(
         matrix,
         selectedByOptionId,
         optionBySlug.slug,
-        valueSlug
+        valueToken
+      )) {
+        continue;
+      }
+      if (matrix.valueById.has(valueToken)) {
+        throw new ProductSelectionCodecError(
+          `Unknown product selection value "${valueToken}" for option "${optionToken}". Use opt.<optionId>=<valueId>.`
+        );
+      }
+      throw new ProductSelectionCodecError(
+        `Unknown product selection value "${valueToken}" for option "${optionToken}". Use opt.<optionSlug>=<valueSlug> for compatibility URLs.`
       );
-      continue;
-    }
-    const legacyOption = matrix.optionById.get(optionToken);
-    if (!legacyOption) continue;
-    const before = selectedByOptionId.get(legacyOption.id);
-    assignSelectedValueSlugByOptionId(
-      matrix,
-      selectedByOptionId,
-      legacyOption.id,
-      valueSlug
-    );
-    if (selectedByOptionId.get(legacyOption.id) !== before) {
-      emitLegacyOptionIdParam(options, {
-        optionId: legacyOption.id,
-        optionSlug: legacyOption.slug,
-        valueSlug,
-        searchParam: key
-      });
     }
   }
+  return null;
 }
 function normalizeProductSelection(detail, selection = {}, options) {
   const matrix = buildProductOptionMatrixFromDetail(detail);
+  return normalizeProductSelectionFromMatrix(matrix, selection, options);
+}
+function normalizeProductSelectionFromMatrix(matrix, selection = {}, options) {
   const selectedByOptionId = /* @__PURE__ */ new Map();
   const variantSelection = getVariantSelection(matrix, selection.variantId);
   const variantId = variantSelection?.id ?? null;
@@ -3560,7 +2720,12 @@ function normalizeProductSelection(detail, selection = {}, options) {
     if (!optionId) continue;
     selectedByOptionId.set(optionId, valueId);
   }
-  assignSearchSelection(matrix, selectedByOptionId, selection.search, options);
+  const searchVariantId = assignSearchSelection(
+    matrix,
+    selectedByOptionId,
+    selection.search,
+    options
+  );
   for (const [rawOptionId, rawSelection] of Object.entries(
     selection.byOptionId ?? {}
   )) {
@@ -3637,7 +2802,7 @@ function normalizeProductSelection(detail, selection = {}, options) {
     byOptionSlug,
     byOptionId,
     valueIds: matrix.optionIds.map((optionId) => byOptionId[optionId]).filter((valueId) => Boolean(valueId)),
-    variantId
+    variantId: searchVariantId ?? variantId
   };
 }
 function parseProductSelection(detail, search, options) {
@@ -3645,15 +2810,31 @@ function parseProductSelection(detail, search, options) {
 }
 function stringifyProductSelection(detail, selection = {}, options) {
   const matrix = buildProductOptionMatrixFromDetail(detail);
-  const normalized = normalizeProductSelection(detail, selection, options);
+  const normalized = normalizeProductSelectionFromMatrix(
+    matrix,
+    selection,
+    options
+  );
   const params = new URLSearchParams();
+  if (hasExplicitSelection(selection)) {
+    const matchingVariants = getMatchingVariantEntries(matrix, normalized);
+    const exactVariant = getExactSelectedVariantEntry(
+      matrix,
+      normalized,
+      matchingVariants
+    );
+    if (exactVariant) {
+      params.set("variant", exactVariant.id);
+      return params.toString();
+    }
+  }
   for (const optionId of matrix.optionIds) {
     const valueId = normalized.byOptionId[optionId];
     if (!valueId) continue;
-    const option = matrix.optionById.get(optionId);
-    const value = matrix.valueById.get(valueId);
-    if (!option || !value) continue;
-    params.append(`opt.${requireOptionSlug(option)}`, requireValueSlug(value));
+    if (!matrix.optionById.has(optionId) || !matrix.valueById.has(valueId)) {
+      continue;
+    }
+    params.append(`opt.${optionId}`, valueId);
   }
   return params.toString();
 }
@@ -3718,17 +2899,21 @@ function mediaArray(values) {
   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 ?? firstMedia(detail.listing.primaryImage) ?? matchingVariantPrimary ?? firstMedia(detailImages);
-  const images = mediaArray(selectedVariant?.images).length > 0 ? mediaArray(selectedVariant?.images) : selectedValueImages.length > 0 ? selectedValueImages : detailImages;
+  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
@@ -3754,11 +2939,39 @@ function buildSelectionStock(selectedVariant, matchingVariants) {
     availableStock: null
   };
 }
-function resolveProductSelection(detail, selection = {}, options) {
-  const matrix = buildProductOptionMatrixFromDetail(detail);
-  const effectiveSelection = hasExplicitSelection(selection) || detail.listing.selectionHintVariant == null ? selection : { ...selection, variantId: detail.listing.selectionHintVariant };
-  const normalizedSelection = normalizeProductSelection(
-    detail,
+function buildAvailableValueStock(variants) {
+  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),
+    0
+  );
+  return {
+    availableForSale: activeVariants.some(isVariantAvailableForSale),
+    isUnlimited,
+    availableStock
+  };
+}
+function getCandidateVariantsForValue(matrix, optionId, valueId, selectedValueIds) {
+  const selectedByOption = getSelectedValueByOptionId(matrix, selectedValueIds);
+  selectedByOption.set(optionId, valueId);
+  return matrix.variants.filter(
+    (variant) => Array.from(selectedByOption.entries()).every(
+      ([selectedOptionId, selectedValueId]) => variant.optionValueByOptionId.get(selectedOptionId) === selectedValueId
+    )
+  ).map((variant) => variant.source);
+}
+function getResolutionContext(context) {
+  return {
+    images: context?.images ?? context?.detail?.images ?? [],
+    listing: context?.listing ?? context?.detail?.listing ?? {}
+  };
+}
+function resolveProductSelectionFromMatrix(matrix, selection = {}, options, context) {
+  const { images, listing } = getResolutionContext(context);
+  const effectiveSelection = hasExplicitSelection(selection) || listing.selectionHintVariant == null ? selection : { ...selection, variantId: listing.selectionHintVariant };
+  const normalizedSelection = normalizeProductSelectionFromMatrix(
+    matrix,
     effectiveSelection,
     options
   );
@@ -3793,9 +3006,17 @@ function resolveProductSelection(detail, selection = {}, options) {
         option.values.map((value) => ({
           valueId: value.id,
           value: value.label,
-          slug: requireValueSlug(value),
+          slug: value.slug ?? "",
           selected: normalizedSelection.byOptionId[option.id] === value.id,
           available: 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
@@ -3823,7 +3044,12 @@ function resolveProductSelection(detail, selection = {}, options) {
     allOptionsSelected,
     price: buildSelectionPrice(priceVariants),
     media: buildSelectionMedia(
-      detail,
+      {
+        images,
+        listing: {
+          primaryImage: listing.primaryImage ?? null
+        }
+      },
       selectedVariant,
       matchingVariants,
       selectedValues
@@ -3831,6 +3057,100 @@ function resolveProductSelection(detail, selection = {}, options) {
     stock: buildSelectionStock(selectedVariant, matchingVariants)
   };
 }
+function resolveProductSelection(detail, selection = {}, options) {
+  const matrix = buildProductOptionMatrixFromDetail(detail);
+  return resolveProductSelectionFromMatrix(matrix, selection, options, {
+    detail
+  });
+}
+function isProductDetailImageMedia(value) {
+  return typeof value === "object" && value !== null;
+}
+function mediaDedupeKey(value) {
+  if (value.id != null) return `id:${String(value.id)}`;
+  if (value.url) return `url:${value.url}`;
+  return null;
+}
+function getProductSelectionImages(resolution) {
+  const seen = /* @__PURE__ */ new Set();
+  const images = [];
+  const candidates = [
+    resolution.media.primaryImage,
+    ...resolution.media.images
+  ].filter(isProductDetailImageMedia);
+  for (const candidate of candidates) {
+    const key = mediaDedupeKey(candidate);
+    if (key && seen.has(key)) continue;
+    if (key) seen.add(key);
+    images.push(candidate);
+  }
+  return images;
+}
+function getProductHrefSlug(product) {
+  if ("product" in product && product.product?.slug) {
+    return product.product.slug;
+  }
+  if ("slug" in product && product.slug) return product.slug;
+  throw new ProductSelectionCodecError(
+    "Product slug is required to build a product href."
+  );
+}
+function joinProductPath(basePath, slug, trailingSlash) {
+  const base = basePath.replace(/\/+$/, "");
+  const encodedSlug = encodeURIComponent(slug);
+  return `${base}/${encodedSlug}${trailingSlash ? "/" : ""}`;
+}
+function getProductHrefGroupSelection(group, matrix) {
+  if (!group) return null;
+  if (group.variantId != null) return { variantId: group.variantId };
+  const 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;
+  }
+  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;
+  }
+  return { byOptionId: { [optionId]: optionValueId } };
+}
+function buildProductHref(product, group, options = {}) {
+  const path = joinProductPath(
+    options.basePath ?? "/products",
+    getProductHrefSlug(product),
+    options.trailingSlash ?? false
+  );
+  const params = new URLSearchParams();
+  if (options.detail && options.selection) {
+    const selection = stringifyProductSelection(options.detail, options.selection);
+    return selection ? `${path}?${selection}` : path;
+  }
+  const groupSelection = getProductHrefGroupSelection(group, options.matrix);
+  if (groupSelection) {
+    if (options.detail) {
+      const selection = stringifyProductSelection(options.detail, groupSelection);
+      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));
+      return `${path}?${params.toString()}`;
+    }
+  }
+  if (group?.optionValueSlug) {
+    const optionSlug = group.optionSlug ?? (group.optionId != null ? options.matrix?.optionById.get(String(group.optionId))?.slug : void 0);
+    if (optionSlug) {
+      params.set(`opt.${optionSlug}`, group.optionValueSlug);
+    }
+  }
+  return params.size > 0 ? `${path}?${params.toString()}` : path;
+}
 function compareVariantOrder(a, b) {
   const aOrder = Number(a._order ?? Number.MAX_SAFE_INTEGER);
   const bOrder = Number(b._order ?? Number.MAX_SAFE_INTEGER);
@@ -3884,6 +3204,72 @@ function buildProductListingProjection(product, variants) {
     availableForSale: availableVariants.length > 0
   };
 }
+function buildProductListingCard(item, options = {}) {
+  const product = item.product;
+  const groups = item.groups;
+  const primaryImage = firstMedia(product.thumbnail) ?? firstMedia(product.images ?? null) ?? null;
+  const priceRange = aggregateListingPriceRange(groups);
+  const availableForSale = groups.some(
+    (group) => group.listing.availableForSale
+  );
+  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),
+    title: product.title,
+    primaryImage,
+    priceRange,
+    availableForSale,
+    swatches
+  };
+}
+function aggregateListingPriceRange(groups) {
+  const minPrice = minOfNullable(groups.map((g) => g.listing.minPrice));
+  const maxPrice = maxOfNullable(groups.map((g) => g.listing.maxPrice));
+  const minCompareAtPrice = minOfNullable(
+    groups.map((g) => g.listing.minCompareAtPrice)
+  );
+  const maxCompareAtPrice = maxOfNullable(
+    groups.map((g) => g.listing.maxCompareAtPrice)
+  );
+  const isPriceRange = minPrice !== null && maxPrice !== null && minPrice !== maxPrice;
+  return {
+    minPrice,
+    maxPrice,
+    minCompareAtPrice,
+    maxCompareAtPrice,
+    isPriceRange
+  };
+}
+function buildListingSwatch(product, group, options) {
+  const thumbnail = firstMedia(group.optionValueThumbnail) ?? firstMedia(group.optionValueImages) ?? null;
+  return {
+    optionId: group.optionId,
+    optionValueId: group.optionValueId,
+    label: group.optionValueLabel,
+    swatchColor: group.optionValueSwatchColor ?? null,
+    thumbnail,
+    href: buildProductHref(
+      { slug: product.slug },
+      {
+        optionId: group.optionId,
+        optionValueId: group.optionValueId,
+        optionValueSlug: group.optionValueSlug,
+        listing: group.listing
+      },
+      options
+    ),
+    availableForSale: group.listing.availableForSale
+  };
+}
+function minOfNullable(values) {
+  const numbers = values.filter((v) => v !== null);
+  return numbers.length === 0 ? null : Math.min(...numbers);
+}
+function maxOfNullable(values) {
+  const numbers = values.filter((v) => v !== null);
+  return numbers.length === 0 ? null : Math.max(...numbers);
+}
 function buildProductListingGroupsByOption(args) {
   const primaryOptionId = args.primaryOptionId ?? void 0;
   if (!primaryOptionId) return [];
@@ -4210,4 +3596,9 @@ function createAnalytics(config) {
     }
   };
 }
+
+// src/index.ts
+function createClient2(options) {
+  return createClient(options);
+}
 //# sourceMappingURL=index.cjs.map