@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
@@ -1,6 +1,6 @@
1
- import { P as PublicCollection, S as ServerCollection } from './const-HwdntWtG.js';
2
- import { C as CollectionType, P as PublicProduct } from './types-BMI3M0nb.js';
3
- import { O as Order, m as Transaction, n as Fulfillment, R as Return } from './payload-types-CqJOgON7.js';
1
+ import { P as PublicCollection, S as ServerCollection } from './const-BBynifk0.cjs';
2
+ import { C as CollectionType, P as PublicProduct } from './types-B1ngKbWI.cjs';
3
+ import { O as Order, m as Transaction, n as Fulfillment, R as Return } from './payload-types-DLxkB7Mv.cjs';
4
4
 
5
5
  interface CustomerScopedApiOptions {
6
6
  publishableKey?: string;
@@ -402,6 +402,14 @@ type CustomerSnapshot = {
402
402
  email: string;
403
403
  phone?: string;
404
404
  };
405
+ type CheckoutShippingAddress = {
406
+ recipientName: string;
407
+ phone: string;
408
+ postalCode: string;
409
+ address: string;
410
+ detailAddress: string;
411
+ deliveryMessage?: string;
412
+ };
405
413
  type PublicOrderReference = string | {
406
414
  id?: string | number | null;
407
415
  title?: string | null;
@@ -449,6 +457,8 @@ type PublicOrder = {
449
457
  discountAmount?: number | null;
450
458
  taxAmount?: number | null;
451
459
  refundedAmount?: number | null;
460
+ /** Net order total after refunds (`totalAmount - refundedAmount`, clamped at 0). */
461
+ currentTotalAmount?: number | null;
452
462
  currency?: string | null;
453
463
  customerNote?: string | null;
454
464
  createdAt?: string | null;
@@ -526,7 +536,7 @@ type CreateOrderBodyBase = {
526
536
  orderNumber: string;
527
537
  customer?: string;
528
538
  customerSnapshot: CustomerSnapshot;
529
- shippingAddress: Order['shippingAddress'];
539
+ shippingAddress?: Order['shippingAddress'];
530
540
  totalAmount: number;
531
541
  shippingAmount?: number;
532
542
  pgPaymentId?: string;
@@ -569,6 +579,31 @@ type ConfirmPaymentResponse = {
569
579
  status: 'paid';
570
580
  alreadyConfirmed?: boolean;
571
581
  };
582
+ type GetOrderByPaymentIdParams = {
583
+ /** Payment provider slug, e.g. `toss`, `portone`. */
584
+ pgProvider: string;
585
+ /** Provider payment identifier stored on the payment transaction. */
586
+ pgPaymentId: string;
587
+ };
588
+ /**
589
+ * Depth-populated order + its payment transaction, resolved by PG payment id.
590
+ * `transaction` is `null` only in transient race windows; the server returns a
591
+ * `404` when no payment transaction matches the id, so a resolved order always
592
+ * comes with its transaction in practice.
593
+ */
594
+ type OrderByPaymentResult = {
595
+ order: Order;
596
+ transaction: Transaction | null;
597
+ };
598
+ /**
599
+ * Result of {@link OrderApi.confirmPaymentReturningOrder}: the raw
600
+ * `confirmPayment` confirmation plus the depth-populated order/transaction
601
+ * resolved by the same payment id.
602
+ */
603
+ type ConfirmPaymentWithOrderResult = ConfirmPaymentResponse & {
604
+ order: Order;
605
+ transaction: Transaction | null;
606
+ };
572
607
  type CancelReasonCode = 'customer' | 'inventory' | 'fraud' | 'declined' | 'staff' | 'other';
573
608
  type CancelOrderStatus = 'pending' | 'paid' | 'canceled' | 'refunded' | 'preparing' | 'shipped' | 'delivered' | 'confirmed' | 'return_requested' | 'return_processing' | 'returned';
574
609
  type CancelOrderReconciliationStatus = Exclude<CancelOrderStatus, 'pending' | 'canceled'>;
@@ -690,14 +725,22 @@ type ReturnWithRefundParams = WithIdempotencyKey<{
690
725
  }>;
691
726
  type CheckoutParams = WithIdempotencyKey<{
692
727
  cartId: string;
728
+ cartToken?: string;
693
729
  orderNumber: string;
694
730
  customerSnapshot: CustomerSnapshot;
731
+ shippingAddress?: CheckoutShippingAddress;
695
732
  pgPaymentId?: string;
696
733
  discountCode?: string;
697
734
  }>;
698
735
  type CreateFulfillmentParams = WithIdempotencyKey<{
699
736
  orderNumber: string;
700
737
  fulfillmentOrderId?: string | number;
738
+ /**
739
+ * Carrier and tracking number are a both-or-neither pair. Send both for a
740
+ * carrier-facing shipment, or neither for a non-carrier-facing manual handoff
741
+ * (tracking can be added later via `updateFulfillment`). A half-pair is
742
+ * rejected server-side with `400 validation_failed`.
743
+ */
701
744
  carrier?: string;
702
745
  trackingNumber?: string;
703
746
  items?: Array<{
@@ -758,6 +801,21 @@ declare class OrderApi extends BaseApi {
758
801
  updateOrder(params: UpdateOrderParams): Promise<Order>;
759
802
  updateTransaction(params: UpdateTransactionParams): Promise<Transaction>;
760
803
  confirmPayment(params: ConfirmPaymentParams): Promise<ConfirmPaymentResponse>;
804
+ /**
805
+ * Resolve an order + its payment transaction by PG payment id. Replaces raw
806
+ * `transactions.find({ where: { pgPaymentId } })` + a local file index in
807
+ * storefronts. Server-only (sk01_) read of the full populated Order.
808
+ */
809
+ getByPaymentId(params: GetOrderByPaymentIdParams): Promise<OrderByPaymentResult>;
810
+ /**
811
+ * Composed facade: confirm a provider payment, then resolve the
812
+ * depth-populated order/transaction by the same payment id. `confirmPayment`'s
813
+ * wire response carries only IDs (its contract is `.strict()`); this returns
814
+ * the populated `Order` so storefronts stop reconstructing order state
815
+ * locally. Two round trips by design — the alternative (widening the strict
816
+ * confirm-payment wire contract to embed a full Order) is rejected.
817
+ */
818
+ confirmPaymentReturningOrder(params: ConfirmPaymentParams): Promise<ConfirmPaymentWithOrderResult>;
761
819
  cancelOrder(params: CancelOrderParams): Promise<CancelOrderResponse>;
762
820
  resolveCancelRefund(params: ResolveCancelRefundParams): Promise<ResolveCancelRefundResponse>;
763
821
  /**
@@ -933,29 +991,35 @@ interface CartApiOptions {
933
991
  onUnauthorized?: () => Promise<string | null>;
934
992
  onRequestId?: (id: string | null) => void;
935
993
  }
994
+ type CreateCartParams = Record<string, never>;
936
995
  type AddItemParams = {
937
- cartId: string;
996
+ cartToken: string;
938
997
  product: string;
939
998
  variant: string;
940
- option: string;
999
+ option?: string;
941
1000
  quantity: number;
942
1001
  };
943
1002
  type UpdateItemParams = {
1003
+ cartToken: string;
944
1004
  cartItemId: string;
945
1005
  quantity: number;
946
1006
  };
947
1007
  type RemoveItemParams = {
1008
+ cartToken: string;
948
1009
  cartItemId: string;
949
1010
  };
950
1011
  type ApplyDiscountParams = {
951
- cartId: string;
1012
+ cartToken: string;
952
1013
  discountCode: string;
953
1014
  };
954
1015
  type RemoveDiscountParams = {
955
- cartId: string;
1016
+ cartToken: string;
956
1017
  };
957
1018
  type ClearCartParams = {
958
- cartId: string;
1019
+ cartToken: string;
1020
+ };
1021
+ type CartMergeParams = {
1022
+ guestCartToken: string;
959
1023
  };
960
1024
  type PublicCartReference = string | {
961
1025
  id?: string | number | null;
@@ -978,6 +1042,7 @@ type PublicCartItem = {
978
1042
  discountAllocation?: number | null;
979
1043
  discountedUnitPrice?: number | null;
980
1044
  discountedTotalPrice?: number | null;
1045
+ requiresShipping?: boolean | null;
981
1046
  createdAt?: string | null;
982
1047
  updatedAt?: string | null;
983
1048
  };
@@ -1013,10 +1078,51 @@ type PublicCart = {
1013
1078
  };
1014
1079
  items?: PublicCartItem[];
1015
1080
  };
1081
+ /**
1082
+ * Create response: the only place the server returns the `cartToken`. Persist
1083
+ * it (cookie/storage) and pass it as the handle on every later cart call.
1084
+ */
1085
+ type CreatedCart = PublicCart & {
1086
+ cartToken?: string;
1087
+ };
1088
+ type CartMergeResult = {
1089
+ cart: PublicCart;
1090
+ merged: boolean;
1091
+ claimed: boolean;
1092
+ guestCartId: string | number;
1093
+ customerCartId: string | number;
1094
+ /**
1095
+ * The resolved customer cart's capability handle. Persist it after a merge so
1096
+ * the storefront can keep operating the cart when a union moved lines into a
1097
+ * different cart row. `null` only if the resolved cart has no token.
1098
+ */
1099
+ cartToken: string | null;
1100
+ };
1101
+ /**
1102
+ * The authenticated customer's active cart resolved by JWT. `cartToken` is the
1103
+ * capability handle returned to the owner; persist it for later token-keyed
1104
+ * mutations. Both fields are `null` when the customer has no active cart.
1105
+ */
1106
+ type CartMineResult = {
1107
+ cart: PublicCart | null;
1108
+ cartToken: string | null;
1109
+ };
1016
1110
  declare class CartApi extends CustomerScopedApi {
1017
1111
  constructor(options: CartApiOptions);
1018
1112
  private execute;
1019
- getCart(cartId: string): Promise<PublicCart>;
1113
+ /**
1114
+ * Create a cart and receive its `cartToken`. Store the token and pass it to
1115
+ * every subsequent cart operation.
1116
+ */
1117
+ createCart(params?: CreateCartParams): Promise<CreatedCart>;
1118
+ getCart(cartToken: string): Promise<PublicCart>;
1119
+ merge(params: CartMergeParams): Promise<CartMergeResult>;
1120
+ /**
1121
+ * Resolve the authenticated customer's active cart by JWT (no `cartToken`
1122
+ * required). Returns the cart and its capability handle, or both `null` when
1123
+ * the customer has no active cart. Requires a customer token.
1124
+ */
1125
+ mine(): Promise<CartMineResult>;
1020
1126
  addItem(params: AddItemParams): Promise<PublicCartItem>;
1021
1127
  updateItem(params: UpdateItemParams): Promise<PublicCartItem>;
1022
1128
  removeItem(params: RemoveItemParams): Promise<{
@@ -1121,6 +1227,7 @@ interface ProductVariantShape {
1121
1227
  stock?: number | null;
1122
1228
  reservedStock?: number | null;
1123
1229
  isUnlimited?: boolean | null;
1230
+ inventoryPolicy?: ('deny' | 'continue') | null;
1124
1231
  isActive?: boolean | null;
1125
1232
  thumbnail?: MediaValue;
1126
1233
  images?: MediaValue[] | null;
@@ -1496,6 +1603,7 @@ type VariantInput = {
1496
1603
  compareAtPrice?: number | null;
1497
1604
  stock?: number;
1498
1605
  isUnlimited?: boolean;
1606
+ inventoryPolicy?: 'deny' | 'continue';
1499
1607
  weight?: number | null;
1500
1608
  requiresShipping?: boolean;
1501
1609
  barcode?: string | null;
@@ -1523,6 +1631,10 @@ type ProductFieldsInput = {
1523
1631
  publishedAt?: string | null;
1524
1632
  categories?: string[];
1525
1633
  tags?: string[];
1634
+ seo?: {
1635
+ title?: string | null;
1636
+ description?: string | null;
1637
+ } | null;
1526
1638
  metadata?: unknown;
1527
1639
  };
1528
1640
  type ProductUpsertGraphFields = {
@@ -1703,6 +1815,7 @@ interface ProductDetailVariant {
1703
1815
  stock: number;
1704
1816
  reservedStock: number;
1705
1817
  isUnlimited: boolean;
1818
+ inventoryPolicy?: ('deny' | 'continue') | null;
1706
1819
  isActive: boolean;
1707
1820
  thumbnail?: ProductDetailMedia | null;
1708
1821
  images?: ProductDetailMedia[];
@@ -1786,6 +1899,11 @@ interface StockSnapshotItem {
1786
1899
  availableStock: number;
1787
1900
  availableForSale: boolean;
1788
1901
  isUnlimited: boolean;
1902
+ /**
1903
+ * Backorder policy for tracked variants (Shopify `inventoryPolicy`).
1904
+ * `continue` means the variant stays purchasable past available stock.
1905
+ */
1906
+ inventoryPolicy?: ('deny' | 'continue') | null;
1789
1907
  }
1790
1908
  interface StockSnapshotResponse {
1791
1909
  snapshots: StockSnapshotItem[];
@@ -1904,6 +2022,7 @@ type ValidateDiscountParams = {
1904
2022
  code: string;
1905
2023
  orderAmount: number;
1906
2024
  };
2025
+ type DiscountErrorReasonCode = 'discount_code_not_found' | 'discount_not_started' | 'discount_expired' | 'discount_usage_limit' | 'discount_per_customer_limit' | 'discount_customer_required' | 'discount_first_order_only' | 'discount_customer_not_eligible' | 'discount_customer_excluded' | 'discount_items_required' | 'discount_product_not_eligible' | 'discount_product_excluded' | 'discount_min_order_amount';
1907
2026
  type ValidateDiscountResult = {
1908
2027
  valid: boolean;
1909
2028
  code: string;
@@ -1911,6 +2030,7 @@ type ValidateDiscountResult = {
1911
2030
  discountAmount: number;
1912
2031
  freeShipping?: boolean;
1913
2032
  reason?: string;
2033
+ reasonCode?: DiscountErrorReasonCode;
1914
2034
  };
1915
2035
  declare class DiscountApi extends BaseApi {
1916
2036
  constructor(options: DiscountApiOptions);
@@ -1958,7 +2078,8 @@ declare class CommerceClient {
1958
2078
  detailCatalog: (params: ProductDetailParams) => Promise<ProductDetailCatalogResult>;
1959
2079
  };
1960
2080
  readonly cart: {
1961
- get: (cartId: string) => Promise<PublicCart>;
2081
+ create: (params?: CreateCartParams) => Promise<CreatedCart>;
2082
+ get: (cartToken: string) => Promise<PublicCart>;
1962
2083
  addItem: (params: AddItemParams) => Promise<PublicCartItem>;
1963
2084
  updateItem: (params: UpdateItemParams) => Promise<PublicCartItem>;
1964
2085
  removeItem: (params: RemoveItemParams) => Promise<{
@@ -1969,6 +2090,17 @@ declare class CommerceClient {
1969
2090
  clear: (params: ClearCartParams) => Promise<{
1970
2091
  success: boolean;
1971
2092
  }>;
2093
+ /**
2094
+ * Union/claim a pre-login guest cart into the authenticated customer's cart
2095
+ * (customer JWT required). Returns the resolved customer cart's `cartToken`
2096
+ * so the caller can persist it and keep operating the cart.
2097
+ */
2098
+ merge: (params: CartMergeParams) => Promise<CartMergeResult>;
2099
+ /**
2100
+ * Load the authenticated customer's active cart by JWT (no `cartToken`
2101
+ * needed). `cart`/`cartToken` are both `null` when there is no active cart.
2102
+ */
2103
+ mine: () => Promise<CartMineResult>;
1972
2104
  };
1973
2105
  readonly orders: {
1974
2106
  checkout: (params: CheckoutParams) => Promise<PublicOrder>;
@@ -2082,7 +2214,8 @@ declare class ServerCommerceClient {
2082
2214
  upsert: (params: ProductUpsertParams) => Promise<ProductUpsertResponse>;
2083
2215
  };
2084
2216
  readonly cart: {
2085
- get: (cartId: string) => Promise<PublicCart>;
2217
+ create: (params?: CreateCartParams) => Promise<CreatedCart>;
2218
+ get: (cartToken: string) => Promise<PublicCart>;
2086
2219
  addItem: (params: AddItemParams) => Promise<PublicCartItem>;
2087
2220
  updateItem: (params: UpdateItemParams) => Promise<PublicCartItem>;
2088
2221
  removeItem: (params: RemoveItemParams) => Promise<{
@@ -2093,6 +2226,13 @@ declare class ServerCommerceClient {
2093
2226
  clear: (params: ClearCartParams) => Promise<{
2094
2227
  success: boolean;
2095
2228
  }>;
2229
+ /**
2230
+ * Union/claim a guest cart into a customer's cart. Customer-bound resolution
2231
+ * requires a customer JWT; a secret-key caller has no customer session.
2232
+ */
2233
+ merge: (params: CartMergeParams) => Promise<CartMergeResult>;
2234
+ /** Load the authenticated customer's active cart by JWT. */
2235
+ mine: () => Promise<CartMineResult>;
2096
2236
  };
2097
2237
  readonly orders: {
2098
2238
  checkout: (params: CheckoutParams) => Promise<PublicOrder>;
@@ -2100,6 +2240,8 @@ declare class ServerCommerceClient {
2100
2240
  update: (params: UpdateOrderParams) => Promise<Order>;
2101
2241
  updateTransaction: (params: UpdateTransactionParams) => Promise<Transaction>;
2102
2242
  confirmPayment: (params: ConfirmPaymentParams) => Promise<ConfirmPaymentResponse>;
2243
+ confirmPaymentReturningOrder: (params: ConfirmPaymentParams) => Promise<ConfirmPaymentWithOrderResult>;
2244
+ getByPaymentId: (params: GetOrderByPaymentIdParams) => Promise<OrderByPaymentResult>;
2103
2245
  cancelOrder: (params: CancelOrderParams) => Promise<CancelOrderResponse>;
2104
2246
  resolveCancelRefund: (params: ResolveCancelRefundParams) => Promise<ResolveCancelRefundResponse>;
2105
2247
  createFulfillment: (params: CreateFulfillmentParams) => Promise<Fulfillment>;
@@ -2140,8 +2282,8 @@ interface EventsClientOptions {
2140
2282
  }
2141
2283
  type EventsDateParam = string | Date;
2142
2284
  interface EventsRangeParams {
2143
- start: EventsDateParam;
2144
- end: EventsDateParam;
2285
+ start?: EventsDateParam;
2286
+ end?: EventsDateParam;
2145
2287
  limit?: number;
2146
2288
  page?: number;
2147
2289
  calendar?: string;
@@ -2330,6 +2472,9 @@ interface TenantFeatureProgressResponse {
2330
2472
  planBlocked: string[];
2331
2473
  closureAdded: string[];
2332
2474
  };
2475
+ config: {
2476
+ fulfillmentMode: 'shipping' | 'none';
2477
+ };
2333
2478
  summary: {
2334
2479
  complete: number;
2335
2480
  total: number;
@@ -2382,6 +2527,67 @@ declare class TenantIntrospectionApi extends BaseApi implements TenantIntrospect
2382
2527
  featureProgress(params: TenantFeatureProgressInput): Promise<TenantFeatureProgressResponse>;
2383
2528
  }
2384
2529
 
2530
+ /**
2531
+ * SDK-local hand-declarations of the membership wire contract types.
2532
+ *
2533
+ * The public SDK must keep these types local because the canonical membership
2534
+ * contract package is private to the workspace. These public types are
2535
+ * structurally checked by membership contract-parity type tests.
2536
+ */
2537
+ type MembershipStatus = 'incomplete' | 'trialing' | 'active' | 'past_due' | 'cancelled' | 'expired';
2538
+ /**
2539
+ * Parameters for the subscribe endpoint (delegated charge model).
2540
+ * The storefront already collected the first payment; this records it and
2541
+ * activates the membership.
2542
+ */
2543
+ type SubscribeMembershipParams = {
2544
+ planId: string;
2545
+ /** Stable client-generated key used as the deduplication key for this subscription intent. */
2546
+ subscribeIntentKey: string;
2547
+ pgPaymentId: string;
2548
+ amount: number;
2549
+ currency: string;
2550
+ customerRef?: string;
2551
+ card?: {
2552
+ last4?: string;
2553
+ brand?: string;
2554
+ };
2555
+ };
2556
+ type SubscribeMembershipResponse = {
2557
+ membershipId: string;
2558
+ status: MembershipStatus;
2559
+ };
2560
+ /**
2561
+ * Parameters for cancelling a membership.
2562
+ * `immediate=false` (default) sets `cancelAtPeriodEnd`; benefits persist to
2563
+ * the last paid period. `immediate=true` cancels immediately and revokes groups.
2564
+ */
2565
+ type CancelMembershipParams = {
2566
+ id: string;
2567
+ immediate?: boolean;
2568
+ };
2569
+ type CancelMembershipResponse = {
2570
+ status: MembershipStatus;
2571
+ };
2572
+ /**
2573
+ * The customer's own subscription view. Never includes a payment token or
2574
+ * subscribeIntentKey.
2575
+ */
2576
+ type CustomerMembershipView = {
2577
+ id: string;
2578
+ plan: string;
2579
+ status: MembershipStatus;
2580
+ currentPeriodEnd: string;
2581
+ nextBillingAt: string | null;
2582
+ cancelAtPeriodEnd: boolean;
2583
+ amount: number;
2584
+ currency: string;
2585
+ card?: {
2586
+ last4?: string;
2587
+ brand?: string;
2588
+ } | null;
2589
+ };
2590
+
2385
2591
  interface ClientConfig {
2386
2592
  publishableKey: string;
2387
2593
  /** API base URL for staging, self-hosted, preview, or proxy deployments. */
@@ -2575,6 +2781,9 @@ interface RootClient {
2575
2781
  events?: EventsClient;
2576
2782
  customer: CustomerNamespace;
2577
2783
  collections: RootCollectionClient;
2784
+ memberships: {
2785
+ me: () => Promise<CustomerMembershipView | null>;
2786
+ };
2578
2787
  lastRequestId: string | null;
2579
2788
  getState(): ClientState;
2580
2789
  getConfig(): ClientConfig;
@@ -2582,6 +2791,11 @@ interface RootClient {
2582
2791
  interface RootServerClient {
2583
2792
  commerce: ServerCommerceClient;
2584
2793
  tenant: TenantIntrospectionClient;
2794
+ memberships: {
2795
+ subscribe: (params: SubscribeMembershipParams) => Promise<SubscribeMembershipResponse>;
2796
+ cancel: (params: CancelMembershipParams) => Promise<CancelMembershipResponse>;
2797
+ me: () => Promise<CustomerMembershipView | null>;
2798
+ };
2585
2799
  /** Set on {@link createServerClient} return values; optional for structural mocks. */
2586
2800
  events?: EventsClient;
2587
2801
  community: CommunityClient & {
@@ -2608,4 +2822,4 @@ type DeepPartial<T> = {
2608
2822
  };
2609
2823
  type ExtractArrayType<T> = T extends (infer U)[] ? U : never;
2610
2824
 
2611
- export { type CollectionFieldSchema as $, type AddItemParams as A, type RootReadOnlyQueryBuilder as B, CommerceClient as C, type DebugConfig as D, EventsClient as E, type StorefrontContentListOptions as F, type StorefrontContentReference as G, type StorefrontGalleryItem as H, type StorefrontGalleryItemsListOptions as I, type StorefrontGalleryItemsSort as J, type StorefrontLink as K, type StorefrontLinksListOptions as L, type StorefrontLinksSort as M, BaseApi as N, type ServerApiOptions as O, type PayloadFindResponse as P, ServerCommerceClient as Q, type RemoveDiscountParams as R, type Sort as S, type TenantIntrospectionClient as T, type UpdateItemParams as U, type BanCustomerParams as V, type Where as W, type CommunityBan as X, type UnbanCustomerParams as Y, type ClientServerConfig as Z, type RootServerClientWithEvents as _, CommunityClient as a, type CalculateShippingParams as a$, type CollectionSchemaResponse as a0, type EventGuestCancelParams as a1, type EventGuestRegistration as a2, type EventGuestRegistrationResponse as a3, type EventRegistrationAnswerInput as a4, type EventRegistrationAttendeeInput as a5, type EventRegistrationPublic as a6, type EventRegistrationRegisterParams as a7, type EventRegistrationRegisterResponse as a8, type EventsCalendarItem as a9, type CustomerProfile as aA, type CustomerAuthResponse as aB, type CustomerLoginData as aC, type CustomerRegisterResponse as aD, type CustomerRegisterData as aE, type CustomerRefreshResponse as aF, type UpdateProfileData as aG, type ProductListingPageBaseParams as aH, type ProductListingPageParams as aI, type ProductDetailParams as aJ, type ProductDetailResult as aK, type ProductListingPageCatalogParams as aL, type ProductListingPageResult as aM, type ProductListingGroupsCatalogItem as aN, type ProductListingPageFullParams as aO, type ProductListingGroupsItem as aP, type ProductDetail as aQ, type ProductDetailCatalog as aR, type StockSnapshotResponse as aS, type ProductSelectionMediaSource as aT, type ProductDisplayMediaSource as aU, type ResolveProductSelectionMediaInput as aV, type ResolveProductSelectionMediaResult as aW, type ProductSelectionMediaPointer as aX, type RootClientWithEvents as aY, type BulkImportFulfillmentsParams as aZ, type BulkImportFulfillmentsResponse as a_, type EventsClientOptions as aa, type EventsDateParam as ab, type EventsExternalSource as ac, type EventsLocation as ad, type EventsOccurrenceLocation as ae, type EventsRangeEvent as af, type EventsRangeOccurrence as ag, type EventsRangeParams as ah, type EventsRangeResponse as ai, type EventsTaxonomyItem as aj, ModerationApi as ak, type RootServerClient as al, type TenantFeatureProgressEvidenceValue as am, type TenantFeatureProgressFeature as an, type TenantFeatureProgressGroup as ao, type TenantFeatureProgressInput as ap, type TenantFeatureProgressItem as aq, type TenantFeatureProgressItemState as ar, type TenantFeatureProgressResponse as as, type TenantFeatureProgressSeverity as at, type TenantFeatureProgressStatus as au, TenantIntrospectionApi as av, type TenantIntrospectionApiOptions as aw, type ApiDeleteOptions as ax, type PublicReadQueryOptions as ay, CustomerAuth as az, ContentClient as b, type ProductListingCard as b$, type CalculateShippingResult as b0, type CancelOrderParams as b1, type CancelOrderReconciliationStatus as b2, type CancelOrderResponse as b3, type CancelReasonCode as b4, CartApi as b5, type CartApiOptions as b6, type Comment as b7, type CommerceClientOptions as b8, type CommunityClientOptions as b9, type NormalizedProductSelection as bA, OrderApi as bB, type OrderApiOptions as bC, PRODUCT_PLP_FIND_OPTIONS as bD, PRODUCT_UPSERT_READONLY_FIELD_REASON as bE, PRODUCT_UPSERT_UNKNOWN_FIELD_REASON as bF, type PrepareFulfillmentOrderParams as bG, type PrepareFulfillmentOrderResponse as bH, ProductApi as bI, type ProductApiOptions as bJ, type ProductDetailBrand as bK, type ProductDetailCatalogResult as bL, type ProductDetailCatalogVariant as bM, type ProductDetailCategory as bN, type ProductDetailImage as bO, type ProductDetailImageMedia as bP, type ProductDetailMedia as bQ, type ProductDetailOption as bR, type ProductDetailOptionValue as bS, type ProductDetailTag as bT, type ProductDetailUnavailableReason as bU, type ProductDetailVariant as bV, type ProductDetailVariantOptionValue as bW, type ProductDetailVideo as bX, type ProductHrefGroup as bY, type ProductHrefOptions as bZ, type ProductHrefProduct as b_, type CommunityComment as ba, type CommunityCommentListSort as bb, type CommunityPost as bc, type CommunityPostCategory as bd, type CommunityPostListSort as be, type CommunityPostTag as bf, type CommunityPublicAuthorSnapshot as bg, type CommunityPublicMediaAsset as bh, type CommunityPublicReference as bi, type CompatibilityProductSelectionParamEvent as bj, type ConfirmPaymentParams as bk, type ConfirmPaymentResponse as bl, type CreateFulfillmentParams as bm, type CreateOrderItem as bn, type CreateOrderParams as bo, type CreateReturnParams as bp, type CustomerAuthOptions as bq, type CustomerOrderListOptions as br, type CustomerSnapshot as bs, DiscountApi as bt, type DiscountApiOptions as bu, type FeaturedImagePointerInput as bv, type LegacyProductSelectionParamEvent as bw, type ListingGroupsParams as bx, type MediaValue as by, type NormalizedOptionSwatch as bz, CustomerNamespace as c, type UpdateReturnParams as c$, type ProductListingCardOptions as c0, type ProductListingCardPriceRange as c1, type ProductListingCardRepresentativeVariant as c2, type ProductListingGroup as c3, type ProductListingGroupCatalogSummary as c4, type ProductListingGroupCatalogVariant as c5, type ProductListingGroupProjection as c6, type ProductListingGroupSummary as c7, type ProductListingGroupVariant as c8, type ProductListingGroupsCatalogProduct as c9, type ProductSelectionResolutionContext as cA, type ProductSelectionUrlEmit as cB, type ProductSelectionVariant as cC, type ProductUpsertFieldValidationErrorBody as cD, type ProductUpsertFieldValidationErrorReason as cE, type ProductVariantShape as cF, type RequestOptions as cG, type ResolveCancelRefundFailedResponse as cH, type ResolveCancelRefundOutcome as cI, type ResolveCancelRefundParams as cJ, type ResolveCancelRefundResponse as cK, type ResolveCancelRefundSucceededResponse as cL, type ResolveProductDisplayMediaInput as cM, type ResolveProductDisplayMediaResult as cN, type ReturnItem as cO, type ReturnReason as cP, type ReturnWithRefundItem as cQ, type ReturnWithRefundParams as cR, ShippingApi as cS, type ShippingApiOptions as cT, type StockCheckParams as cU, type StockCheckResponse as cV, type StockCheckResult as cW, type StockSnapshotItem as cX, type StockSnapshotParams as cY, type UpdateFulfillmentParams as cZ, type UpdateOrderParams as c_, type ProductListingGroupsCatalogResponse as ca, type ProductListingGroupsProduct as cb, type ProductListingGroupsResponse as cc, type ProductListingPageFilters as cd, type ProductListingPageSort as ce, type ProductListingProductShape as cf, type ProductListingSwatch as cg, type ProductMediaResolutionSource as ch, type ProductMoneyRange as ci, type ProductOptionMatrix as cj, type ProductOptionMatrixOption as ck, type ProductOptionMatrixValue as cl, type ProductOptionMatrixVariant as cm, type ProductOptionShape as cn, type ProductOptionValueShape as co, type ProductOptionValueSwatch as cp, type ProductOptionValueSwatchInput as cq, type ProductPriceRange as cr, type ProductSelectionAvailableSwatch as cs, type ProductSelectionAvailableValue as ct, type ProductSelectionByOptionValue as cu, ProductSelectionCodecError as cv, type ProductSelectionCodecOptions as cw, type ProductSelectionInput as cx, type ProductSelectionOptionValue as cy, type ProductSelectionResolution as cz, type ClientState as d, type UpdateTransactionParams as d0, type ValidateDiscountParams as d1, type ValidateDiscountResult as d2, type WithIdempotencyKey as d3, buildProductHref as d4, buildProductListingCard as d5, buildProductListingGroupProjection as d6, buildProductListingGroupsByOption as d7, buildProductOptionMatrix as d8, buildProductOptionMatrixFromDetail as d9, createProductSelectionCodec as da, getAvailableOptionValues as db, getProductSelectionImages as dc, getSelectedValueByOptionId as dd, getVariantAvailableForSale as de, getVariantAvailableStock as df, isProductUpsertFieldValidationErrorBody as dg, normalizeProductSelection as dh, normalizeProductSelectionFromMatrix as di, normalizeSelectedValueIds as dj, parseProductSelection as dk, projectProductToListingShape as dl, resolveFeaturedImagePointer as dm, resolveProductDisplayMedia as dn, resolveProductSelection as dp, resolveProductSelectionFromMatrix as dq, resolveProductSelectionMedia as dr, resolveVariantForSelection as ds, selectNext as dt, selectedSwatchMediaItemId as du, stringifyProductSelection as dv, toShopifyPriceRangeV2 as dw, type ClientConfig as e, type ApiQueryOptions as f, type ApplyDiscountParams as g, type CheckoutParams as h, type ClearCartParams as i, type ClientMetadata as j, type ContentClientOptions as k, type DeepPartial as l, type ExtractArrayType as m, type PayloadMutationResponse as n, type PublicCart as o, type PublicCartItem as p, type PublicCartReference as q, type PublicMediaAsset as r, type PublicMediaSize as s, type PublicOrder as t, type PublicOrderItem as u, type PublicOrderReference as v, type RemoveItemParams as w, type RetryConfig as x, type RootClient as y, type RootCollectionClient as z };
2825
+ export { type BanCustomerParams as $, type AddItemParams as A, type RootCollectionClient as B, CommerceClient as C, type DebugConfig as D, EventsClient as E, type RootReadOnlyQueryBuilder as F, type StorefrontContentListOptions as G, type StorefrontContentReference as H, type StorefrontGalleryItem as I, type StorefrontGalleryItemsListOptions as J, type StorefrontGalleryItemsSort as K, type StorefrontLink as L, type StorefrontLinksListOptions as M, type StorefrontLinksSort as N, BaseApi as O, type PayloadFindResponse as P, type ServerApiOptions as Q, type RemoveDiscountParams as R, type Sort as S, ServerCommerceClient as T, type UpdateItemParams as U, type TenantIntrospectionClient as V, type Where as W, type SubscribeMembershipParams as X, type SubscribeMembershipResponse as Y, type CancelMembershipParams as Z, type CancelMembershipResponse as _, CommunityClient as a, type ResolveProductSelectionMediaResult as a$, type CommunityBan as a0, type UnbanCustomerParams as a1, type ClientServerConfig as a2, type RootServerClientWithEvents as a3, type CollectionFieldSchema as a4, type CollectionSchemaResponse as a5, type EventGuestCancelParams as a6, type EventGuestRegistration as a7, type EventGuestRegistrationResponse as a8, type EventRegistrationAnswerInput as a9, TenantIntrospectionApi as aA, type TenantIntrospectionApiOptions as aB, type ApiDeleteOptions as aC, type PublicReadQueryOptions as aD, CustomerAuth as aE, type CustomerProfile as aF, type CustomerAuthResponse as aG, type CustomerLoginData as aH, type CustomerRegisterResponse as aI, type CustomerRegisterData as aJ, type CustomerRefreshResponse as aK, type UpdateProfileData as aL, type ProductListingPageBaseParams as aM, type ProductListingPageParams as aN, type ProductDetailParams as aO, type ProductDetailResult as aP, type ProductListingPageCatalogParams as aQ, type ProductListingPageResult as aR, type ProductListingGroupsCatalogItem as aS, type ProductListingPageFullParams as aT, type ProductListingGroupsItem as aU, type ProductDetail as aV, type ProductDetailCatalog as aW, type StockSnapshotResponse as aX, type ProductSelectionMediaSource as aY, type ProductDisplayMediaSource as aZ, type ResolveProductSelectionMediaInput as a_, type EventRegistrationAttendeeInput as aa, type EventRegistrationPublic as ab, type EventRegistrationRegisterParams as ac, type EventRegistrationRegisterResponse as ad, type EventsCalendarItem as ae, type EventsClientOptions as af, type EventsDateParam as ag, type EventsExternalSource as ah, type EventsLocation as ai, type EventsOccurrenceLocation as aj, type EventsRangeEvent as ak, type EventsRangeOccurrence as al, type EventsRangeParams as am, type EventsRangeResponse as an, type EventsTaxonomyItem as ao, ModerationApi as ap, type RootServerClient as aq, type TenantFeatureProgressEvidenceValue as ar, type TenantFeatureProgressFeature as as, type TenantFeatureProgressGroup as at, type TenantFeatureProgressInput as au, type TenantFeatureProgressItem as av, type TenantFeatureProgressItemState as aw, type TenantFeatureProgressResponse as ax, type TenantFeatureProgressSeverity as ay, type TenantFeatureProgressStatus as az, ContentClient as b, type ProductDetailImage as b$, type ProductSelectionMediaPointer as b0, type RootClientWithEvents as b1, type BulkImportFulfillmentsParams as b2, type BulkImportFulfillmentsResponse as b3, type CalculateShippingParams as b4, type CalculateShippingResult as b5, type CancelOrderParams as b6, type CancelOrderReconciliationStatus as b7, type CancelOrderResponse as b8, type CancelReasonCode as b9, type CustomerOrderListOptions as bA, type CustomerSnapshot as bB, DiscountApi as bC, type DiscountApiOptions as bD, type DiscountErrorReasonCode as bE, type FeaturedImagePointerInput as bF, type GetOrderByPaymentIdParams as bG, type LegacyProductSelectionParamEvent as bH, type ListingGroupsParams as bI, type MediaValue as bJ, type MembershipStatus as bK, type NormalizedOptionSwatch as bL, type NormalizedProductSelection as bM, OrderApi as bN, type OrderApiOptions as bO, type OrderByPaymentResult as bP, PRODUCT_PLP_FIND_OPTIONS as bQ, PRODUCT_UPSERT_READONLY_FIELD_REASON as bR, PRODUCT_UPSERT_UNKNOWN_FIELD_REASON as bS, type PrepareFulfillmentOrderParams as bT, type PrepareFulfillmentOrderResponse as bU, ProductApi as bV, type ProductApiOptions as bW, type ProductDetailBrand as bX, type ProductDetailCatalogResult as bY, type ProductDetailCatalogVariant as bZ, type ProductDetailCategory as b_, CartApi as ba, type CartApiOptions as bb, type CartMergeParams as bc, type CartMergeResult as bd, type CartMineResult as be, type Comment as bf, type CommerceClientOptions as bg, type CommunityClientOptions as bh, type CommunityComment as bi, type CommunityCommentListSort as bj, type CommunityPost as bk, type CommunityPostCategory as bl, type CommunityPostListSort as bm, type CommunityPostTag as bn, type CommunityPublicAuthorSnapshot as bo, type CommunityPublicMediaAsset as bp, type CommunityPublicReference as bq, type CompatibilityProductSelectionParamEvent as br, type ConfirmPaymentParams as bs, type ConfirmPaymentResponse as bt, type ConfirmPaymentWithOrderResult as bu, type CreateFulfillmentParams as bv, type CreateOrderItem as bw, type CreateOrderParams as bx, type CreateReturnParams as by, type CustomerAuthOptions as bz, CustomerNamespace as c, type ReturnItem as c$, type ProductDetailImageMedia as c0, type ProductDetailMedia as c1, type ProductDetailOption as c2, type ProductDetailOptionValue as c3, type ProductDetailTag as c4, type ProductDetailUnavailableReason as c5, type ProductDetailVariant as c6, type ProductDetailVariantOptionValue as c7, type ProductDetailVideo as c8, type ProductHrefGroup as c9, type ProductOptionShape as cA, type ProductOptionValueShape as cB, type ProductOptionValueSwatch as cC, type ProductOptionValueSwatchInput as cD, type ProductPriceRange as cE, type ProductSelectionAvailableSwatch as cF, type ProductSelectionAvailableValue as cG, type ProductSelectionByOptionValue as cH, ProductSelectionCodecError as cI, type ProductSelectionCodecOptions as cJ, type ProductSelectionInput as cK, type ProductSelectionOptionValue as cL, type ProductSelectionResolution as cM, type ProductSelectionResolutionContext as cN, type ProductSelectionUrlEmit as cO, type ProductSelectionVariant as cP, type ProductUpsertFieldValidationErrorBody as cQ, type ProductUpsertFieldValidationErrorReason as cR, type ProductVariantShape as cS, type RequestOptions as cT, type ResolveCancelRefundFailedResponse as cU, type ResolveCancelRefundOutcome as cV, type ResolveCancelRefundParams as cW, type ResolveCancelRefundResponse as cX, type ResolveCancelRefundSucceededResponse as cY, type ResolveProductDisplayMediaInput as cZ, type ResolveProductDisplayMediaResult as c_, type ProductHrefOptions as ca, type ProductHrefProduct as cb, type ProductListingCard as cc, type ProductListingCardOptions as cd, type ProductListingCardPriceRange as ce, type ProductListingCardRepresentativeVariant as cf, type ProductListingGroup as cg, type ProductListingGroupCatalogSummary as ch, type ProductListingGroupCatalogVariant as ci, type ProductListingGroupProjection as cj, type ProductListingGroupSummary as ck, type ProductListingGroupVariant as cl, type ProductListingGroupsCatalogProduct as cm, type ProductListingGroupsCatalogResponse as cn, type ProductListingGroupsProduct as co, type ProductListingGroupsResponse as cp, type ProductListingPageFilters as cq, type ProductListingPageSort as cr, type ProductListingProductShape as cs, type ProductListingSwatch as ct, type ProductMediaResolutionSource as cu, type ProductMoneyRange as cv, type ProductOptionMatrix as cw, type ProductOptionMatrixOption as cx, type ProductOptionMatrixValue as cy, type ProductOptionMatrixVariant as cz, type CustomerMembershipView as d, type ReturnReason as d0, type ReturnWithRefundItem as d1, type ReturnWithRefundParams as d2, ShippingApi as d3, type ShippingApiOptions as d4, type StockCheckParams as d5, type StockCheckResponse as d6, type StockCheckResult as d7, type StockSnapshotItem as d8, type StockSnapshotParams as d9, projectProductToListingShape as dA, resolveFeaturedImagePointer as dB, resolveProductDisplayMedia as dC, resolveProductSelection as dD, resolveProductSelectionFromMatrix as dE, resolveProductSelectionMedia as dF, resolveVariantForSelection as dG, selectNext as dH, selectedSwatchMediaItemId as dI, stringifyProductSelection as dJ, toShopifyPriceRangeV2 as dK, type TransactionStatus as da, type UpdateFulfillmentParams as db, type UpdateOrderParams as dc, type UpdateReturnParams as dd, type UpdateTransactionParams as de, type ValidateDiscountParams as df, type ValidateDiscountResult as dg, type WithIdempotencyKey as dh, buildProductHref as di, buildProductListingCard as dj, buildProductListingGroupProjection as dk, buildProductListingGroupsByOption as dl, buildProductOptionMatrix as dm, buildProductOptionMatrixFromDetail as dn, createProductSelectionCodec as dp, getAvailableOptionValues as dq, getProductSelectionImages as dr, getSelectedValueByOptionId as ds, getVariantAvailableForSale as dt, getVariantAvailableStock as du, isProductUpsertFieldValidationErrorBody as dv, normalizeProductSelection as dw, normalizeProductSelectionFromMatrix as dx, normalizeSelectedValueIds as dy, parseProductSelection as dz, type ClientState as e, type ClientConfig as f, type ApiQueryOptions as g, type ApplyDiscountParams as h, type CheckoutParams as i, type ClearCartParams as j, type ClientMetadata as k, type ContentClientOptions as l, type DeepPartial as m, type ExtractArrayType as n, type PayloadMutationResponse as o, type PublicCart as p, type PublicCartItem as q, type PublicCartReference as r, type PublicMediaAsset as s, type PublicMediaSize as t, type PublicOrder as u, type PublicOrderItem as v, type PublicOrderReference as w, type RemoveItemParams as x, type RetryConfig as y, type RootClient as z };