@01.software/sdk 0.67.0 → 0.69.0

package/dist/server.js

@@ -1,6 +1,3 @@
-// src/core/collection/http-client.ts
-import { stringify } from "qs-esm";
-
 // src/core/errors.ts
 var SDK_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@01.software/sdk/SDKError");
 var SDK_ERROR_TYPE_BRAND = /* @__PURE__ */ Symbol.for("@01.software/sdk/SDKError.type");
@@ -114,6 +111,7 @@ var COMMERCE_ERROR_CODES = [
   "admission_metadata_invalid",
   "admission_metadata_required",
   "capacity_exceeded",
+  "admission_required",
   "occurrence_lock_unavailable",
   "occurrence_not_open",
   "admission_type_capacity_exceeded",
@@ -132,6 +130,8 @@ var COMMERCE_ERROR_CODES = [
   "variant_inactive",
   "variant_product_mismatch",
   "product_not_public",
+  "product_not_eligible",
+  "purchase_limit_exceeded",
   "market_not_found",
   "market_shipping_currency_unsupported",
   "missing_market_rate",
@@ -1004,1046 +1004,1234 @@ function stockSnapshotSearchParams(params) {
   return `variantIds=${params.variantIds.map(encodeURIComponent).join(",")}`;
 }
 
-// src/core/collection/http-client.ts
-function validateWhere(where) {
-  if (where === void 0) return false;
-  let hasNull = false;
-  function visit(value, depth, key) {
-    if (depth > 10) {
-      throw createValidationError(
-        "Collection where must not exceed nesting depth 10."
-      );
-    }
-    if (value === null && (key === "equals" || key === "not_equals")) {
-      hasNull = true;
-      return;
-    }
-    if (value == null) {
-      throw createValidationError(
-        "Collection where must not contain null or undefined values."
-      );
-    }
-    if (Array.isArray(value)) {
-      if (value.length === 0) {
-        throw createValidationError(
-          "Collection where must not contain empty arrays, including and/or."
-        );
-      }
-      if (value.length > 1e3) {
-        throw createValidationError(
-          "Collection where arrays must not contain more than 1000 elements."
-        );
-      }
-      for (const item of value) visit(item, depth + 1);
-    } else if (typeof value === "object" && !(value instanceof Date)) {
-      const values = Object.entries(value);
-      if (values.length === 0) {
-        throw createValidationError(
-          "Collection where must not contain empty condition objects."
-        );
-      }
-      for (const [key2, item] of values) visit(item, depth + 1, key2);
-    }
+// src/core/api/parse-response.ts
+async function parseApiResponse(response, endpoint, options = {}) {
+  if (response.status === 204 || response.headers.get("content-length") === "0") {
+    return void 0;
   }
-  visit(where, 0);
-  return hasNull;
-}
-var HttpClient = class {
-  constructor(publishableKey, secretKey, getCustomerToken, onUnauthorized, onRequestId, apiUrl) {
-    this.publishableKey = requirePublishableKeyForSecret(
-      "CollectionClient",
-      publishableKey,
-      secretKey
+  let parsed;
+  try {
+    parsed = await response.json();
+  } catch {
+    throw createApiError(
+      `Invalid JSON response from ${endpoint}`,
+      response.status,
+      void 0,
+      "Server returned an invalid response.",
+      "Check if the API endpoint is available."
     );
-    this.secretKey = secretKey;
-    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
-    };
-    const token = this.getCustomerToken?.();
-    if (token) {
-      opts.customerToken = token;
-      if (this.onUnauthorized) {
-        opts.onUnauthorized = this.onUnauthorized;
-      }
-    }
-    return opts;
-  }
-  async fetchWithTracking(url, opts) {
-    try {
-      const response = await httpFetch(url, opts);
-      this.onRequestId?.(response.headers.get("x-request-id") ?? null);
-      return response;
-    } catch (err) {
-      const id = err instanceof SDKError ? err.requestId ?? null : null;
-      this.onRequestId?.(id);
-      throw err;
-    }
-  }
-  buildUrl(endpoint, options) {
-    if (!options) return endpoint;
-    const { fallbackLocale, ...rest } = options;
-    const queryOptions = fallbackLocale === void 0 ? rest : {
-      ...rest,
-      "fallback-locale": fallbackLocale === false ? "none" : fallbackLocale
-    };
-    const encodedOptions = validateWhere(queryOptions.where) ? { ...queryOptions, where: JSON.stringify(queryOptions.where) } : queryOptions;
-    const queryString = stringify(encodedOptions, { addQueryPrefix: true });
-    return queryString ? `${endpoint}${queryString}` : endpoint;
-  }
-  assertJsonResponse(response) {
-    const contentType = response.headers.get("content-type");
-    if (!contentType?.includes("application/json")) {
-      throw createApiError("Response is not in JSON format.", response.status, {
-        contentType
-      });
-    }
-  }
-  /**
-   * Parse Payload CMS find response (list query)
-   * Returns native Payload response structure
-   */
-  async parseFindResponse(response) {
-    const contentType = response.headers.get("content-type");
-    try {
-      this.assertJsonResponse(response);
-      const jsonData = await response.json();
-      if (jsonData.docs === void 0) {
-        throw createApiError("Invalid find response.", response.status, {
-          jsonData
-        });
-      }
-      return {
-        docs: jsonData.docs,
-        totalDocs: jsonData.totalDocs ?? 0,
-        limit: jsonData.limit || 20,
-        totalPages: jsonData.totalPages ?? 0,
-        page: jsonData.page || 1,
-        pagingCounter: jsonData.pagingCounter || 1,
-        hasPrevPage: jsonData.hasPrevPage ?? false,
-        hasNextPage: jsonData.hasNextPage ?? false,
-        prevPage: jsonData.prevPage ?? null,
-        nextPage: jsonData.nextPage ?? null
-      };
-    } catch (error) {
-      if (error instanceof SDKError) throw error;
-      throw createApiError("Failed to parse response.", response.status, {
-        contentType,
-        error: error instanceof Error ? error.message : error
-      });
-    }
   }
-  /**
-   * Parse Payload CMS mutation response (create/update)
-   * Returns native Payload response structure
-   */
-  async parseMutationResponse(response) {
-    const contentType = response.headers.get("content-type");
-    try {
-      this.assertJsonResponse(response);
-      const jsonData = await response.json();
-      if (jsonData.doc === void 0) {
-        throw createApiError("Invalid mutation response.", response.status, {
-          jsonData
-        });
-      }
-      return {
-        message: jsonData.message || "",
-        doc: jsonData.doc,
-        errors: jsonData.errors
-      };
-    } catch (error) {
-      if (error instanceof SDKError) throw error;
-      throw createApiError("Failed to parse response.", response.status, {
-        contentType,
-        error: error instanceof Error ? error.message : error
-      });
-    }
+  if (parsed === null || typeof parsed !== "object") {
+    return parsed;
   }
-  /**
-   * Parse Payload CMS document response (findById/delete)
-   * Returns document directly without wrapper
-   */
-  async parseDocumentResponse(response) {
-    const contentType = response.headers.get("content-type");
-    try {
-      this.assertJsonResponse(response);
-      const jsonData = await response.json();
-      return jsonData;
-    } catch (error) {
-      if (error instanceof SDKError) throw error;
-      throw createApiError("Failed to parse response.", response.status, {
-        contentType,
-        error: error instanceof Error ? error.message : error
-      });
+  const data = parsed;
+  const hasCommerceEnvelopeSignal = options.errorFamily === "commerce" && ["error", "reason", "requestId", "retryable", "details"].some(
+    (key) => Object.prototype.hasOwnProperty.call(data, key)
+  );
+  if (data.error || hasCommerceEnvelopeSignal) {
+    const errorMessage = typeof data.error === "string" ? data.error : "Unknown API error";
+    const reason = typeof data.reason === "string" ? data.reason : void 0;
+    const requestId = response.headers.get("x-request-id") ?? void 0;
+    const retryAfter = parseRetryAfter(response).seconds;
+    let error;
+    if (reason === "validation_failed") {
+      error = createValidationError(errorMessage, data, errorMessage);
+    } else if (reason === "token_expired" || reason === "token_invalid" || reason === "preview_token_invalid" || reason === "preview_token_required" || reason === "key_invalid" || reason === "key_revoked") {
+      error = createAuthError(errorMessage, data, errorMessage);
+    } else if (reason === "forbidden") {
+      error = createPermissionError(errorMessage, data, errorMessage);
+    } else if (reason === "rate_limit_exceeded") {
+      error = createRateLimitError(errorMessage, retryAfter, data, errorMessage);
+    } else if (reason === "not_found") {
+      error = createNotFoundError(errorMessage, data, errorMessage);
+    } else if (reason === "conflict") {
+      error = createConflictError(errorMessage, data, errorMessage);
+    } else {
+      error = createApiError(
+        errorMessage,
+        response.status,
+        data,
+        errorMessage,
+        "An error occurred while processing the request."
+      );
     }
+    const withRequestId = attachRequestId(error, requestId);
+    if (retryAfter !== void 0) Object.assign(withRequestId, { retryAfter });
+    throw options.errorFamily === "commerce" ? enhanceCommerceError(withRequestId, data, requestId) : enhanceNonCommerceError(withRequestId, reason);
   }
-};
-
-// src/utils/types.ts
-function resolveRelation(ref) {
-  if (typeof ref === "string" || typeof ref === "number" || ref === null || ref === void 0)
-    return null;
-  return ref;
+  return data;
 }
 
-// src/core/metadata/index.ts
-var OPEN_GRAPH_IMAGE_SIZE = "1200";
-var LEGACY_OPEN_GRAPH_IMAGE_SIZE = "1536";
-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] }
+// ../../internal/http-contracts/src/index.ts
+var operationBrand = /* @__PURE__ */ Symbol("sdk-http-operation");
+var PORTONE_STANDARD_ACTION_CAPABILITIES_MEDIA_TYPE = "application/vnd.01software.portone-action-capabilities.v1+json";
+var operation = (collection, method, path, errorFamily) => Object.freeze({
+  [operationBrand]: true,
+  collection,
+  method,
+  path,
+  ...errorFamily && { errorFamily }
+});
+var strictCommerceOperation = (collection, method, path) => operation(collection, method, path, "commerce");
+var selectiveCommerceOperation = (collection, method, path, typedCommerceErrorReasons) => Object.freeze({
+  ...operation(collection, method, path),
+  typedCommerceErrorReasons: Object.freeze([...typedCommerceErrorReasons])
+});
+var COMMERCE_ENDPOINT_OPERATIONS = {
+  products: {
+    detail: operation("products", "get", "/detail"),
+    detailCatalog: operation("products", "get", "/detail/catalog"),
+    listingGroups: operation("products", "get", "/listing-groups"),
+    listingGroupsCatalog: operation(
+      "products",
+      "get",
+      "/listing-groups/catalog"
+    ),
+    listingGroupsQuery: operation("products", "post", "/listing-groups/query"),
+    listingGroupsQueryGet: operation(
+      "products",
+      "get",
+      "/listing-groups/query"
+    ),
+    listingGroupsQueryCatalog: operation(
+      "products",
+      "get",
+      "/listing-groups/query/catalog"
+    ),
+    stockCheck: operation("products", "post", "/stock-check"),
+    stockSnapshot: operation("products", "get", "/stock"),
+    upsert: operation("products", "post", "/upsert"),
+    graphRevision: operation("products", "get", "/:id/graph-revision"),
+    variantsPatch: operation("products", "patch", "/:id/variants")
+  },
+  orders: {
+    create: operation("orders", "post", "/create"),
+    update: operation("orders", "post", "/update"),
+    confirmPayment: operation("orders", "post", "/confirm-payment"),
+    byPayment: operation("orders", "get", "/by-payment"),
+    cancel: operation("orders", "post", "/cancel"),
+    resolveCancelRefund: selectiveCommerceOperation(
+      "orders",
+      "post",
+      "/resolve-cancel-refund",
+      ["managed_refund_attestation_forbidden"]
+    ),
+    checkout: strictCommerceOperation("orders", "post", "/checkout"),
+    createFulfillment: operation("orders", "post", "/create-fulfillment"),
+    updateFulfillment: operation("orders", "post", "/update-fulfillment")
+  },
+  checkouts: {
+    detail: strictCommerceOperation("checkouts", "post", "/detail"),
+    query: strictCommerceOperation("checkouts", "post", "/query")
+  },
+  draftOrders: {
+    calculate: operation("draft-orders", "post", "/:id/calculate"),
+    complete: operation("draft-orders", "post", "/:id/complete"),
+    finalize: operation("draft-orders", "post", "/:id/finalize")
+  },
+  transactions: {
+    update: operation("transactions", "post", "/update")
+  },
+  returns: {
+    create: operation("returns", "post", "/create"),
+    update: operation("returns", "post", "/update"),
+    returnRefund: operation("returns", "post", "/return-refund")
+  },
+  fulfillmentOrders: {
+    prepare: operation(
+      "fulfillment-orders",
+      "post",
+      "/prepare-fulfillment-order"
+    )
+  },
+  fulfillments: {
+    bulkImport: operation("fulfillments", "post", "/bulk-import")
+  },
+  carts: {
+    create: strictCommerceOperation("carts", "post", "/create"),
+    retrieve: strictCommerceOperation("carts", "post", "/retrieve"),
+    mine: strictCommerceOperation("carts", "post", "/mine"),
+    merge: strictCommerceOperation("carts", "post", "/merge"),
+    addItem: strictCommerceOperation("carts", "post", "/add-item"),
+    updateItem: strictCommerceOperation("carts", "post", "/update-item"),
+    removeItem: strictCommerceOperation("carts", "post", "/remove-item"),
+    updateDiscountCodes: strictCommerceOperation(
+      "carts",
+      "post",
+      "/update-discount-codes"
+    ),
+    updateAttributes: strictCommerceOperation(
+      "carts",
+      "post",
+      "/update-attributes"
+    ),
+    clear: strictCommerceOperation("carts", "post", "/clear")
+  },
+  paymentSessions: {
+    create: strictCommerceOperation("payment-sessions", "post", "/create"),
+    retrieve: strictCommerceOperation("payment-sessions", "post", "/retrieve"),
+    cancel: strictCommerceOperation("payment-sessions", "post", "/cancel"),
+    server: {
+      create: strictCommerceOperation(
+        "payment-sessions",
+        "post",
+        "/server/create"
+      ),
+      retrieve: strictCommerceOperation(
+        "payment-sessions",
+        "post",
+        "/server/retrieve"
+      ),
+      cancel: strictCommerceOperation(
+        "payment-sessions",
+        "post",
+        "/server/cancel"
+      ),
+      confirm: strictCommerceOperation(
+        "payment-sessions",
+        "post",
+        "/server/confirm"
+      ),
+      findPortOne: strictCommerceOperation(
+        "payment-sessions",
+        "post",
+        "/server/portone/find"
+      ),
+      reconcilePortOne: strictCommerceOperation(
+        "payment-sessions",
+        "post",
+        "/server/portone/reconcile"
+      )
+    },
+    custom: {
+      create: operation("orders", "post", "/custom-payment-sessions"),
+      retrieve: operation(
+        "orders",
+        "post",
+        "/custom-payment-sessions/retrieve"
+      ),
+      confirm: operation("orders", "post", "/custom-payment-sessions/confirm")
+    }
+  },
+  shippingPolicies: {
+    calculate: operation("shipping-policies", "post", "/calculate")
+  },
+  discounts: {
+    validate: operation("discounts", "post", "/validate")
+  }
+};
+var portOneStandardActionCapabilityOperations = /* @__PURE__ */ new Set([
+  COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.create,
+  COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.retrieve,
+  COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.create,
+  COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.retrieve
+]);
+var MEMBERSHIP_ENDPOINT_OPERATIONS = {
+  subscribe: operation(null, "post", "/memberships/subscribe"),
+  billingCustody: operation(null, "post", "/memberships/billing-custody"),
+  cancel: operation(null, "post", "/memberships/:id/cancel"),
+  me: operation(null, "get", "/memberships/me"),
+  chargeResult: operation(null, "post", "/memberships/:id/charge-result"),
+  refundResult: operation(null, "post", "/memberships/:id/refund-result"),
+  revoke: operation(null, "post", "/memberships/:id/revoke")
+};
+var EXTERNAL_EFFECT_CLAIM_ENDPOINT_OPERATIONS = {
+  claim: operation(null, "post", "/external-effect-claims/claim"),
+  get: operation(null, "post", "/external-effect-claims/get"),
+  arm: operation(null, "post", "/external-effect-claims/arm"),
+  release: operation(null, "post", "/external-effect-claims/release"),
+  report: operation(null, "post", "/external-effect-claims/report"),
+  recovery: operation(null, "post", "/external-effect-claims/recovery")
+};
+var INSTALLATION_CREDENTIAL_ENDPOINT_OPERATIONS = {
+  create: operation(null, "post", "/installation-credentials/create"),
+  get: operation(null, "post", "/installation-credentials/get"),
+  replace: operation(null, "post", "/installation-credentials/replace"),
+  dispose: operation(null, "post", "/installation-credentials/dispose")
+};
+var EXTERNAL_CUSTOMER_LINK_ENDPOINT_OPERATIONS = {
+  connect: operation("customers", "post", "/external-links/connect"),
+  get: operation("customers", "post", "/external-links/get"),
+  list: operation("customers", "post", "/external-links/list"),
+  unlink: operation("customers", "post", "/external-links/unlink"),
+  capturePreviousState: operation(
+    "customers",
+    "post",
+    "/external-links/capture-previous-state"
+  ),
+  clearPreviousState: operation(
+    "customers",
+    "post",
+    "/external-links/clear-previous-state"
+  )
+};
+var BENEFIT_VOUCHER_ENDPOINT_OPERATIONS = {
+  issue: operation("customers", "post", "/benefit-vouchers/issue"),
+  get: operation("customers", "post", "/benefit-vouchers/get"),
+  list: operation("customers", "post", "/benefit-vouchers/list"),
+  redeem: operation("customers", "post", "/benefit-vouchers/redeem"),
+  void: operation("customers", "post", "/benefit-vouchers/void"),
+  listMine: operation("customers", "get", "/me/benefit-vouchers")
+};
+var CUSTOMER_GROUP_ENDPOINT_OPERATIONS = {
+  members: operation("customer-groups", "get", "/:id/members"),
+  grant: operation("customer-groups", "post", "/:id/members/grant"),
+  revoke: operation("customer-groups", "post", "/:id/members/revoke")
+};
+var CUSTOMER_AUTH_ENDPOINT_OPERATIONS = {
+  register: operation("customers", "post", "/register"),
+  login: operation("customers", "post", "/login"),
+  refresh: operation("customers", "post", "/refresh"),
+  me: operation("customers", "get", "/me"),
+  updateProfile: operation("customers", "patch", "/me"),
+  forgotPassword: operation("customers", "post", "/forgot-password"),
+  resetPassword: operation("customers", "post", "/reset-password"),
+  changePassword: operation("customers", "post", "/change-password"),
+  revokeRefresh: operation("customers", "post", "/revoke-refresh"),
+  withdraw: operation("customers", "post", "/withdraw")
+};
+var EMBEDDED_ADMIN_ENDPOINT_OPERATIONS = {
+  show: operation("tenants", "get", "/embedded-admin-app"),
+  configure: operation("tenants", "patch", "/embedded-admin-app"),
+  disable: operation("tenants", "delete", "/embedded-admin-app")
+};
+var EVENTS_ENDPOINT_OPERATIONS = {
+  registrations: {
+    listMine: operation("event-registrations", "get", "/my")
+  },
+  events: {
+    convertSchedule: operation("events", "post", "/:id/schedule")
+  },
+  occurrences: {
+    range: operation("event-occurrences", "get", "/range"),
+    admissionAvailability: operation(
+      "event-occurrences",
+      "get",
+      "/admission-availability"
+    )
+  }
+};
+var COMMUNITY_ENDPOINT_OPERATIONS = {
+  posts: {
+    detail: operation("posts", "get", "/detail")
+  }
+};
+var GALLERY_ENDPOINT_OPERATIONS = {
+  items: {
+    storefront: operation("gallery-items", "get", "/storefront")
+  }
+};
+var VIDEO_ENDPOINT_OPERATIONS = {
+  playback: operation("videos", "post", "/:id/playback")
+};
+function resolveOperationTemplate(descriptor) {
+  return descriptor.collection ? `/api/${descriptor.collection}${descriptor.path}` : `/api${descriptor.path}`;
+}
+function resolveOperationPath(descriptor, options) {
+  const path = resolveOperationTemplate(descriptor).replace(
+    /:([A-Za-z][A-Za-z0-9_]*)/g,
+    (_, key) => {
+      const value = options?.pathParams?.[key];
+      if (value === void 0) {
+        throw new TypeError(`Missing path parameter: ${key}`);
+      }
+      return encodeURIComponent(value);
+    }
+  );
+  const unresolved = path.match(/:([A-Za-z][A-Za-z0-9_]*)/);
+  if (unresolved) {
+    throw new TypeError(`Missing path parameter: ${unresolved[1]}`);
+  }
+  const query = options?.query?.toString().replace(/^\?/, "");
+  return query ? `${path}?${query}` : path;
+}
+function resolveOperationMethod(descriptor) {
+  return descriptor.method.toUpperCase();
+}
+
+// src/core/api/endpoints.ts
+var sharedEndpoint = (descriptor) => descriptor;
+function resolveOperationErrorFamily(descriptor) {
+  return descriptor.errorFamily;
+}
+function resolveOperationTypedCommerceErrorReasons(descriptor) {
+  return descriptor.typedCommerceErrorReasons;
+}
+var COMMERCE_ENDPOINTS = {
+  products: {
+    detail: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.products.detail),
+    detailCatalog: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.products.detailCatalog
+    ),
+    listingGroups: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.products.listingGroups
+    ),
+    listingGroupsCatalog: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.products.listingGroupsCatalog
+    ),
+    // The manifest keeps the GET read and the POST body-query apart; this
+    // semantic name has always resolved to the GET one.
+    listingGroupsQuery: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.products.listingGroupsQueryGet
+    ),
+    listingGroupsQueryCatalog: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.products.listingGroupsQueryCatalog
+    ),
+    stockCheck: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.products.stockCheck
+    ),
+    stockSnapshot: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.products.stockSnapshot
+    ),
+    upsert: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.products.upsert)
+  },
+  orders: {
+    update: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.orders.update),
+    byPayment: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.orders.byPayment),
+    cancel: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.orders.cancel),
+    resolveCancelRefund: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.orders.resolveCancelRefund
+    ),
+    createFulfillment: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.orders.createFulfillment
+    ),
+    updateFulfillment: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.orders.updateFulfillment
+    )
+  },
+  checkouts: {
+    create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.orders.checkout),
+    retrieve: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.checkouts.detail),
+    server: {
+      create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.orders.checkout),
+      retrieve: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.checkouts.detail),
+      query: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.checkouts.query)
+    }
+  },
+  returns: {
+    create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.returns.create),
+    update: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.returns.update),
+    returnRefund: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.returns.returnRefund
+    )
+  },
+  fulfillmentOrders: {
+    prepare: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.fulfillmentOrders.prepare
+    )
+  },
+  fulfillments: {
+    bulkImport: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.fulfillments.bulkImport
+    )
+  },
+  carts: {
+    create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.create),
+    retrieve: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.retrieve),
+    mine: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.mine),
+    merge: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.merge),
+    server: {
+      // Server credentials are an authorization lane, not a second Cart
+      // transport. These must stay bound to the registered shared operations.
+      create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.create),
+      retrieve: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.retrieve),
+      mine: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.mine),
+      merge: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.merge),
+      addItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.addItem),
+      updateItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.updateItem),
+      removeItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.removeItem),
+      updateDiscountCodes: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.carts.updateDiscountCodes
+      ),
+      updateAttributes: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.carts.updateAttributes
+      ),
+      clear: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.clear)
     },
-    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?.[OPEN_GRAPH_IMAGE_SIZE] ?? image.sizes?.[LEGACY_OPEN_GRAPH_IMAGE_SIZE];
-  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 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
-      );
+    addItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.addItem),
+    updateItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.updateItem),
+    removeItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.removeItem),
+    updateDiscountCodes: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.carts.updateDiscountCodes
+    ),
+    updateAttributes: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.carts.updateAttributes
+    ),
+    clear: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.clear)
+  },
+  paymentSessions: {
+    create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.create),
+    retrieve: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.retrieve
+    ),
+    cancel: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.cancel),
+    custom: {
+      create: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.custom.create
+      ),
+      retrieve: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.custom.retrieve
+      ),
+      confirm: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.custom.confirm
+      )
+    },
+    server: {
+      create: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.create
+      ),
+      retrieve: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.retrieve
+      ),
+      cancel: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.cancel
+      ),
+      confirm: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.confirm
+      ),
+      findPortOne: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.findPortOne
+      ),
+      reconcilePortOne: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.reconcilePortOne
+      )
     }
-    return this.api.requestCreate(endpoint, data);
+  },
+  shippingPolicies: {
+    calculate: sharedEndpoint(
+      COMMERCE_ENDPOINT_OPERATIONS.shippingPolicies.calculate
+    )
   }
-  /**
-   * 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
-      );
+};
+
+// src/core/api/base-api.ts
+var ServerApiTransport = class {
+  constructor(apiName, options) {
+    if (!options.secretKey) {
+      throw createConfigError(`secretKey is required for ${apiName}.`);
     }
-    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
+    this.publishableKey = requirePublishableKeyForSecret(
+      apiName,
+      options.publishableKey,
+      options.secretKey
     );
+    this.secretKey = options.secretKey;
+    this.apiUrl = options.apiUrl;
+    this.onRequestId = options.onRequestId;
   }
-  /**
-   * 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
-    );
+  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 },
+        ...options?.errorFamily && { errorFamily: options.errorFamily },
+        ...options?.typedCommerceErrorReasons && {
+          typedCommerceErrorReasons: options.typedCommerceErrorReasons
+        }
+      });
+      this.onRequestId?.(response.headers.get("x-request-id") ?? null);
+      return parseApiResponse(response, endpoint, {
+        errorFamily: options?.errorFamily
+      });
+    } catch (err) {
+      const id = err instanceof SDKError ? err.requestId ?? null : null;
+      this.onRequestId?.(id);
+      throw err;
+    }
   }
-  /**
-   * 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 }
-    );
+};
+var BaseApi = class {
+  constructor(apiName, options) {
+    this.transport = new ServerApiTransport(apiName, options);
   }
-  /**
-   * Delete a document by ID
-   * DELETE /api/{collection}/{id}
-   * @returns Deleted document object directly (no wrapper)
-   */
-  async remove(id, options) {
-    return this.api.requestDelete(
-      `/api/${String(this.collection)}/${String(id)}`,
-      options
+  requestEndpoint(endpoint, body, options) {
+    return this.transport.request(
+      resolveOperationPath(endpoint, options),
+      body,
+      {
+        method: resolveOperationMethod(endpoint),
+        headers: options?.headers,
+        errorFamily: resolveOperationErrorFamily(endpoint),
+        typedCommerceErrorReasons: resolveOperationTypedCommerceErrorReasons(endpoint)
+      }
     );
   }
-  /**
-   * 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 RawBaseApi = class {
+  constructor(apiName, options) {
+    this.transport = new ServerApiTransport(apiName, options);
+    this.publishableKey = requirePublishableKeyForSecret(
+      apiName,
+      options.publishableKey,
+      options.secretKey
     );
+    this.secretKey = options.secretKey;
+    this.apiUrl = options.apiUrl;
+    this.onRequestId = options.onRequestId;
+  }
+  request(endpoint, body, options) {
+    return this.transport.request(endpoint, body, options);
   }
-};
-var ServerCollectionQueryBuilder = class extends CollectionQueryBuilder {
 };
 
-// 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/core/api/benefit-voucher-types.ts
+var BENEFIT_VOUCHER_VOID_REASONS = [
+  "issued_in_error",
+  "benefit_revoked",
+  "customer_request",
+  "other"
+];
+function invalidBenefitVoucherResponse() {
+  throw createApiError("Invalid benefit voucher response", 200);
 }
-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-like response from a cacheable GET custom endpoint.
-   */
-  async requestFindEndpointGet(endpoint) {
-    const response = await this.fetchWithTracking(endpoint, {
-      ...this.defaultOptions,
-      method: "GET"
-    });
-    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);
+function object(value, keys) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).length !== keys.length || keys.some((key) => !(key in value)))
+    invalidBenefitVoucherResponse();
+  return value;
+}
+var uuid = (v) => typeof v === "string" && (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+  v
+) || v === "00000000-0000-0000-0000-000000000000" || v.toLowerCase() === "ffffffff-ffff-ffff-ffff-ffffffffffff");
+var time = (v) => typeof v === "string" && /^\d{4}-\d{2}-\d{2}T/.test(v) && Number.isFinite(Date.parse(v)) && new Date(Date.parse(v)).toISOString() === v;
+var actor = (v) => typeof v === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(v);
+function parseBenefitVoucher(value, mine = false) {
+  const v = object(value, [
+    "id",
+    "name",
+    "description",
+    "state",
+    "issuedAt",
+    "expiresAt",
+    ...mine ? ["closedAt"] : ["customerId", "definitionId", "source", "closed"]
+  ]);
+  if (!uuid(v.id) || typeof v.name !== "string" || !v.name.length || v.name.length > 120 || v.description !== null && (typeof v.description !== "string" || v.description.length > 1e3) || !["issued", "redeemed", "expired", "voided"].includes(v.state) || !time(v.issuedAt) || !time(v.expiresAt))
+    invalidBenefitVoucherResponse();
+  if (mine) {
+    if (v.closedAt !== null && !time(v.closedAt))
+      invalidBenefitVoucherResponse();
+  } else {
+    if (!uuid(v.customerId) || !uuid(v.definitionId))
+      invalidBenefitVoucherResponse();
+    const source = object(v.source, ["namespace", "ref"]);
+    if (typeof source.namespace !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(source.namespace) || typeof source.ref !== "string" || !source.ref.length || source.ref.length > 256)
+      invalidBenefitVoucherResponse();
+    if (v.closed !== null) {
+      const closed = object(v.closed, [
+        "at",
+        "channel",
+        "actor",
+        "actorRef",
+        "voidReason"
+      ]);
+      const principal = object(closed.actor, ["type", "id"]);
+      if (!time(closed.at) || !uuid(principal.id) || !["server", "console"].includes(closed.channel) || !["server_credential", "operator"].includes(principal.type) || closed.actorRef !== null && !actor(closed.actorRef) || closed.voidReason !== null && !BENEFIT_VOUCHER_VOID_REASONS.includes(closed.voidReason))
+        invalidBenefitVoucherResponse();
+    }
   }
-  /**
-   * 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);
+  return value;
+}
+function parseBenefitVoucherList(value, mine = false) {
+  const v = object(value, ["vouchers", "nextCursor", "evaluatedAt"]);
+  if (!Array.isArray(v.vouchers) || v.vouchers.length > 100 || !time(v.evaluatedAt) || v.nextCursor !== null && (typeof v.nextCursor !== "string" || !v.nextCursor.length || v.nextCursor.length > 2048))
+    invalidBenefitVoucherResponse();
+  for (const row of v.vouchers) {
+    if (mine) parseBenefitVoucher(row, true);
+    else parseBenefitVoucher(row);
   }
-  /**
-   * Update multiple documents (bulk update)
-   * PATCH /api/{collection}
-   */
-  async requestUpdateMany(endpoint, data) {
-    const url = this.buildUrl(endpoint, { where: data.where });
-    const response = await this.fetchWithTracking(url, {
-      ...this.defaultOptions,
-      method: "PATCH",
-      body: JSON.stringify(data.data)
-    });
-    return this.parseFindResponse(response);
+  return value;
+}
+
+// src/core/api/benefit-vouchers-api.ts
+var BenefitVouchersApi = class extends BaseApi {
+  constructor(options) {
+    super("BenefitVouchersApi", options);
+  }
+  async command(name, input) {
+    const result = await this.requestEndpoint(BENEFIT_VOUCHER_ENDPOINT_OPERATIONS[name], input);
+    if (!result || typeof result !== "object" || !("voucher" in result))
+      invalidBenefitVoucherResponse();
+    const voucher = parseBenefitVoucher(result.voucher);
+    const key = name === "issue" ? "created" : name === "get" ? null : "replayed";
+    if (Object.keys(result).length !== (key ? 2 : 1) || key && typeof result[key] !== "boolean")
+      invalidBenefitVoucherResponse();
+    return {
+      voucher,
+      ...key ? { [key]: result[key] } : {}
+    };
   }
-  /**
-   * Delete document
-   * DELETE /api/{collection}/{id}
-   */
-  async requestDelete(endpoint, options) {
-    const url = this.buildUrl(endpoint, options);
-    const response = await this.fetchWithTracking(url, {
-      ...this.defaultOptions,
-      method: "DELETE"
-    });
-    return this.parseDocumentResponse(response);
+  async issue(input) {
+    return await this.command("issue", input);
   }
-  /**
-   * Delete multiple documents (bulk delete)
-   * DELETE /api/{collection}
-   */
-  async requestDeleteMany(endpoint, data) {
-    const url = this.buildUrl(endpoint, { where: data.where });
-    const response = await this.fetchWithTracking(url, {
-      ...this.defaultOptions,
-      method: "DELETE"
-    });
-    return this.parseFindResponse(response);
+  async get(input) {
+    return this.command("get", input);
   }
-  /**
-   * 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 list(input) {
+    return parseBenefitVoucherList(
+      await this.requestEndpoint(BENEFIT_VOUCHER_ENDPOINT_OPERATIONS.list, input)
+    );
   }
-  /**
-   * 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 redeem(input) {
+    return await this.command("redeem", input);
   }
-};
-var ServerCollectionClient = class extends CollectionClient {
-  from(collection) {
-    return new ServerCollectionQueryBuilder(this, collection);
+  async voidVoucher(input) {
+    return await this.command("void", input);
   }
 };
 
-// src/core/api/parse-response.ts
-async function parseApiResponse(response, endpoint, options = {}) {
-  if (response.status === 204 || response.headers.get("content-length") === "0") {
-    return void 0;
+// src/core/collection/http-client.ts
+import { stringify } from "qs-esm";
+function validateWhere(where) {
+  if (where === void 0) return false;
+  let hasNull = false;
+  function visit(value, depth, key) {
+    if (depth > 10) {
+      throw createValidationError(
+        "Collection where must not exceed nesting depth 10."
+      );
+    }
+    if (value === null && (key === "equals" || key === "not_equals")) {
+      hasNull = true;
+      return;
+    }
+    if (value == null) {
+      throw createValidationError(
+        "Collection where must not contain null or undefined values."
+      );
+    }
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        throw createValidationError(
+          "Collection where must not contain empty arrays, including and/or."
+        );
+      }
+      if (value.length > 1e3) {
+        throw createValidationError(
+          "Collection where arrays must not contain more than 1000 elements."
+        );
+      }
+      for (const item of value) visit(item, depth + 1);
+    } else if (typeof value === "object" && !(value instanceof Date)) {
+      const values = Object.entries(value);
+      if (values.length === 0) {
+        throw createValidationError(
+          "Collection where must not contain empty condition objects."
+        );
+      }
+      for (const [key2, item] of values) visit(item, depth + 1, key2);
+    }
   }
-  let parsed;
-  try {
-    parsed = await response.json();
-  } catch {
-    throw createApiError(
-      `Invalid JSON response from ${endpoint}`,
-      response.status,
-      void 0,
-      "Server returned an invalid response.",
-      "Check if the API endpoint is available."
+  visit(where, 0);
+  return hasNull;
+}
+var HttpClient = class {
+  constructor(publishableKey, secretKey, getCustomerToken, onUnauthorized, onRequestId, apiUrl) {
+    this.publishableKey = requirePublishableKeyForSecret(
+      "CollectionClient",
+      publishableKey,
+      secretKey
     );
+    this.secretKey = secretKey;
+    this.getCustomerToken = getCustomerToken;
+    this.onUnauthorized = onUnauthorized;
+    this.onRequestId = onRequestId;
+    this.apiUrl = apiUrl;
   }
-  if (parsed === null || typeof parsed !== "object") {
-    return parsed;
+  get defaultOptions() {
+    const opts = {
+      apiUrl: this.apiUrl,
+      publishableKey: this.publishableKey,
+      secretKey: this.secretKey
+    };
+    const token = this.getCustomerToken?.();
+    if (token) {
+      opts.customerToken = token;
+      if (this.onUnauthorized) {
+        opts.onUnauthorized = this.onUnauthorized;
+      }
+    }
+    return opts;
   }
-  const data = parsed;
-  const hasCommerceEnvelopeSignal = options.errorFamily === "commerce" && ["error", "reason", "requestId", "retryable", "details"].some(
-    (key) => Object.prototype.hasOwnProperty.call(data, key)
-  );
-  if (data.error || hasCommerceEnvelopeSignal) {
-    const errorMessage = typeof data.error === "string" ? data.error : "Unknown API error";
-    const reason = typeof data.reason === "string" ? data.reason : void 0;
-    const requestId = response.headers.get("x-request-id") ?? void 0;
-    const retryAfter = parseRetryAfter(response).seconds;
-    let error;
-    if (reason === "validation_failed") {
-      error = createValidationError(errorMessage, data, errorMessage);
-    } else if (reason === "token_expired" || reason === "token_invalid" || reason === "preview_token_invalid" || reason === "preview_token_required" || reason === "key_invalid" || reason === "key_revoked") {
-      error = createAuthError(errorMessage, data, errorMessage);
-    } else if (reason === "forbidden") {
-      error = createPermissionError(errorMessage, data, errorMessage);
-    } else if (reason === "rate_limit_exceeded") {
-      error = createRateLimitError(errorMessage, retryAfter, data, errorMessage);
-    } else if (reason === "not_found") {
-      error = createNotFoundError(errorMessage, data, errorMessage);
-    } else if (reason === "conflict") {
-      error = createConflictError(errorMessage, data, errorMessage);
-    } else {
-      error = createApiError(
-        errorMessage,
-        response.status,
-        data,
-        errorMessage,
-        "An error occurred while processing the request."
-      );
+  async fetchWithTracking(url, opts) {
+    try {
+      const response = await httpFetch(url, opts);
+      this.onRequestId?.(response.headers.get("x-request-id") ?? null);
+      return response;
+    } catch (err) {
+      const id = err instanceof SDKError ? err.requestId ?? null : null;
+      this.onRequestId?.(id);
+      throw err;
     }
-    const withRequestId = attachRequestId(error, requestId);
-    if (retryAfter !== void 0) Object.assign(withRequestId, { retryAfter });
-    throw options.errorFamily === "commerce" ? enhanceCommerceError(withRequestId, data, requestId) : enhanceNonCommerceError(withRequestId, reason);
   }
-  return data;
-}
-
-// ../../internal/http-contracts/src/index.ts
-var operationBrand = /* @__PURE__ */ Symbol("sdk-http-operation");
-var PORTONE_STANDARD_ACTION_CAPABILITIES_MEDIA_TYPE = "application/vnd.01software.portone-action-capabilities.v1+json";
-var operation = (collection, method, path, errorFamily) => Object.freeze({
-  [operationBrand]: true,
-  collection,
-  method,
-  path,
-  ...errorFamily && { errorFamily }
-});
-var strictCommerceOperation = (collection, method, path) => operation(collection, method, path, "commerce");
-var selectiveCommerceOperation = (collection, method, path, typedCommerceErrorReasons) => Object.freeze({
-  ...operation(collection, method, path),
-  typedCommerceErrorReasons: Object.freeze([...typedCommerceErrorReasons])
-});
-var COMMERCE_ENDPOINT_OPERATIONS = {
-  products: {
-    detail: operation("products", "get", "/detail"),
-    detailCatalog: operation("products", "get", "/detail/catalog"),
-    listingGroups: operation("products", "get", "/listing-groups"),
-    listingGroupsCatalog: operation(
-      "products",
-      "get",
-      "/listing-groups/catalog"
-    ),
-    listingGroupsQuery: operation("products", "post", "/listing-groups/query"),
-    listingGroupsQueryGet: operation(
-      "products",
-      "get",
-      "/listing-groups/query"
-    ),
-    listingGroupsQueryCatalog: operation(
-      "products",
-      "get",
-      "/listing-groups/query/catalog"
-    ),
-    stockCheck: operation("products", "post", "/stock-check"),
-    stockSnapshot: operation("products", "get", "/stock"),
-    upsert: operation("products", "post", "/upsert"),
-    graphRevision: operation("products", "get", "/:id/graph-revision"),
-    variantsPatch: operation("products", "patch", "/:id/variants")
-  },
-  orders: {
-    create: operation("orders", "post", "/create"),
-    update: operation("orders", "post", "/update"),
-    confirmPayment: operation("orders", "post", "/confirm-payment"),
-    byPayment: operation("orders", "get", "/by-payment"),
-    cancel: operation("orders", "post", "/cancel"),
-    resolveCancelRefund: selectiveCommerceOperation(
-      "orders",
-      "post",
-      "/resolve-cancel-refund",
-      ["managed_refund_attestation_forbidden"]
-    ),
-    checkout: strictCommerceOperation("orders", "post", "/checkout"),
-    createFulfillment: operation("orders", "post", "/create-fulfillment"),
-    updateFulfillment: operation("orders", "post", "/update-fulfillment")
-  },
-  checkouts: {
-    detail: strictCommerceOperation("checkouts", "post", "/detail"),
-    query: strictCommerceOperation("checkouts", "post", "/query")
-  },
-  draftOrders: {
-    calculate: operation("draft-orders", "post", "/:id/calculate"),
-    complete: operation("draft-orders", "post", "/:id/complete"),
-    finalize: operation("draft-orders", "post", "/:id/finalize")
-  },
-  transactions: {
-    update: operation("transactions", "post", "/update")
-  },
-  returns: {
-    create: operation("returns", "post", "/create"),
-    update: operation("returns", "post", "/update"),
-    returnRefund: operation("returns", "post", "/return-refund")
-  },
-  fulfillmentOrders: {
-    prepare: operation(
-      "fulfillment-orders",
-      "post",
-      "/prepare-fulfillment-order"
-    )
-  },
-  fulfillments: {
-    bulkImport: operation("fulfillments", "post", "/bulk-import")
-  },
-  carts: {
-    create: strictCommerceOperation("carts", "post", "/create"),
-    retrieve: strictCommerceOperation("carts", "post", "/retrieve"),
-    mine: strictCommerceOperation("carts", "post", "/mine"),
-    merge: strictCommerceOperation("carts", "post", "/merge"),
-    addItem: strictCommerceOperation("carts", "post", "/add-item"),
-    updateItem: strictCommerceOperation("carts", "post", "/update-item"),
-    removeItem: strictCommerceOperation("carts", "post", "/remove-item"),
-    updateDiscountCodes: strictCommerceOperation(
-      "carts",
-      "post",
-      "/update-discount-codes"
-    ),
-    updateAttributes: strictCommerceOperation(
-      "carts",
-      "post",
-      "/update-attributes"
-    ),
-    clear: strictCommerceOperation("carts", "post", "/clear")
-  },
-  paymentSessions: {
-    create: strictCommerceOperation("payment-sessions", "post", "/create"),
-    retrieve: strictCommerceOperation("payment-sessions", "post", "/retrieve"),
-    cancel: strictCommerceOperation("payment-sessions", "post", "/cancel"),
-    server: {
-      create: strictCommerceOperation(
-        "payment-sessions",
-        "post",
-        "/server/create"
-      ),
-      retrieve: strictCommerceOperation(
-        "payment-sessions",
-        "post",
-        "/server/retrieve"
-      ),
-      cancel: strictCommerceOperation(
-        "payment-sessions",
-        "post",
-        "/server/cancel"
-      ),
-      confirm: strictCommerceOperation(
-        "payment-sessions",
-        "post",
-        "/server/confirm"
-      ),
-      findPortOne: strictCommerceOperation(
-        "payment-sessions",
-        "post",
-        "/server/portone/find"
-      ),
-      reconcilePortOne: strictCommerceOperation(
-        "payment-sessions",
-        "post",
-        "/server/portone/reconcile"
-      )
-    },
-    custom: {
-      create: operation("orders", "post", "/custom-payment-sessions"),
-      retrieve: operation(
-        "orders",
-        "post",
-        "/custom-payment-sessions/retrieve"
-      ),
-      confirm: operation("orders", "post", "/custom-payment-sessions/confirm")
+  buildUrl(endpoint, options) {
+    if (!options) return endpoint;
+    const { fallbackLocale, ...rest } = options;
+    const queryOptions = fallbackLocale === void 0 ? rest : {
+      ...rest,
+      "fallback-locale": fallbackLocale === false ? "none" : fallbackLocale
+    };
+    const encodedOptions = validateWhere(queryOptions.where) ? { ...queryOptions, where: JSON.stringify(queryOptions.where) } : queryOptions;
+    const queryString = stringify(encodedOptions, { addQueryPrefix: true });
+    return queryString ? `${endpoint}${queryString}` : endpoint;
+  }
+  assertJsonResponse(response) {
+    const contentType = response.headers.get("content-type");
+    if (!contentType?.includes("application/json")) {
+      throw createApiError("Response is not in JSON format.", response.status, {
+        contentType
+      });
+    }
+  }
+  /**
+   * Parse Payload CMS find response (list query)
+   * Returns native Payload response structure
+   */
+  async parseFindResponse(response) {
+    const contentType = response.headers.get("content-type");
+    try {
+      this.assertJsonResponse(response);
+      const jsonData = await response.json();
+      if (jsonData.docs === void 0) {
+        throw createApiError("Invalid find response.", response.status, {
+          jsonData
+        });
+      }
+      return {
+        docs: jsonData.docs,
+        totalDocs: jsonData.totalDocs ?? 0,
+        limit: jsonData.limit || 20,
+        totalPages: jsonData.totalPages ?? 0,
+        page: jsonData.page || 1,
+        pagingCounter: jsonData.pagingCounter || 1,
+        hasPrevPage: jsonData.hasPrevPage ?? false,
+        hasNextPage: jsonData.hasNextPage ?? false,
+        prevPage: jsonData.prevPage ?? null,
+        nextPage: jsonData.nextPage ?? null
+      };
+    } catch (error) {
+      if (error instanceof SDKError) throw error;
+      throw createApiError("Failed to parse response.", response.status, {
+        contentType,
+        error: error instanceof Error ? error.message : error
+      });
+    }
+  }
+  /**
+   * Parse Payload CMS mutation response (create/update)
+   * Returns native Payload response structure
+   */
+  async parseMutationResponse(response) {
+    const contentType = response.headers.get("content-type");
+    try {
+      this.assertJsonResponse(response);
+      const jsonData = await response.json();
+      if (jsonData.doc === void 0) {
+        throw createApiError("Invalid mutation response.", response.status, {
+          jsonData
+        });
+      }
+      return {
+        message: jsonData.message || "",
+        doc: jsonData.doc,
+        errors: jsonData.errors
+      };
+    } catch (error) {
+      if (error instanceof SDKError) throw error;
+      throw createApiError("Failed to parse response.", response.status, {
+        contentType,
+        error: error instanceof Error ? error.message : error
+      });
+    }
+  }
+  /**
+   * Parse Payload CMS document response (findById/delete)
+   * Returns document directly without wrapper
+   */
+  async parseDocumentResponse(response) {
+    const contentType = response.headers.get("content-type");
+    try {
+      this.assertJsonResponse(response);
+      const jsonData = await response.json();
+      return jsonData;
+    } catch (error) {
+      if (error instanceof SDKError) throw error;
+      throw createApiError("Failed to parse response.", response.status, {
+        contentType,
+        error: error instanceof Error ? error.message : error
+      });
     }
-  },
-  shippingPolicies: {
-    calculate: operation("shipping-policies", "post", "/calculate")
-  },
-  discounts: {
-    validate: operation("discounts", "post", "/validate")
   }
 };
-var portOneStandardActionCapabilityOperations = /* @__PURE__ */ new Set([
-  COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.create,
-  COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.retrieve,
-  COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.create,
-  COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.retrieve
-]);
-var MEMBERSHIP_ENDPOINT_OPERATIONS = {
-  subscribe: operation(null, "post", "/memberships/subscribe"),
-  billingCustody: operation(null, "post", "/memberships/billing-custody"),
-  cancel: operation(null, "post", "/memberships/:id/cancel"),
-  me: operation(null, "get", "/memberships/me"),
-  chargeResult: operation(null, "post", "/memberships/:id/charge-result"),
-  refundResult: operation(null, "post", "/memberships/:id/refund-result"),
-  revoke: operation(null, "post", "/memberships/:id/revoke")
-};
-var EXTERNAL_EFFECT_CLAIM_ENDPOINT_OPERATIONS = {
-  claim: operation(null, "post", "/external-effect-claims/claim"),
-  get: operation(null, "post", "/external-effect-claims/get"),
-  arm: operation(null, "post", "/external-effect-claims/arm"),
-  release: operation(null, "post", "/external-effect-claims/release"),
-  report: operation(null, "post", "/external-effect-claims/report"),
-  recovery: operation(null, "post", "/external-effect-claims/recovery")
-};
-var INSTALLATION_CREDENTIAL_ENDPOINT_OPERATIONS = {
-  create: operation(null, "post", "/installation-credentials/create"),
-  get: operation(null, "post", "/installation-credentials/get"),
-  replace: operation(null, "post", "/installation-credentials/replace"),
-  dispose: operation(null, "post", "/installation-credentials/dispose")
-};
-var EXTERNAL_CUSTOMER_LINK_ENDPOINT_OPERATIONS = {
-  connect: operation("customers", "post", "/external-links/connect"),
-  get: operation("customers", "post", "/external-links/get"),
-  list: operation("customers", "post", "/external-links/list"),
-  unlink: operation("customers", "post", "/external-links/unlink"),
-  capturePreviousState: operation(
-    "customers",
-    "post",
-    "/external-links/capture-previous-state"
-  ),
-  clearPreviousState: operation(
-    "customers",
-    "post",
-    "/external-links/clear-previous-state"
-  )
-};
-var CUSTOMER_GROUP_ENDPOINT_OPERATIONS = {
-  members: operation("customer-groups", "get", "/:id/members"),
-  grant: operation("customer-groups", "post", "/:id/members/grant"),
-  revoke: operation("customer-groups", "post", "/:id/members/revoke")
-};
-var CUSTOMER_AUTH_ENDPOINT_OPERATIONS = {
-  register: operation("customers", "post", "/register"),
-  login: operation("customers", "post", "/login"),
-  refresh: operation("customers", "post", "/refresh"),
-  me: operation("customers", "get", "/me"),
-  updateProfile: operation("customers", "patch", "/me"),
-  forgotPassword: operation("customers", "post", "/forgot-password"),
-  resetPassword: operation("customers", "post", "/reset-password"),
-  changePassword: operation("customers", "post", "/change-password"),
-  revokeRefresh: operation("customers", "post", "/revoke-refresh"),
-  withdraw: operation("customers", "post", "/withdraw")
-};
-var EMBEDDED_ADMIN_ENDPOINT_OPERATIONS = {
-  show: operation("tenants", "get", "/embedded-admin-app"),
-  configure: operation("tenants", "patch", "/embedded-admin-app"),
-  disable: operation("tenants", "delete", "/embedded-admin-app")
-};
-var EVENTS_ENDPOINT_OPERATIONS = {
-  registrations: {
-    listMine: operation("event-registrations", "get", "/my")
-  },
-  events: {
-    convertSchedule: operation("events", "post", "/:id/schedule")
-  },
-  occurrences: {
-    range: operation("event-occurrences", "get", "/range"),
-    admissionAvailability: operation(
-      "event-occurrences",
-      "get",
-      "/admission-availability"
-    )
+
+// src/utils/types.ts
+function resolveRelation(ref) {
+  if (typeof ref === "string" || typeof ref === "number" || ref === null || ref === void 0)
+    return null;
+  return ref;
+}
+
+// src/core/metadata/index.ts
+var OPEN_GRAPH_IMAGE_SIZE = "1200";
+var LEGACY_OPEN_GRAPH_IMAGE_SIZE = "1536";
+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?.[OPEN_GRAPH_IMAGE_SIZE] ?? image.sizes?.[LEGACY_OPEN_GRAPH_IMAGE_SIZE];
+  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 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);
   }
-};
-var COMMUNITY_ENDPOINT_OPERATIONS = {
-  posts: {
-    detail: operation("posts", "get", "/detail")
+  /**
+   * 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);
   }
-};
-var GALLERY_ENDPOINT_OPERATIONS = {
-  items: {
-    storefront: operation("gallery-items", "get", "/storefront")
+  /**
+   * 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, options) {
+    return this.api.requestDelete(
+      `/api/${String(this.collection)}/${String(id)}`,
+      options
+    );
+  }
+  /**
+   * 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 VIDEO_ENDPOINT_OPERATIONS = {
-  playback: operation("videos", "post", "/:id/playback")
+var ServerCollectionQueryBuilder = class extends CollectionQueryBuilder {
 };
-function resolveOperationTemplate(descriptor) {
-  return descriptor.collection ? `/api/${descriptor.collection}${descriptor.path}` : `/api${descriptor.path}`;
+
+// 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;
 }
-function resolveOperationPath(descriptor, options) {
-  const path = resolveOperationTemplate(descriptor).replace(
-    /:([A-Za-z][A-Za-z0-9_]*)/g,
-    (_, key) => {
-      const value = options?.pathParams?.[key];
-      if (value === void 0) {
-        throw new TypeError(`Missing path parameter: ${key}`);
-      }
-      return encodeURIComponent(value);
-    }
-  );
-  const unresolved = path.match(/:([A-Za-z][A-Za-z0-9_]*)/);
-  if (unresolved) {
-    throw new TypeError(`Missing path parameter: ${unresolved[1]}`);
+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-like response from a cacheable GET custom endpoint.
+   */
+  async requestFindEndpointGet(endpoint) {
+    const response = await this.fetchWithTracking(endpoint, {
+      ...this.defaultOptions,
+      method: "GET"
+    });
+    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 url = this.buildUrl(endpoint, { where: data.where });
+    const response = await this.fetchWithTracking(url, {
+      ...this.defaultOptions,
+      method: "PATCH",
+      body: JSON.stringify(data.data)
+    });
+    return this.parseFindResponse(response);
+  }
+  /**
+   * Delete document
+   * DELETE /api/{collection}/{id}
+   */
+  async requestDelete(endpoint, options) {
+    const url = this.buildUrl(endpoint, options);
+    const response = await this.fetchWithTracking(url, {
+      ...this.defaultOptions,
+      method: "DELETE"
+    });
+    return this.parseDocumentResponse(response);
+  }
+  /**
+   * Delete multiple documents (bulk delete)
+   * DELETE /api/{collection}
+   */
+  async requestDeleteMany(endpoint, data) {
+    const url = this.buildUrl(endpoint, { where: data.where });
+    const response = await this.fetchWithTracking(url, {
+      ...this.defaultOptions,
+      method: "DELETE"
+    });
+    return this.parseFindResponse(response);
+  }
+  /**
+   * 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);
   }
-  const query = options?.query?.toString().replace(/^\?/, "");
-  return query ? `${path}?${query}` : path;
-}
-function resolveOperationMethod(descriptor) {
-  return descriptor.method.toUpperCase();
-}
-
-// src/core/api/endpoints.ts
-var sharedEndpoint = (descriptor) => descriptor;
-function resolveOperationErrorFamily(descriptor) {
-  return descriptor.errorFamily;
-}
-function resolveOperationTypedCommerceErrorReasons(descriptor) {
-  return descriptor.typedCommerceErrorReasons;
-}
-var COMMERCE_ENDPOINTS = {
-  products: {
-    detail: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.products.detail),
-    detailCatalog: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.products.detailCatalog
-    ),
-    listingGroups: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.products.listingGroups
-    ),
-    listingGroupsCatalog: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.products.listingGroupsCatalog
-    ),
-    // The manifest keeps the GET read and the POST body-query apart; this
-    // semantic name has always resolved to the GET one.
-    listingGroupsQuery: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.products.listingGroupsQueryGet
-    ),
-    listingGroupsQueryCatalog: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.products.listingGroupsQueryCatalog
-    ),
-    stockCheck: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.products.stockCheck
-    ),
-    stockSnapshot: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.products.stockSnapshot
-    ),
-    upsert: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.products.upsert)
-  },
-  orders: {
-    update: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.orders.update),
-    byPayment: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.orders.byPayment),
-    cancel: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.orders.cancel),
-    resolveCancelRefund: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.orders.resolveCancelRefund
-    ),
-    createFulfillment: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.orders.createFulfillment
-    ),
-    updateFulfillment: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.orders.updateFulfillment
-    )
-  },
-  checkouts: {
-    create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.orders.checkout),
-    retrieve: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.checkouts.detail),
-    server: {
-      create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.orders.checkout),
-      retrieve: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.checkouts.detail),
-      query: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.checkouts.query)
-    }
-  },
-  returns: {
-    create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.returns.create),
-    update: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.returns.update),
-    returnRefund: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.returns.returnRefund
-    )
-  },
-  fulfillmentOrders: {
-    prepare: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.fulfillmentOrders.prepare
-    )
-  },
-  fulfillments: {
-    bulkImport: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.fulfillments.bulkImport
-    )
-  },
-  carts: {
-    create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.create),
-    retrieve: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.retrieve),
-    mine: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.mine),
-    merge: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.merge),
-    server: {
-      // Server credentials are an authorization lane, not a second Cart
-      // transport. These must stay bound to the registered shared operations.
-      create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.create),
-      retrieve: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.retrieve),
-      mine: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.mine),
-      merge: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.merge),
-      addItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.addItem),
-      updateItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.updateItem),
-      removeItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.removeItem),
-      updateDiscountCodes: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.carts.updateDiscountCodes
-      ),
-      updateAttributes: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.carts.updateAttributes
-      ),
-      clear: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.clear)
-    },
-    addItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.addItem),
-    updateItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.updateItem),
-    removeItem: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.removeItem),
-    updateDiscountCodes: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.carts.updateDiscountCodes
-    ),
-    updateAttributes: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.carts.updateAttributes
-    ),
-    clear: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.carts.clear)
-  },
-  paymentSessions: {
-    create: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.create),
-    retrieve: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.retrieve
-    ),
-    cancel: sharedEndpoint(COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.cancel),
-    custom: {
-      create: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.custom.create
-      ),
-      retrieve: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.custom.retrieve
-      ),
-      confirm: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.custom.confirm
-      )
-    },
-    server: {
-      create: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.create
-      ),
-      retrieve: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.retrieve
-      ),
-      cancel: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.cancel
-      ),
-      confirm: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.confirm
-      ),
-      findPortOne: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.findPortOne
-      ),
-      reconcilePortOne: sharedEndpoint(
-        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.server.reconcilePortOne
-      )
-    }
-  },
-  shippingPolicies: {
-    calculate: sharedEndpoint(
-      COMMERCE_ENDPOINT_OPERATIONS.shippingPolicies.calculate
-    )
+  /**
+   * 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);
+  }
+};
+var ServerCollectionClient = class extends CollectionClient {
+  from(collection) {
+    return new ServerCollectionQueryBuilder(this, collection);
   }
 };
 
@@ -2454,81 +2642,6 @@ var CommunityClient = class extends RawCustomerScopedApi {
   }
 };
 
-// src/core/api/base-api.ts
-var ServerApiTransport = class {
-  constructor(apiName, options) {
-    if (!options.secretKey) {
-      throw createConfigError(`secretKey is required for ${apiName}.`);
-    }
-    this.publishableKey = requirePublishableKeyForSecret(
-      apiName,
-      options.publishableKey,
-      options.secretKey
-    );
-    this.secretKey = options.secretKey;
-    this.apiUrl = options.apiUrl;
-    this.onRequestId = options.onRequestId;
-  }
-  async request(endpoint, body, options) {
-    const method = options?.method ?? "POST";
-    try {
-      const response = await httpFetch(endpoint, {
-        method,
-        apiUrl: this.apiUrl,
-        publishableKey: this.publishableKey,
-        secretKey: this.secretKey,
-        ...body !== void 0 && { body: JSON.stringify(body) },
-        ...options?.headers && { headers: options.headers },
-        ...options?.errorFamily && { errorFamily: options.errorFamily },
-        ...options?.typedCommerceErrorReasons && {
-          typedCommerceErrorReasons: options.typedCommerceErrorReasons
-        }
-      });
-      this.onRequestId?.(response.headers.get("x-request-id") ?? null);
-      return parseApiResponse(response, endpoint, {
-        errorFamily: options?.errorFamily
-      });
-    } catch (err) {
-      const id = err instanceof SDKError ? err.requestId ?? null : null;
-      this.onRequestId?.(id);
-      throw err;
-    }
-  }
-};
-var BaseApi = class {
-  constructor(apiName, options) {
-    this.transport = new ServerApiTransport(apiName, options);
-  }
-  requestEndpoint(endpoint, body, options) {
-    return this.transport.request(
-      resolveOperationPath(endpoint, options),
-      body,
-      {
-        method: resolveOperationMethod(endpoint),
-        headers: options?.headers,
-        errorFamily: resolveOperationErrorFamily(endpoint),
-        typedCommerceErrorReasons: resolveOperationTypedCommerceErrorReasons(endpoint)
-      }
-    );
-  }
-};
-var RawBaseApi = class {
-  constructor(apiName, options) {
-    this.transport = new ServerApiTransport(apiName, options);
-    this.publishableKey = requirePublishableKeyForSecret(
-      apiName,
-      options.publishableKey,
-      options.secretKey
-    );
-    this.secretKey = options.secretKey;
-    this.apiUrl = options.apiUrl;
-    this.onRequestId = options.onRequestId;
-  }
-  request(endpoint, body, options) {
-    return this.transport.request(endpoint, body, options);
-  }
-};
-
 // src/core/community/moderation-api.ts
 var ModerationApi = class extends RawBaseApi {
   constructor(options) {
@@ -6609,8 +6722,8 @@ var InstallationCredentialsApi = class extends BaseApi {
 function invalidResponse3() {
   throw createApiError("Invalid external-customer link response", 200);
 }
-var uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-var isUuid = (value) => typeof value === "string" && (uuid.test(value) || value === "00000000-0000-0000-0000-000000000000" || value.toLowerCase() === "ffffffff-ffff-ffff-ffff-ffffffffffff");
+var uuid2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var isUuid = (value) => typeof value === "string" && (uuid2.test(value) || value === "00000000-0000-0000-0000-000000000000" || value.toLowerCase() === "ffffffff-ffff-ffff-ffff-ffffffffffff");
 var isIdentity = (value) => typeof value === "string" && value.length > 0 && value.length <= 256 && value === value.trim() && // eslint-disable-next-line no-control-regex -- Normalized identity forbids C0 controls.
 !/[\u0000-\u001f]/.test(value) && !/[\uD800-\uDFFF]/u.test(value);
 var isDateTime = (value) => {
@@ -6757,6 +6870,7 @@ var ServerClient = class _ServerClient {
     this.customerGroups = new CustomerGroupApi(serverOptions);
     this.externalEffectClaims = new ExternalEffectClaimsApi(serverOptions);
     this.installationCredentials = new InstallationCredentialsApi(serverOptions);
+    this.benefitVouchers = new BenefitVouchersApi(serverOptions);
     this.externalCustomerLinks = new ExternalCustomerLinksApi(serverOptions);
     const tenantIntrospectionApi = new TenantIntrospectionApi(serverOptions);
     this.tenant = {
@@ -6831,6 +6945,7 @@ function createServerClient(options) {
   return new ServerClient(options);
 }
 export {
+  BenefitVouchersApi,
   CollectionClient,
   CommunityClient,
   CustomerGroupApi,