@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.js CHANGED
@@ -70,6 +70,26 @@ var TimeoutError = class extends SDKError {
70
70
  this.name = "TimeoutError";
71
71
  }
72
72
  };
73
+ var GoneError = class extends SDKError {
74
+ constructor(message = "The requested resource is no longer available.", details, userMessage, suggestion) {
75
+ super("GONE_ERROR", message, 410, details, userMessage, suggestion);
76
+ this.name = "GoneError";
77
+ }
78
+ };
79
+ var ServiceUnavailableError = class extends SDKError {
80
+ constructor(message = "Service temporarily unavailable.", retryAfter, details, userMessage, suggestion) {
81
+ super(
82
+ "SERVICE_UNAVAILABLE_ERROR",
83
+ message,
84
+ 503,
85
+ details,
86
+ userMessage,
87
+ suggestion
88
+ );
89
+ this.name = "ServiceUnavailableError";
90
+ this.retryAfter = retryAfter;
91
+ }
92
+ };
73
93
  var UsageLimitError = class extends SDKError {
74
94
  constructor(message, usage, details, userMessage, suggestion) {
75
95
  super("USAGE_LIMIT_ERROR", message, 429, details, userMessage, suggestion);
@@ -151,6 +171,14 @@ var createValidationError = (message, details, userMessage, suggestion, status)
151
171
  var createApiError = (message, status, details, userMessage, suggestion, requestId) => new ApiError(message, status, details, userMessage, suggestion, requestId);
152
172
  var createConfigError = (message, details, userMessage, suggestion) => new ConfigError(message, details, userMessage, suggestion);
153
173
  var createTimeoutError = (message, details, userMessage, suggestion) => new TimeoutError(message, details, userMessage, suggestion);
174
+ var createGoneError = (message, details, userMessage, suggestion) => new GoneError(message, details, userMessage, suggestion);
175
+ var createServiceUnavailableError = (message, retryAfter, details, userMessage, suggestion) => new ServiceUnavailableError(
176
+ message,
177
+ retryAfter,
178
+ details,
179
+ userMessage,
180
+ suggestion
181
+ );
154
182
  var createUsageLimitError = (message, usage, details, userMessage, suggestion) => new UsageLimitError(message, usage, details, userMessage, suggestion);
155
183
  var createAuthError = (message, details, userMessage, suggestion, requestId) => new AuthError(message, details, userMessage, suggestion, requestId);
156
184
  var createPermissionError = (message, details, userMessage, suggestion, requestId) => new PermissionError(message, details, userMessage, suggestion, requestId);
@@ -175,7 +203,7 @@ function requirePublishableKeyForSecret(apiName, publishableKey, secretKey) {
175
203
  return publishableKey ?? "";
176
204
  }
177
205
 
178
- // src/core/client/types.ts
206
+ // src/core/internal/utils/api-url.ts
179
207
  function resolveApiUrl(apiUrl) {
180
208
  if (apiUrl) {
181
209
  return apiUrl.replace(/\/$/, "");
@@ -192,7 +220,7 @@ function resolveApiUrl(apiUrl) {
192
220
  // src/core/internal/utils/http.ts
193
221
  var DEFAULT_TIMEOUT = 3e4;
194
222
  var STOREFRONT_BROWSER_TIMEOUT = 15e3;
195
- var DEFAULT_RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504];
223
+ var DEFAULT_RETRYABLE_STATUSES = [408, 500, 502, 503, 504];
196
224
  var NON_RETRYABLE_STATUSES = [400, 401, 403, 404, 409, 422];
197
225
  var SAFE_METHODS = ["GET", "HEAD", "OPTIONS"];
198
226
  var DEFAULT_MAX_RETRIES = 3;
@@ -309,7 +337,12 @@ function attachRequestId(err, id) {
309
337
  if (id) err.requestId = id;
310
338
  return err;
311
339
  }
312
- function createHttpStatusError(status, parsed, details, requestId) {
340
+ function parseRetryAfter(response) {
341
+ const raw = response.headers.get("Retry-After");
342
+ if (!raw) return void 0;
343
+ return parseInt(raw, 10) || void 0;
344
+ }
345
+ function mapResponseToError(status, parsed, details, requestId, retryAfter) {
313
346
  const errorDetails = {
314
347
  ...details,
315
348
  ...parsed.errors && { errors: parsed.errors },
@@ -372,6 +405,41 @@ function createHttpStatusError(status, parsed, details, requestId) {
372
405
  requestId
373
406
  );
374
407
  }
408
+ if (status === 410) {
409
+ return attachRequestId(
410
+ createGoneError(
411
+ parsed.errorMessage,
412
+ errorDetails,
413
+ parsed.userMessage,
414
+ suggestion
415
+ ),
416
+ requestId
417
+ );
418
+ }
419
+ if (status === 429) {
420
+ return attachRequestId(
421
+ createRateLimitError(
422
+ parsed.errorMessage,
423
+ retryAfter,
424
+ errorDetails,
425
+ parsed.userMessage,
426
+ suggestion
427
+ ),
428
+ requestId
429
+ );
430
+ }
431
+ if (status === 503) {
432
+ return attachRequestId(
433
+ createServiceUnavailableError(
434
+ parsed.errorMessage,
435
+ retryAfter,
436
+ errorDetails,
437
+ parsed.userMessage,
438
+ suggestion
439
+ ),
440
+ requestId
441
+ );
442
+ }
375
443
  return attachRequestId(
376
444
  createNetworkError(
377
445
  parsed.errorMessage,
@@ -490,26 +558,17 @@ async function httpFetch(url, options) {
490
558
  method: requestInit.method || "GET",
491
559
  attempt: attempt + 1
492
560
  };
493
- if (NON_RETRYABLE_STATUSES.includes(response.status)) {
494
- throw createHttpStatusError(
495
- response.status,
496
- parsed,
497
- details,
498
- requestId
499
- );
500
- }
501
- const error = attachRequestId(
502
- createNetworkError(
503
- parsed.errorMessage,
504
- response.status,
505
- details,
506
- parsed.userMessage,
507
- getErrorSuggestion(response.status)
508
- ),
509
- requestId
561
+ const retryAfter = parseRetryAfter(response);
562
+ const error = mapResponseToError(
563
+ response.status,
564
+ parsed,
565
+ details,
566
+ requestId,
567
+ retryAfter
510
568
  );
511
569
  const method2 = (requestInit.method || "GET").toUpperCase();
512
- if (attempt < retryConfig.maxRetries && SAFE_METHODS.includes(method2) && retryConfig.retryableStatuses.includes(response.status)) {
570
+ const isTerminal = error instanceof RateLimitError || error instanceof UsageLimitError;
571
+ if (attempt < retryConfig.maxRetries && SAFE_METHODS.includes(method2) && !isTerminal && !NON_RETRYABLE_STATUSES.includes(response.status) && retryConfig.retryableStatuses.includes(response.status)) {
513
572
  lastError = error;
514
573
  const retryDelay = retryConfig.retryDelay(attempt);
515
574
  debugLog(debug, "error", `Retrying in ${retryDelay}ms...`, error);
@@ -581,6 +640,64 @@ async function httpFetch(url, options) {
581
640
  throw lastError ?? new NetworkError("Request failed after retries");
582
641
  }
583
642
 
643
+ // src/core/api/endpoints.ts
644
+ var COMMERCE_ENDPOINTS = {
645
+ orders: {
646
+ create: "/api/orders/create",
647
+ update: "/api/orders/update",
648
+ confirmPayment: "/api/orders/confirm-payment",
649
+ byPayment: "/api/orders/by-payment",
650
+ cancel: "/api/orders/cancel",
651
+ resolveCancelRefund: "/api/orders/resolve-cancel-refund",
652
+ checkout: "/api/orders/checkout",
653
+ createFulfillment: "/api/orders/create-fulfillment",
654
+ updateFulfillment: "/api/orders/update-fulfillment"
655
+ },
656
+ transactions: {
657
+ update: "/api/transactions/update"
658
+ },
659
+ returns: {
660
+ create: "/api/returns/create",
661
+ update: "/api/returns/update",
662
+ returnRefund: "/api/returns/return-refund"
663
+ },
664
+ fulfillmentOrders: {
665
+ prepare: "/api/fulfillment-orders/prepare-fulfillment-order"
666
+ },
667
+ fulfillments: {
668
+ bulkImport: "/api/fulfillments/bulk-import"
669
+ },
670
+ carts: {
671
+ mine: "/api/carts/mine",
672
+ merge: "/api/carts/merge",
673
+ addItem: "/api/carts/add-item",
674
+ updateItem: "/api/carts/update-item",
675
+ removeItem: "/api/carts/remove-item",
676
+ applyDiscount: "/api/carts/apply-discount",
677
+ removeDiscount: "/api/carts/remove-discount",
678
+ clear: "/api/carts/clear"
679
+ },
680
+ products: {
681
+ stockCheck: "/api/products/stock-check",
682
+ stockSnapshot: "/api/products/stock",
683
+ listingGroups: "/api/products/listing-groups",
684
+ listingGroupsCatalog: "/api/products/listing-groups/catalog",
685
+ listingGroupsQuery: "/api/products/listing-groups/query",
686
+ listingGroupsQueryCatalog: "/api/products/listing-groups/query/catalog",
687
+ detail: "/api/products/detail",
688
+ detailCatalog: "/api/products/detail/catalog",
689
+ upsert: "/api/products/upsert"
690
+ }
691
+ };
692
+ var COMMERCE_ENDPOINT_PATHS = Object.values(
693
+ COMMERCE_ENDPOINTS
694
+ ).flatMap((group) => Object.values(group));
695
+ var MEMBERSHIP_ENDPOINTS = {
696
+ subscribe: "/api/memberships/subscribe",
697
+ cancel: (id) => `/api/memberships/${id}/cancel`,
698
+ me: "/api/memberships/me"
699
+ };
700
+
584
701
  // src/core/internal/utils/query-string.ts
585
702
  function productDetailQuery(params) {
586
703
  const search = new URLSearchParams();
@@ -589,7 +706,7 @@ function productDetailQuery(params) {
589
706
  } else {
590
707
  search.set("id", params.id);
591
708
  }
592
- return `/api/products/detail?${search}`;
709
+ return `${COMMERCE_ENDPOINTS.products.detail}?${search}`;
593
710
  }
594
711
  function productDetailCatalogQuery(params) {
595
712
  const search = new URLSearchParams();
@@ -598,23 +715,20 @@ function productDetailCatalogQuery(params) {
598
715
  } else {
599
716
  search.set("id", params.id);
600
717
  }
601
- return `/api/products/detail/catalog?${search}`;
718
+ return `${COMMERCE_ENDPOINTS.products.detailCatalog}?${search}`;
602
719
  }
603
720
  function listingGroupsQuery(params) {
604
- return `/api/products/listing-groups?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
721
+ return `${COMMERCE_ENDPOINTS.products.listingGroups}?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
605
722
  }
606
723
  function listingGroupsCatalogQuery(params) {
607
- return `/api/products/listing-groups/catalog?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
724
+ return `${COMMERCE_ENDPOINTS.products.listingGroupsCatalog}?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
608
725
  }
609
726
  function appendListingGroupsQuerySearchParams(search, options) {
610
727
  if (options?.page != null) search.set("page", String(options.page));
611
728
  if (options?.limit != null) search.set("limit", String(options.limit));
612
729
  if (options?.sort != null) {
613
730
  const sort = options.sort;
614
- search.set(
615
- "sort",
616
- Array.isArray(sort) ? sort.join(",") : sort
617
- );
731
+ search.set("sort", Array.isArray(sort) ? sort.join(",") : sort);
618
732
  }
619
733
  if (options?.where != null) {
620
734
  search.set("whereJson", JSON.stringify(options.where));
@@ -624,16 +738,16 @@ function listingGroupsQueryUrl(options) {
624
738
  const search = new URLSearchParams();
625
739
  appendListingGroupsQuerySearchParams(search, options);
626
740
  const query = search.toString();
627
- return `/api/products/listing-groups/query${query ? `?${query}` : ""}`;
741
+ return `${COMMERCE_ENDPOINTS.products.listingGroupsQuery}${query ? `?${query}` : ""}`;
628
742
  }
629
743
  function listingGroupsQueryCatalogUrl(options) {
630
744
  const search = new URLSearchParams();
631
745
  appendListingGroupsQuerySearchParams(search, options);
632
746
  const query = search.toString();
633
- return `/api/products/listing-groups/query/catalog${query ? `?${query}` : ""}`;
747
+ return `${COMMERCE_ENDPOINTS.products.listingGroupsQueryCatalog}${query ? `?${query}` : ""}`;
634
748
  }
635
749
  function stockSnapshotQuery(params) {
636
- return `/api/products/stock?variantIds=${params.variantIds.map(encodeURIComponent).join(",")}`;
750
+ return `${COMMERCE_ENDPOINTS.products.stockSnapshot}?variantIds=${params.variantIds.map(encodeURIComponent).join(",")}`;
637
751
  }
638
752
 
639
753
  // src/core/collection/http-client.ts
@@ -1582,39 +1696,78 @@ var ModerationApi = class extends BaseApi {
1582
1696
  // src/core/api/cart-api.ts
1583
1697
  var CartApi = class extends CustomerScopedApi {
1584
1698
  constructor(options) {
1585
- super("CartApi", options);
1699
+ super("CartApi", { ...options, requiresCredential: false });
1586
1700
  }
1587
1701
  async execute(endpoint, method, body) {
1588
1702
  return this.request(endpoint, { method, body });
1589
1703
  }
1590
- getCart(cartId) {
1704
+ /**
1705
+ * Create a cart and receive its `cartToken`. Store the token and pass it to
1706
+ * every subsequent cart operation.
1707
+ */
1708
+ createCart(params = {}) {
1709
+ return this.execute("/api/carts/create", "POST", params);
1710
+ }
1711
+ getCart(cartToken) {
1712
+ return this.execute("/api/carts/get", "POST", { cartToken });
1713
+ }
1714
+ merge(params) {
1591
1715
  return this.execute(
1592
- `/api/carts/${cartId}?depth=0&joins=false`,
1593
- "GET"
1716
+ COMMERCE_ENDPOINTS.carts.merge,
1717
+ "POST",
1718
+ params
1719
+ );
1720
+ }
1721
+ /**
1722
+ * Resolve the authenticated customer's active cart by JWT (no `cartToken`
1723
+ * required). Returns the cart and its capability handle, or both `null` when
1724
+ * the customer has no active cart. Requires a customer token.
1725
+ */
1726
+ mine() {
1727
+ return this.execute(
1728
+ COMMERCE_ENDPOINTS.carts.mine,
1729
+ "POST",
1730
+ {}
1594
1731
  );
1595
1732
  }
1596
1733
  addItem(params) {
1597
- return this.execute("/api/carts/add-item", "POST", params);
1734
+ return this.execute(
1735
+ COMMERCE_ENDPOINTS.carts.addItem,
1736
+ "POST",
1737
+ params
1738
+ );
1598
1739
  }
1599
1740
  updateItem(params) {
1600
- return this.execute("/api/carts/update-item", "POST", params);
1741
+ return this.execute(
1742
+ COMMERCE_ENDPOINTS.carts.updateItem,
1743
+ "POST",
1744
+ params
1745
+ );
1601
1746
  }
1602
1747
  removeItem(params) {
1603
1748
  return this.execute(
1604
- "/api/carts/remove-item",
1749
+ COMMERCE_ENDPOINTS.carts.removeItem,
1605
1750
  "POST",
1606
1751
  params
1607
1752
  );
1608
1753
  }
1609
1754
  applyDiscount(params) {
1610
- return this.execute("/api/carts/apply-discount", "POST", params);
1755
+ return this.execute(
1756
+ COMMERCE_ENDPOINTS.carts.applyDiscount,
1757
+ "POST",
1758
+ params
1759
+ );
1611
1760
  }
1612
1761
  removeDiscount(params) {
1613
- return this.execute("/api/carts/remove-discount", "POST", params);
1762
+ return this.execute(
1763
+ COMMERCE_ENDPOINTS.carts.removeDiscount,
1764
+ "POST",
1765
+ params
1766
+ );
1614
1767
  }
1615
1768
  clearCart(params) {
1616
1769
  return this.execute(
1617
- "/api/carts/clear",
1770
+ COMMERCE_ENDPOINTS.carts.clear,
1618
1771
  "POST",
1619
1772
  params
1620
1773
  );
@@ -2425,6 +2578,7 @@ function compareVariantOrder(a, b) {
2425
2578
  function getVariantAvailableForSale(variant) {
2426
2579
  if (variant.isActive === false) return false;
2427
2580
  if (variant.isUnlimited) return true;
2581
+ if (variant.inventoryPolicy === "continue") return true;
2428
2582
  return (variant.stock ?? 0) - (variant.reservedStock ?? 0) > 0;
2429
2583
  }
2430
2584
  function isVariantAvailableForSale(variant) {
@@ -2763,7 +2917,10 @@ var ProductApi = class extends BaseApi {
2763
2917
  * to remain available by the time an order is placed.
2764
2918
  */
2765
2919
  stockCheck(params) {
2766
- return this.request("/api/products/stock-check", params);
2920
+ return this.request(
2921
+ COMMERCE_ENDPOINTS.products.stockCheck,
2922
+ params
2923
+ );
2767
2924
  }
2768
2925
  stockSnapshot(params) {
2769
2926
  return this.request(
@@ -2840,7 +2997,7 @@ var ProductApi = class extends BaseApi {
2840
2997
  */
2841
2998
  upsert(params) {
2842
2999
  return this.request(
2843
- "/api/products/upsert",
3000
+ COMMERCE_ENDPOINTS.products.upsert,
2844
3001
  normalizeProductUpsertParams(params)
2845
3002
  );
2846
3003
  }
@@ -2890,26 +3047,61 @@ var OrderApi = class extends BaseApi {
2890
3047
  const { idempotencyKey } = params;
2891
3048
  const normalizedBody = normalizeCreateOrderBody(params);
2892
3049
  return this.request(
2893
- "/api/orders/create",
3050
+ COMMERCE_ENDPOINTS.orders.create,
2894
3051
  normalizedBody,
2895
3052
  idempotencyRequestOptions(idempotencyKey)
2896
3053
  );
2897
3054
  }
2898
3055
  updateOrder(params) {
2899
- return this.request("/api/orders/update", params);
3056
+ return this.request(COMMERCE_ENDPOINTS.orders.update, params);
2900
3057
  }
2901
3058
  updateTransaction(params) {
2902
- return this.request("/api/transactions/update", params);
3059
+ return this.request(
3060
+ COMMERCE_ENDPOINTS.transactions.update,
3061
+ params
3062
+ );
2903
3063
  }
2904
3064
  confirmPayment(params) {
2905
3065
  const { body, idempotencyKey } = splitIdempotencyKey(params);
2906
3066
  const headerKey = idempotencyKey ?? params.providerEventId;
2907
3067
  return this.request(
2908
- "/api/orders/confirm-payment",
3068
+ COMMERCE_ENDPOINTS.orders.confirmPayment,
2909
3069
  body,
2910
3070
  idempotencyRequestOptions(headerKey)
2911
3071
  );
2912
3072
  }
3073
+ /**
3074
+ * Resolve an order + its payment transaction by PG payment id. Replaces raw
3075
+ * `transactions.find({ where: { pgPaymentId } })` + a local file index in
3076
+ * storefronts. Server-only (sk01_) read of the full populated Order.
3077
+ */
3078
+ getByPaymentId(params) {
3079
+ const query = new URLSearchParams({
3080
+ pgProvider: params.pgProvider,
3081
+ pgPaymentId: params.pgPaymentId
3082
+ }).toString();
3083
+ return this.request(
3084
+ `${COMMERCE_ENDPOINTS.orders.byPayment}?${query}`,
3085
+ void 0,
3086
+ { method: "GET" }
3087
+ );
3088
+ }
3089
+ /**
3090
+ * Composed facade: confirm a provider payment, then resolve the
3091
+ * depth-populated order/transaction by the same payment id. `confirmPayment`'s
3092
+ * wire response carries only IDs (its contract is `.strict()`); this returns
3093
+ * the populated `Order` so storefronts stop reconstructing order state
3094
+ * locally. Two round trips by design — the alternative (widening the strict
3095
+ * confirm-payment wire contract to embed a full Order) is rejected.
3096
+ */
3097
+ async confirmPaymentReturningOrder(params) {
3098
+ const confirmation = await this.confirmPayment(params);
3099
+ const { order, transaction } = await this.getByPaymentId({
3100
+ pgProvider: params.pgProvider,
3101
+ pgPaymentId: params.pgPaymentId
3102
+ });
3103
+ return { ...confirmation, order, transaction };
3104
+ }
2913
3105
  cancelOrder(params) {
2914
3106
  const { idempotencyKey } = params;
2915
3107
  const body = {
@@ -2918,14 +3110,14 @@ var OrderApi = class extends BaseApi {
2918
3110
  reasonDetail: params.reasonDetail
2919
3111
  };
2920
3112
  return this.request(
2921
- "/api/orders/cancel",
3113
+ COMMERCE_ENDPOINTS.orders.cancel,
2922
3114
  body,
2923
3115
  idempotencyKey ? { headers: { "X-Idempotency-Key": idempotencyKey } } : void 0
2924
3116
  );
2925
3117
  }
2926
3118
  resolveCancelRefund(params) {
2927
3119
  return this.request(
2928
- "/api/orders/resolve-cancel-refund",
3120
+ COMMERCE_ENDPOINTS.orders.resolveCancelRefund,
2929
3121
  {
2930
3122
  orderNumber: params.orderNumber,
2931
3123
  idempotencyKey: params.idempotencyKey,
@@ -2946,7 +3138,7 @@ var OrderApi = class extends BaseApi {
2946
3138
  checkout(params) {
2947
3139
  const { body, idempotencyKey } = splitIdempotencyKey(params);
2948
3140
  return this.request(
2949
- "/api/orders/checkout",
3141
+ COMMERCE_ENDPOINTS.orders.checkout,
2950
3142
  body,
2951
3143
  idempotencyRequestOptions(idempotencyKey)
2952
3144
  );
@@ -2954,30 +3146,33 @@ var OrderApi = class extends BaseApi {
2954
3146
  createFulfillment(params) {
2955
3147
  const { body, idempotencyKey } = splitIdempotencyKey(params);
2956
3148
  return this.request(
2957
- "/api/orders/create-fulfillment",
3149
+ COMMERCE_ENDPOINTS.orders.createFulfillment,
2958
3150
  body,
2959
3151
  idempotencyRequestOptions(idempotencyKey)
2960
3152
  );
2961
3153
  }
2962
3154
  prepareFulfillmentOrder(params) {
2963
3155
  return this.request(
2964
- "/api/fulfillment-orders/prepare-fulfillment-order",
3156
+ COMMERCE_ENDPOINTS.fulfillmentOrders.prepare,
2965
3157
  params
2966
3158
  );
2967
3159
  }
2968
3160
  updateFulfillment(params) {
2969
- return this.request("/api/orders/update-fulfillment", params);
3161
+ return this.request(
3162
+ COMMERCE_ENDPOINTS.orders.updateFulfillment,
3163
+ params
3164
+ );
2970
3165
  }
2971
3166
  bulkImportFulfillments(params) {
2972
3167
  return this.request(
2973
- "/api/fulfillments/bulk-import",
3168
+ COMMERCE_ENDPOINTS.fulfillments.bulkImport,
2974
3169
  params
2975
3170
  );
2976
3171
  }
2977
3172
  returnWithRefund(params) {
2978
3173
  const { body, idempotencyKey } = splitIdempotencyKey(params);
2979
3174
  return this.request(
2980
- "/api/returns/return-refund",
3175
+ COMMERCE_ENDPOINTS.returns.returnRefund,
2981
3176
  body,
2982
3177
  idempotencyRequestOptions(idempotencyKey)
2983
3178
  );
@@ -2985,13 +3180,13 @@ var OrderApi = class extends BaseApi {
2985
3180
  createReturn(params) {
2986
3181
  const { body, idempotencyKey } = splitIdempotencyKey(params);
2987
3182
  return this.request(
2988
- "/api/returns/create",
3183
+ COMMERCE_ENDPOINTS.returns.create,
2989
3184
  body,
2990
3185
  idempotencyRequestOptions(idempotencyKey)
2991
3186
  );
2992
3187
  }
2993
3188
  updateReturn(params) {
2994
- return this.request("/api/returns/update", params);
3189
+ return this.request(COMMERCE_ENDPOINTS.returns.update, params);
2995
3190
  }
2996
3191
  };
2997
3192
 
@@ -3077,13 +3272,16 @@ var ServerCommerceClient = class {
3077
3272
  upsert: productApi.upsert.bind(productApi)
3078
3273
  };
3079
3274
  this.cart = {
3275
+ create: cartApi.createCart.bind(cartApi),
3080
3276
  get: cartApi.getCart.bind(cartApi),
3081
3277
  addItem: cartApi.addItem.bind(cartApi),
3082
3278
  updateItem: cartApi.updateItem.bind(cartApi),
3083
3279
  removeItem: cartApi.removeItem.bind(cartApi),
3084
3280
  applyDiscount: cartApi.applyDiscount.bind(cartApi),
3085
3281
  removeDiscount: cartApi.removeDiscount.bind(cartApi),
3086
- clear: cartApi.clearCart.bind(cartApi)
3282
+ clear: cartApi.clearCart.bind(cartApi),
3283
+ merge: cartApi.merge.bind(cartApi),
3284
+ mine: cartApi.mine.bind(cartApi)
3087
3285
  };
3088
3286
  this.orders = {
3089
3287
  checkout: orderApi.checkout.bind(orderApi),
@@ -3091,6 +3289,8 @@ var ServerCommerceClient = class {
3091
3289
  update: orderApi.updateOrder.bind(orderApi),
3092
3290
  updateTransaction: orderApi.updateTransaction.bind(orderApi),
3093
3291
  confirmPayment: orderApi.confirmPayment.bind(orderApi),
3292
+ confirmPaymentReturningOrder: orderApi.confirmPaymentReturningOrder.bind(orderApi),
3293
+ getByPaymentId: orderApi.getByPaymentId.bind(orderApi),
3094
3294
  cancelOrder: orderApi.cancelOrder.bind(orderApi),
3095
3295
  resolveCancelRefund: orderApi.resolveCancelRefund.bind(orderApi),
3096
3296
  createFulfillment: orderApi.createFulfillment.bind(orderApi),
@@ -3194,8 +3394,12 @@ function buildGuestCancelRequestBody(token, params) {
3194
3394
  }
3195
3395
  function buildRangeEndpoint(params) {
3196
3396
  const urlParams = new URLSearchParams();
3197
- urlParams.set("start", formatDateParam(params.start));
3198
- urlParams.set("end", formatDateParam(params.end));
3397
+ if (params.start !== void 0) {
3398
+ urlParams.set("start", formatDateParam(params.start));
3399
+ }
3400
+ if (params.end !== void 0) {
3401
+ urlParams.set("end", formatDateParam(params.end));
3402
+ }
3199
3403
  if (params.limit !== void 0) urlParams.set("limit", String(params.limit));
3200
3404
  if (params.page !== void 0) urlParams.set("page", String(params.page));
3201
3405
  appendValues(urlParams, "calendar", params.calendar);
@@ -3240,6 +3444,53 @@ var TenantIntrospectionApi = class extends BaseApi {
3240
3444
  }
3241
3445
  };
3242
3446
 
3447
+ // src/core/api/membership-api.ts
3448
+ var MembershipApi = class extends BaseApi {
3449
+ constructor(options) {
3450
+ super("MembershipApi", options);
3451
+ }
3452
+ /**
3453
+ * Record a delegated first-charge and activate a membership.
3454
+ * The storefront collected the payment; this endpoint deduplicates by
3455
+ * `subscribeIntentKey` and records the already-paid charge.
3456
+ *
3457
+ * `subscribeIntentKey` is used as the HTTP idempotency key so the call is
3458
+ * safely retryable.
3459
+ */
3460
+ subscribe(params) {
3461
+ const { subscribeIntentKey, ...body } = params;
3462
+ return this.request(
3463
+ MEMBERSHIP_ENDPOINTS.subscribe,
3464
+ body,
3465
+ idempotencyRequestOptions(subscribeIntentKey)
3466
+ );
3467
+ }
3468
+ /**
3469
+ * Cancel a membership by id.
3470
+ * `immediate=false` (default) sets `cancelAtPeriodEnd`; the customer retains
3471
+ * benefits until `currentPeriodEnd`. `immediate=true` cancels now and revokes
3472
+ * membership groups immediately.
3473
+ */
3474
+ cancel(params) {
3475
+ const { id, immediate } = params;
3476
+ return this.request(
3477
+ MEMBERSHIP_ENDPOINTS.cancel(id),
3478
+ immediate !== void 0 ? { immediate } : {}
3479
+ );
3480
+ }
3481
+ /**
3482
+ * Retrieve the authenticated customer's own membership view.
3483
+ * Never returns payment tokens or internal keys.
3484
+ */
3485
+ me() {
3486
+ return this.request(
3487
+ MEMBERSHIP_ENDPOINTS.me,
3488
+ void 0,
3489
+ { method: "GET" }
3490
+ );
3491
+ }
3492
+ };
3493
+
3243
3494
  // src/core/client/client.server.ts
3244
3495
  var ServerClient = class {
3245
3496
  constructor(options) {
@@ -3273,6 +3524,12 @@ var ServerClient = class {
3273
3524
  onRequestId
3274
3525
  };
3275
3526
  this.commerce = new ServerCommerceClient(serverOptions);
3527
+ const membershipApi = new MembershipApi(serverOptions);
3528
+ this.memberships = {
3529
+ subscribe: membershipApi.subscribe.bind(membershipApi),
3530
+ cancel: membershipApi.cancel.bind(membershipApi),
3531
+ me: membershipApi.me.bind(membershipApi)
3532
+ };
3276
3533
  const tenantIntrospectionApi = new TenantIntrospectionApi(serverOptions);
3277
3534
  this.tenant = {
3278
3535
  collectionSchema: tenantIntrospectionApi.collectionSchema.bind(