@01.software/sdk 0.41.1 → 0.43.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/CHANGELOG.md +246 -0
  2. package/README.md +88 -19
  3. package/dist/analytics/react.cjs +71 -3
  4. package/dist/analytics/react.cjs.map +1 -1
  5. package/dist/analytics/react.d.cts +18 -2
  6. package/dist/analytics/react.d.ts +18 -2
  7. package/dist/analytics/react.js +67 -3
  8. package/dist/analytics/react.js.map +1 -1
  9. package/dist/analytics.cjs +6 -2
  10. package/dist/analytics.cjs.map +1 -1
  11. package/dist/analytics.d.cts +17 -4
  12. package/dist/analytics.d.ts +17 -4
  13. package/dist/analytics.js +6 -2
  14. package/dist/analytics.js.map +1 -1
  15. package/dist/client.cjs +233 -47
  16. package/dist/client.cjs.map +1 -1
  17. package/dist/client.d.cts +9 -6
  18. package/dist/client.d.ts +9 -6
  19. package/dist/client.js +233 -47
  20. package/dist/client.js.map +1 -1
  21. package/dist/{collection-client-Bk--pNzW.d.cts → collection-client-U70KizLf.d.cts} +3 -3
  22. package/dist/{collection-client-BdcxkW7l.d.ts → collection-client-gWsA7BVP.d.ts} +3 -3
  23. package/dist/{const-qGGI7Uii.d.cts → const-BBynifk0.d.cts} +5 -5
  24. package/dist/{const-HwdntWtG.d.ts → const-_WWHU-gX.d.ts} +5 -5
  25. package/dist/{index-B1oW50RY.d.ts → index-DPi5NWU8.d.ts} +4 -4
  26. package/dist/{index-DiXtjVab.d.cts → index-Dg4Y6Aq7.d.cts} +4 -4
  27. package/dist/index.cjs +225 -358
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.d.cts +41 -8
  30. package/dist/index.d.ts +41 -8
  31. package/dist/index.js +225 -358
  32. package/dist/index.js.map +1 -1
  33. package/dist/{payload-types-CqJOgON7.d.cts → payload-types-DLxkB7Mv.d.cts} +561 -123
  34. package/dist/{payload-types-CqJOgON7.d.ts → payload-types-DLxkB7Mv.d.ts} +561 -123
  35. package/dist/query.cjs +59 -7
  36. package/dist/query.cjs.map +1 -1
  37. package/dist/query.d.cts +5 -5
  38. package/dist/query.d.ts +5 -5
  39. package/dist/query.js +59 -7
  40. package/dist/query.js.map +1 -1
  41. package/dist/realtime.cjs +1 -1
  42. package/dist/realtime.cjs.map +1 -1
  43. package/dist/realtime.d.cts +2 -2
  44. package/dist/realtime.d.ts +2 -2
  45. package/dist/realtime.js +1 -1
  46. package/dist/realtime.js.map +1 -1
  47. package/dist/server.cjs +318 -61
  48. package/dist/server.cjs.map +1 -1
  49. package/dist/server.d.cts +12 -7
  50. package/dist/server.d.ts +12 -7
  51. package/dist/server.js +318 -61
  52. package/dist/server.js.map +1 -1
  53. package/dist/{types-ByLSG-O3.d.cts → types-B1ngKbWI.d.cts} +1 -1
  54. package/dist/{types-BKa9z9s2.d.cts → types-B9lGhZlB.d.ts} +229 -15
  55. package/dist/{types-BMI3M0nb.d.ts → types-BiKNBwRA.d.ts} +1 -1
  56. package/dist/{types-DgfXb7iV.d.ts → types-Bpx5sYKo.d.cts} +229 -15
  57. package/dist/ui/canvas.cjs.map +1 -1
  58. package/dist/ui/canvas.js.map +1 -1
  59. package/dist/ui/form.d.cts +1 -1
  60. package/dist/ui/form.d.ts +1 -1
  61. package/dist/ui/video.d.cts +1 -1
  62. package/dist/ui/video.d.ts +1 -1
  63. package/dist/webhook.cjs +3 -1
  64. package/dist/webhook.cjs.map +1 -1
  65. package/dist/webhook.d.cts +4 -4
  66. package/dist/webhook.d.ts +4 -4
  67. package/dist/webhook.js +3 -1
  68. package/dist/webhook.js.map +1 -1
  69. package/package.json +1 -1
package/dist/server.cjs CHANGED
@@ -105,6 +105,26 @@ var TimeoutError = class extends SDKError {
105
105
  this.name = "TimeoutError";
106
106
  }
107
107
  };
108
+ var GoneError = class extends SDKError {
109
+ constructor(message = "The requested resource is no longer available.", details, userMessage, suggestion) {
110
+ super("GONE_ERROR", message, 410, details, userMessage, suggestion);
111
+ this.name = "GoneError";
112
+ }
113
+ };
114
+ var ServiceUnavailableError = class extends SDKError {
115
+ constructor(message = "Service temporarily unavailable.", retryAfter, details, userMessage, suggestion) {
116
+ super(
117
+ "SERVICE_UNAVAILABLE_ERROR",
118
+ message,
119
+ 503,
120
+ details,
121
+ userMessage,
122
+ suggestion
123
+ );
124
+ this.name = "ServiceUnavailableError";
125
+ this.retryAfter = retryAfter;
126
+ }
127
+ };
108
128
  var UsageLimitError = class extends SDKError {
109
129
  constructor(message, usage, details, userMessage, suggestion) {
110
130
  super("USAGE_LIMIT_ERROR", message, 429, details, userMessage, suggestion);
@@ -186,6 +206,14 @@ var createValidationError = (message, details, userMessage, suggestion, status)
186
206
  var createApiError = (message, status, details, userMessage, suggestion, requestId) => new ApiError(message, status, details, userMessage, suggestion, requestId);
187
207
  var createConfigError = (message, details, userMessage, suggestion) => new ConfigError(message, details, userMessage, suggestion);
188
208
  var createTimeoutError = (message, details, userMessage, suggestion) => new TimeoutError(message, details, userMessage, suggestion);
209
+ var createGoneError = (message, details, userMessage, suggestion) => new GoneError(message, details, userMessage, suggestion);
210
+ var createServiceUnavailableError = (message, retryAfter, details, userMessage, suggestion) => new ServiceUnavailableError(
211
+ message,
212
+ retryAfter,
213
+ details,
214
+ userMessage,
215
+ suggestion
216
+ );
189
217
  var createUsageLimitError = (message, usage, details, userMessage, suggestion) => new UsageLimitError(message, usage, details, userMessage, suggestion);
190
218
  var createAuthError = (message, details, userMessage, suggestion, requestId) => new AuthError(message, details, userMessage, suggestion, requestId);
191
219
  var createPermissionError = (message, details, userMessage, suggestion, requestId) => new PermissionError(message, details, userMessage, suggestion, requestId);
@@ -210,7 +238,7 @@ function requirePublishableKeyForSecret(apiName, publishableKey, secretKey) {
210
238
  return publishableKey ?? "";
211
239
  }
212
240
 
213
- // src/core/client/types.ts
241
+ // src/core/internal/utils/api-url.ts
214
242
  function resolveApiUrl(apiUrl) {
215
243
  if (apiUrl) {
216
244
  return apiUrl.replace(/\/$/, "");
@@ -227,7 +255,7 @@ function resolveApiUrl(apiUrl) {
227
255
  // src/core/internal/utils/http.ts
228
256
  var DEFAULT_TIMEOUT = 3e4;
229
257
  var STOREFRONT_BROWSER_TIMEOUT = 15e3;
230
- var DEFAULT_RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504];
258
+ var DEFAULT_RETRYABLE_STATUSES = [408, 500, 502, 503, 504];
231
259
  var NON_RETRYABLE_STATUSES = [400, 401, 403, 404, 409, 422];
232
260
  var SAFE_METHODS = ["GET", "HEAD", "OPTIONS"];
233
261
  var DEFAULT_MAX_RETRIES = 3;
@@ -344,7 +372,12 @@ function attachRequestId(err, id) {
344
372
  if (id) err.requestId = id;
345
373
  return err;
346
374
  }
347
- function createHttpStatusError(status, parsed, details, requestId) {
375
+ function parseRetryAfter(response) {
376
+ const raw = response.headers.get("Retry-After");
377
+ if (!raw) return void 0;
378
+ return parseInt(raw, 10) || void 0;
379
+ }
380
+ function mapResponseToError(status, parsed, details, requestId, retryAfter) {
348
381
  const errorDetails = {
349
382
  ...details,
350
383
  ...parsed.errors && { errors: parsed.errors },
@@ -407,6 +440,41 @@ function createHttpStatusError(status, parsed, details, requestId) {
407
440
  requestId
408
441
  );
409
442
  }
443
+ if (status === 410) {
444
+ return attachRequestId(
445
+ createGoneError(
446
+ parsed.errorMessage,
447
+ errorDetails,
448
+ parsed.userMessage,
449
+ suggestion
450
+ ),
451
+ requestId
452
+ );
453
+ }
454
+ if (status === 429) {
455
+ return attachRequestId(
456
+ createRateLimitError(
457
+ parsed.errorMessage,
458
+ retryAfter,
459
+ errorDetails,
460
+ parsed.userMessage,
461
+ suggestion
462
+ ),
463
+ requestId
464
+ );
465
+ }
466
+ if (status === 503) {
467
+ return attachRequestId(
468
+ createServiceUnavailableError(
469
+ parsed.errorMessage,
470
+ retryAfter,
471
+ errorDetails,
472
+ parsed.userMessage,
473
+ suggestion
474
+ ),
475
+ requestId
476
+ );
477
+ }
410
478
  return attachRequestId(
411
479
  createNetworkError(
412
480
  parsed.errorMessage,
@@ -525,26 +593,17 @@ async function httpFetch(url, options) {
525
593
  method: requestInit.method || "GET",
526
594
  attempt: attempt + 1
527
595
  };
528
- if (NON_RETRYABLE_STATUSES.includes(response.status)) {
529
- throw createHttpStatusError(
530
- response.status,
531
- parsed,
532
- details,
533
- requestId
534
- );
535
- }
536
- const error = attachRequestId(
537
- createNetworkError(
538
- parsed.errorMessage,
539
- response.status,
540
- details,
541
- parsed.userMessage,
542
- getErrorSuggestion(response.status)
543
- ),
544
- requestId
596
+ const retryAfter = parseRetryAfter(response);
597
+ const error = mapResponseToError(
598
+ response.status,
599
+ parsed,
600
+ details,
601
+ requestId,
602
+ retryAfter
545
603
  );
546
604
  const method2 = (requestInit.method || "GET").toUpperCase();
547
- if (attempt < retryConfig.maxRetries && SAFE_METHODS.includes(method2) && retryConfig.retryableStatuses.includes(response.status)) {
605
+ const isTerminal = error instanceof RateLimitError || error instanceof UsageLimitError;
606
+ if (attempt < retryConfig.maxRetries && SAFE_METHODS.includes(method2) && !isTerminal && !NON_RETRYABLE_STATUSES.includes(response.status) && retryConfig.retryableStatuses.includes(response.status)) {
548
607
  lastError = error;
549
608
  const retryDelay = retryConfig.retryDelay(attempt);
550
609
  debugLog(debug, "error", `Retrying in ${retryDelay}ms...`, error);
@@ -616,6 +675,64 @@ async function httpFetch(url, options) {
616
675
  throw lastError ?? new NetworkError("Request failed after retries");
617
676
  }
618
677
 
678
+ // src/core/api/endpoints.ts
679
+ var COMMERCE_ENDPOINTS = {
680
+ orders: {
681
+ create: "/api/orders/create",
682
+ update: "/api/orders/update",
683
+ confirmPayment: "/api/orders/confirm-payment",
684
+ byPayment: "/api/orders/by-payment",
685
+ cancel: "/api/orders/cancel",
686
+ resolveCancelRefund: "/api/orders/resolve-cancel-refund",
687
+ checkout: "/api/orders/checkout",
688
+ createFulfillment: "/api/orders/create-fulfillment",
689
+ updateFulfillment: "/api/orders/update-fulfillment"
690
+ },
691
+ transactions: {
692
+ update: "/api/transactions/update"
693
+ },
694
+ returns: {
695
+ create: "/api/returns/create",
696
+ update: "/api/returns/update",
697
+ returnRefund: "/api/returns/return-refund"
698
+ },
699
+ fulfillmentOrders: {
700
+ prepare: "/api/fulfillment-orders/prepare-fulfillment-order"
701
+ },
702
+ fulfillments: {
703
+ bulkImport: "/api/fulfillments/bulk-import"
704
+ },
705
+ carts: {
706
+ mine: "/api/carts/mine",
707
+ merge: "/api/carts/merge",
708
+ addItem: "/api/carts/add-item",
709
+ updateItem: "/api/carts/update-item",
710
+ removeItem: "/api/carts/remove-item",
711
+ applyDiscount: "/api/carts/apply-discount",
712
+ removeDiscount: "/api/carts/remove-discount",
713
+ clear: "/api/carts/clear"
714
+ },
715
+ products: {
716
+ stockCheck: "/api/products/stock-check",
717
+ stockSnapshot: "/api/products/stock",
718
+ listingGroups: "/api/products/listing-groups",
719
+ listingGroupsCatalog: "/api/products/listing-groups/catalog",
720
+ listingGroupsQuery: "/api/products/listing-groups/query",
721
+ listingGroupsQueryCatalog: "/api/products/listing-groups/query/catalog",
722
+ detail: "/api/products/detail",
723
+ detailCatalog: "/api/products/detail/catalog",
724
+ upsert: "/api/products/upsert"
725
+ }
726
+ };
727
+ var COMMERCE_ENDPOINT_PATHS = Object.values(
728
+ COMMERCE_ENDPOINTS
729
+ ).flatMap((group) => Object.values(group));
730
+ var MEMBERSHIP_ENDPOINTS = {
731
+ subscribe: "/api/memberships/subscribe",
732
+ cancel: (id) => `/api/memberships/${id}/cancel`,
733
+ me: "/api/memberships/me"
734
+ };
735
+
619
736
  // src/core/internal/utils/query-string.ts
620
737
  function productDetailQuery(params) {
621
738
  const search = new URLSearchParams();
@@ -624,7 +741,7 @@ function productDetailQuery(params) {
624
741
  } else {
625
742
  search.set("id", params.id);
626
743
  }
627
- return `/api/products/detail?${search}`;
744
+ return `${COMMERCE_ENDPOINTS.products.detail}?${search}`;
628
745
  }
629
746
  function productDetailCatalogQuery(params) {
630
747
  const search = new URLSearchParams();
@@ -633,23 +750,20 @@ function productDetailCatalogQuery(params) {
633
750
  } else {
634
751
  search.set("id", params.id);
635
752
  }
636
- return `/api/products/detail/catalog?${search}`;
753
+ return `${COMMERCE_ENDPOINTS.products.detailCatalog}?${search}`;
637
754
  }
638
755
  function listingGroupsQuery(params) {
639
- return `/api/products/listing-groups?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
756
+ return `${COMMERCE_ENDPOINTS.products.listingGroups}?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
640
757
  }
641
758
  function listingGroupsCatalogQuery(params) {
642
- return `/api/products/listing-groups/catalog?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
759
+ return `${COMMERCE_ENDPOINTS.products.listingGroupsCatalog}?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
643
760
  }
644
761
  function appendListingGroupsQuerySearchParams(search, options) {
645
762
  if (options?.page != null) search.set("page", String(options.page));
646
763
  if (options?.limit != null) search.set("limit", String(options.limit));
647
764
  if (options?.sort != null) {
648
765
  const sort = options.sort;
649
- search.set(
650
- "sort",
651
- Array.isArray(sort) ? sort.join(",") : sort
652
- );
766
+ search.set("sort", Array.isArray(sort) ? sort.join(",") : sort);
653
767
  }
654
768
  if (options?.where != null) {
655
769
  search.set("whereJson", JSON.stringify(options.where));
@@ -659,16 +773,16 @@ function listingGroupsQueryUrl(options) {
659
773
  const search = new URLSearchParams();
660
774
  appendListingGroupsQuerySearchParams(search, options);
661
775
  const query = search.toString();
662
- return `/api/products/listing-groups/query${query ? `?${query}` : ""}`;
776
+ return `${COMMERCE_ENDPOINTS.products.listingGroupsQuery}${query ? `?${query}` : ""}`;
663
777
  }
664
778
  function listingGroupsQueryCatalogUrl(options) {
665
779
  const search = new URLSearchParams();
666
780
  appendListingGroupsQuerySearchParams(search, options);
667
781
  const query = search.toString();
668
- return `/api/products/listing-groups/query/catalog${query ? `?${query}` : ""}`;
782
+ return `${COMMERCE_ENDPOINTS.products.listingGroupsQueryCatalog}${query ? `?${query}` : ""}`;
669
783
  }
670
784
  function stockSnapshotQuery(params) {
671
- return `/api/products/stock?variantIds=${params.variantIds.map(encodeURIComponent).join(",")}`;
785
+ return `${COMMERCE_ENDPOINTS.products.stockSnapshot}?variantIds=${params.variantIds.map(encodeURIComponent).join(",")}`;
672
786
  }
673
787
 
674
788
  // src/core/collection/http-client.ts
@@ -1617,39 +1731,78 @@ var ModerationApi = class extends BaseApi {
1617
1731
  // src/core/api/cart-api.ts
1618
1732
  var CartApi = class extends CustomerScopedApi {
1619
1733
  constructor(options) {
1620
- super("CartApi", options);
1734
+ super("CartApi", { ...options, requiresCredential: false });
1621
1735
  }
1622
1736
  async execute(endpoint, method, body) {
1623
1737
  return this.request(endpoint, { method, body });
1624
1738
  }
1625
- getCart(cartId) {
1739
+ /**
1740
+ * Create a cart and receive its `cartToken`. Store the token and pass it to
1741
+ * every subsequent cart operation.
1742
+ */
1743
+ createCart(params = {}) {
1744
+ return this.execute("/api/carts/create", "POST", params);
1745
+ }
1746
+ getCart(cartToken) {
1747
+ return this.execute("/api/carts/get", "POST", { cartToken });
1748
+ }
1749
+ merge(params) {
1626
1750
  return this.execute(
1627
- `/api/carts/${cartId}?depth=0&joins=false`,
1628
- "GET"
1751
+ COMMERCE_ENDPOINTS.carts.merge,
1752
+ "POST",
1753
+ params
1754
+ );
1755
+ }
1756
+ /**
1757
+ * Resolve the authenticated customer's active cart by JWT (no `cartToken`
1758
+ * required). Returns the cart and its capability handle, or both `null` when
1759
+ * the customer has no active cart. Requires a customer token.
1760
+ */
1761
+ mine() {
1762
+ return this.execute(
1763
+ COMMERCE_ENDPOINTS.carts.mine,
1764
+ "POST",
1765
+ {}
1629
1766
  );
1630
1767
  }
1631
1768
  addItem(params) {
1632
- return this.execute("/api/carts/add-item", "POST", params);
1769
+ return this.execute(
1770
+ COMMERCE_ENDPOINTS.carts.addItem,
1771
+ "POST",
1772
+ params
1773
+ );
1633
1774
  }
1634
1775
  updateItem(params) {
1635
- return this.execute("/api/carts/update-item", "POST", params);
1776
+ return this.execute(
1777
+ COMMERCE_ENDPOINTS.carts.updateItem,
1778
+ "POST",
1779
+ params
1780
+ );
1636
1781
  }
1637
1782
  removeItem(params) {
1638
1783
  return this.execute(
1639
- "/api/carts/remove-item",
1784
+ COMMERCE_ENDPOINTS.carts.removeItem,
1640
1785
  "POST",
1641
1786
  params
1642
1787
  );
1643
1788
  }
1644
1789
  applyDiscount(params) {
1645
- return this.execute("/api/carts/apply-discount", "POST", params);
1790
+ return this.execute(
1791
+ COMMERCE_ENDPOINTS.carts.applyDiscount,
1792
+ "POST",
1793
+ params
1794
+ );
1646
1795
  }
1647
1796
  removeDiscount(params) {
1648
- return this.execute("/api/carts/remove-discount", "POST", params);
1797
+ return this.execute(
1798
+ COMMERCE_ENDPOINTS.carts.removeDiscount,
1799
+ "POST",
1800
+ params
1801
+ );
1649
1802
  }
1650
1803
  clearCart(params) {
1651
1804
  return this.execute(
1652
- "/api/carts/clear",
1805
+ COMMERCE_ENDPOINTS.carts.clear,
1653
1806
  "POST",
1654
1807
  params
1655
1808
  );
@@ -2460,6 +2613,7 @@ function compareVariantOrder(a, b) {
2460
2613
  function getVariantAvailableForSale(variant) {
2461
2614
  if (variant.isActive === false) return false;
2462
2615
  if (variant.isUnlimited) return true;
2616
+ if (variant.inventoryPolicy === "continue") return true;
2463
2617
  return (variant.stock ?? 0) - (variant.reservedStock ?? 0) > 0;
2464
2618
  }
2465
2619
  function isVariantAvailableForSale(variant) {
@@ -2798,7 +2952,10 @@ var ProductApi = class extends BaseApi {
2798
2952
  * to remain available by the time an order is placed.
2799
2953
  */
2800
2954
  stockCheck(params) {
2801
- return this.request("/api/products/stock-check", params);
2955
+ return this.request(
2956
+ COMMERCE_ENDPOINTS.products.stockCheck,
2957
+ params
2958
+ );
2802
2959
  }
2803
2960
  stockSnapshot(params) {
2804
2961
  return this.request(
@@ -2875,7 +3032,7 @@ var ProductApi = class extends BaseApi {
2875
3032
  */
2876
3033
  upsert(params) {
2877
3034
  return this.request(
2878
- "/api/products/upsert",
3035
+ COMMERCE_ENDPOINTS.products.upsert,
2879
3036
  normalizeProductUpsertParams(params)
2880
3037
  );
2881
3038
  }
@@ -2925,26 +3082,61 @@ var OrderApi = class extends BaseApi {
2925
3082
  const { idempotencyKey } = params;
2926
3083
  const normalizedBody = normalizeCreateOrderBody(params);
2927
3084
  return this.request(
2928
- "/api/orders/create",
3085
+ COMMERCE_ENDPOINTS.orders.create,
2929
3086
  normalizedBody,
2930
3087
  idempotencyRequestOptions(idempotencyKey)
2931
3088
  );
2932
3089
  }
2933
3090
  updateOrder(params) {
2934
- return this.request("/api/orders/update", params);
3091
+ return this.request(COMMERCE_ENDPOINTS.orders.update, params);
2935
3092
  }
2936
3093
  updateTransaction(params) {
2937
- return this.request("/api/transactions/update", params);
3094
+ return this.request(
3095
+ COMMERCE_ENDPOINTS.transactions.update,
3096
+ params
3097
+ );
2938
3098
  }
2939
3099
  confirmPayment(params) {
2940
3100
  const { body, idempotencyKey } = splitIdempotencyKey(params);
2941
3101
  const headerKey = idempotencyKey ?? params.providerEventId;
2942
3102
  return this.request(
2943
- "/api/orders/confirm-payment",
3103
+ COMMERCE_ENDPOINTS.orders.confirmPayment,
2944
3104
  body,
2945
3105
  idempotencyRequestOptions(headerKey)
2946
3106
  );
2947
3107
  }
3108
+ /**
3109
+ * Resolve an order + its payment transaction by PG payment id. Replaces raw
3110
+ * `transactions.find({ where: { pgPaymentId } })` + a local file index in
3111
+ * storefronts. Server-only (sk01_) read of the full populated Order.
3112
+ */
3113
+ getByPaymentId(params) {
3114
+ const query = new URLSearchParams({
3115
+ pgProvider: params.pgProvider,
3116
+ pgPaymentId: params.pgPaymentId
3117
+ }).toString();
3118
+ return this.request(
3119
+ `${COMMERCE_ENDPOINTS.orders.byPayment}?${query}`,
3120
+ void 0,
3121
+ { method: "GET" }
3122
+ );
3123
+ }
3124
+ /**
3125
+ * Composed facade: confirm a provider payment, then resolve the
3126
+ * depth-populated order/transaction by the same payment id. `confirmPayment`'s
3127
+ * wire response carries only IDs (its contract is `.strict()`); this returns
3128
+ * the populated `Order` so storefronts stop reconstructing order state
3129
+ * locally. Two round trips by design — the alternative (widening the strict
3130
+ * confirm-payment wire contract to embed a full Order) is rejected.
3131
+ */
3132
+ async confirmPaymentReturningOrder(params) {
3133
+ const confirmation = await this.confirmPayment(params);
3134
+ const { order, transaction } = await this.getByPaymentId({
3135
+ pgProvider: params.pgProvider,
3136
+ pgPaymentId: params.pgPaymentId
3137
+ });
3138
+ return { ...confirmation, order, transaction };
3139
+ }
2948
3140
  cancelOrder(params) {
2949
3141
  const { idempotencyKey } = params;
2950
3142
  const body = {
@@ -2953,14 +3145,14 @@ var OrderApi = class extends BaseApi {
2953
3145
  reasonDetail: params.reasonDetail
2954
3146
  };
2955
3147
  return this.request(
2956
- "/api/orders/cancel",
3148
+ COMMERCE_ENDPOINTS.orders.cancel,
2957
3149
  body,
2958
3150
  idempotencyKey ? { headers: { "X-Idempotency-Key": idempotencyKey } } : void 0
2959
3151
  );
2960
3152
  }
2961
3153
  resolveCancelRefund(params) {
2962
3154
  return this.request(
2963
- "/api/orders/resolve-cancel-refund",
3155
+ COMMERCE_ENDPOINTS.orders.resolveCancelRefund,
2964
3156
  {
2965
3157
  orderNumber: params.orderNumber,
2966
3158
  idempotencyKey: params.idempotencyKey,
@@ -2981,7 +3173,7 @@ var OrderApi = class extends BaseApi {
2981
3173
  checkout(params) {
2982
3174
  const { body, idempotencyKey } = splitIdempotencyKey(params);
2983
3175
  return this.request(
2984
- "/api/orders/checkout",
3176
+ COMMERCE_ENDPOINTS.orders.checkout,
2985
3177
  body,
2986
3178
  idempotencyRequestOptions(idempotencyKey)
2987
3179
  );
@@ -2989,30 +3181,33 @@ var OrderApi = class extends BaseApi {
2989
3181
  createFulfillment(params) {
2990
3182
  const { body, idempotencyKey } = splitIdempotencyKey(params);
2991
3183
  return this.request(
2992
- "/api/orders/create-fulfillment",
3184
+ COMMERCE_ENDPOINTS.orders.createFulfillment,
2993
3185
  body,
2994
3186
  idempotencyRequestOptions(idempotencyKey)
2995
3187
  );
2996
3188
  }
2997
3189
  prepareFulfillmentOrder(params) {
2998
3190
  return this.request(
2999
- "/api/fulfillment-orders/prepare-fulfillment-order",
3191
+ COMMERCE_ENDPOINTS.fulfillmentOrders.prepare,
3000
3192
  params
3001
3193
  );
3002
3194
  }
3003
3195
  updateFulfillment(params) {
3004
- return this.request("/api/orders/update-fulfillment", params);
3196
+ return this.request(
3197
+ COMMERCE_ENDPOINTS.orders.updateFulfillment,
3198
+ params
3199
+ );
3005
3200
  }
3006
3201
  bulkImportFulfillments(params) {
3007
3202
  return this.request(
3008
- "/api/fulfillments/bulk-import",
3203
+ COMMERCE_ENDPOINTS.fulfillments.bulkImport,
3009
3204
  params
3010
3205
  );
3011
3206
  }
3012
3207
  returnWithRefund(params) {
3013
3208
  const { body, idempotencyKey } = splitIdempotencyKey(params);
3014
3209
  return this.request(
3015
- "/api/returns/return-refund",
3210
+ COMMERCE_ENDPOINTS.returns.returnRefund,
3016
3211
  body,
3017
3212
  idempotencyRequestOptions(idempotencyKey)
3018
3213
  );
@@ -3020,13 +3215,13 @@ var OrderApi = class extends BaseApi {
3020
3215
  createReturn(params) {
3021
3216
  const { body, idempotencyKey } = splitIdempotencyKey(params);
3022
3217
  return this.request(
3023
- "/api/returns/create",
3218
+ COMMERCE_ENDPOINTS.returns.create,
3024
3219
  body,
3025
3220
  idempotencyRequestOptions(idempotencyKey)
3026
3221
  );
3027
3222
  }
3028
3223
  updateReturn(params) {
3029
- return this.request("/api/returns/update", params);
3224
+ return this.request(COMMERCE_ENDPOINTS.returns.update, params);
3030
3225
  }
3031
3226
  };
3032
3227
 
@@ -3112,13 +3307,16 @@ var ServerCommerceClient = class {
3112
3307
  upsert: productApi.upsert.bind(productApi)
3113
3308
  };
3114
3309
  this.cart = {
3310
+ create: cartApi.createCart.bind(cartApi),
3115
3311
  get: cartApi.getCart.bind(cartApi),
3116
3312
  addItem: cartApi.addItem.bind(cartApi),
3117
3313
  updateItem: cartApi.updateItem.bind(cartApi),
3118
3314
  removeItem: cartApi.removeItem.bind(cartApi),
3119
3315
  applyDiscount: cartApi.applyDiscount.bind(cartApi),
3120
3316
  removeDiscount: cartApi.removeDiscount.bind(cartApi),
3121
- clear: cartApi.clearCart.bind(cartApi)
3317
+ clear: cartApi.clearCart.bind(cartApi),
3318
+ merge: cartApi.merge.bind(cartApi),
3319
+ mine: cartApi.mine.bind(cartApi)
3122
3320
  };
3123
3321
  this.orders = {
3124
3322
  checkout: orderApi.checkout.bind(orderApi),
@@ -3126,6 +3324,8 @@ var ServerCommerceClient = class {
3126
3324
  update: orderApi.updateOrder.bind(orderApi),
3127
3325
  updateTransaction: orderApi.updateTransaction.bind(orderApi),
3128
3326
  confirmPayment: orderApi.confirmPayment.bind(orderApi),
3327
+ confirmPaymentReturningOrder: orderApi.confirmPaymentReturningOrder.bind(orderApi),
3328
+ getByPaymentId: orderApi.getByPaymentId.bind(orderApi),
3129
3329
  cancelOrder: orderApi.cancelOrder.bind(orderApi),
3130
3330
  resolveCancelRefund: orderApi.resolveCancelRefund.bind(orderApi),
3131
3331
  createFulfillment: orderApi.createFulfillment.bind(orderApi),
@@ -3229,8 +3429,12 @@ function buildGuestCancelRequestBody(token, params) {
3229
3429
  }
3230
3430
  function buildRangeEndpoint(params) {
3231
3431
  const urlParams = new URLSearchParams();
3232
- urlParams.set("start", formatDateParam(params.start));
3233
- urlParams.set("end", formatDateParam(params.end));
3432
+ if (params.start !== void 0) {
3433
+ urlParams.set("start", formatDateParam(params.start));
3434
+ }
3435
+ if (params.end !== void 0) {
3436
+ urlParams.set("end", formatDateParam(params.end));
3437
+ }
3234
3438
  if (params.limit !== void 0) urlParams.set("limit", String(params.limit));
3235
3439
  if (params.page !== void 0) urlParams.set("page", String(params.page));
3236
3440
  appendValues(urlParams, "calendar", params.calendar);
@@ -3275,6 +3479,53 @@ var TenantIntrospectionApi = class extends BaseApi {
3275
3479
  }
3276
3480
  };
3277
3481
 
3482
+ // src/core/api/membership-api.ts
3483
+ var MembershipApi = class extends BaseApi {
3484
+ constructor(options) {
3485
+ super("MembershipApi", options);
3486
+ }
3487
+ /**
3488
+ * Record a delegated first-charge and activate a membership.
3489
+ * The storefront collected the payment; this endpoint deduplicates by
3490
+ * `subscribeIntentKey` and records the already-paid charge.
3491
+ *
3492
+ * `subscribeIntentKey` is used as the HTTP idempotency key so the call is
3493
+ * safely retryable.
3494
+ */
3495
+ subscribe(params) {
3496
+ const { subscribeIntentKey, ...body } = params;
3497
+ return this.request(
3498
+ MEMBERSHIP_ENDPOINTS.subscribe,
3499
+ body,
3500
+ idempotencyRequestOptions(subscribeIntentKey)
3501
+ );
3502
+ }
3503
+ /**
3504
+ * Cancel a membership by id.
3505
+ * `immediate=false` (default) sets `cancelAtPeriodEnd`; the customer retains
3506
+ * benefits until `currentPeriodEnd`. `immediate=true` cancels now and revokes
3507
+ * membership groups immediately.
3508
+ */
3509
+ cancel(params) {
3510
+ const { id, immediate } = params;
3511
+ return this.request(
3512
+ MEMBERSHIP_ENDPOINTS.cancel(id),
3513
+ immediate !== void 0 ? { immediate } : {}
3514
+ );
3515
+ }
3516
+ /**
3517
+ * Retrieve the authenticated customer's own membership view.
3518
+ * Never returns payment tokens or internal keys.
3519
+ */
3520
+ me() {
3521
+ return this.request(
3522
+ MEMBERSHIP_ENDPOINTS.me,
3523
+ void 0,
3524
+ { method: "GET" }
3525
+ );
3526
+ }
3527
+ };
3528
+
3278
3529
  // src/core/client/client.server.ts
3279
3530
  var ServerClient = class {
3280
3531
  constructor(options) {
@@ -3308,6 +3559,12 @@ var ServerClient = class {
3308
3559
  onRequestId
3309
3560
  };
3310
3561
  this.commerce = new ServerCommerceClient(serverOptions);
3562
+ const membershipApi = new MembershipApi(serverOptions);
3563
+ this.memberships = {
3564
+ subscribe: membershipApi.subscribe.bind(membershipApi),
3565
+ cancel: membershipApi.cancel.bind(membershipApi),
3566
+ me: membershipApi.me.bind(membershipApi)
3567
+ };
3311
3568
  const tenantIntrospectionApi = new TenantIntrospectionApi(serverOptions);
3312
3569
  this.tenant = {
3313
3570
  collectionSchema: tenantIntrospectionApi.collectionSchema.bind(