@01.software/sdk 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @01.software/sdk
 
+## 0.44.0
+
+### Minor Changes
+
+- 14f6a6a: BREAKING (0.x minor): require `pgProvider` alongside `pgPaymentId` for paid
+  order creation and checkout inputs so storefronts persist the same
+  provider-scoped payment key used by confirmation and payment recovery. Free
+  orders omit both fields.
+
+### Patch Changes
+
+- 2e5c223: Expose registry-backed market country and currency fields in generated Payload collection types.
+- 99727ac: Expose the product `unlisted` status in generated SDK Payload types. Product
+  visibility now lives on `status`; Console migrations add the `unlisted` enum
+  value, convert legacy product visibility values into status, and remove the
+  legacy visibility storage.
+
+## 0.43.0
+
+### Minor Changes
+
+- 81ef105: Expose cart item `requiresShipping` snapshots through the public cart item
+  types, and update the ecommerce starter so non-shipping-only carts skip shipping
+  address collection while legacy or mixed carts remain shippable by default.
+- 5d7b26f: Expose the new `markets` collection slug through the browser-safe `COLLECTIONS`
+  constant so storefront and integration code can address tenant-scoped market
+  records without local collection-name mirrors.
+
+### Patch Changes
+
+- 9789528: Add checkout shipping context fields to the SDK contract and update the
+  ecommerce starter to pass checkout context through the order API instead of
+  mutating carts through the customer-scoped SDK client.
+- 9b7afab: Expose membership plan and customer membership collection slugs in the public collection surface.
+- db8bd4b: Add optional `seo` (title/description) to product upsert `ProductFieldsInput` for CSV import parity.
+- b95f6ac: Expose stable storefront discount validation reason codes in the SDK.
+  `ValidateDiscountResult.reasonCode` now carries the machine-readable discount
+  reason union returned by `/api/discounts/validate`, so storefronts can branch and
+  localize without parsing human-readable `reason` text.
+- c60ec7f: fix(sdk): remove stale event calendar order field
+
+  `EventCalendar` and its select type no longer expose the stale `_order` field
+  because tenant-global event calendars are not operator-orderable.
+
+- 6c71a71: chore(sdk): sync event occurrence timezone generated type docs
+
+  The generated Payload types now include the Event Occurrence timezone field
+  description used by Console's read-only occurrence identity timezone contract.
+  Type-only change; no SDK runtime or request shape changed.
+
+- 3aa6239: Allow `events.getRange()` to omit `start` and `end` so the public events range endpoint can use the tenant calendar's public listing defaults.
+- 294b7d1: Keep membership contract-parity type tests within the SDK export guard's explicit test-only private-contract allowlist.
+- f87fe09: Add return approval and rejection commerce notification webhook events.
+- 4362b14: Expose tenant commerce `fulfillmentMode` in tenant feature progress responses.
+
 ## 0.42.0
 
 ### Minor Changes

package/README.md

@@ -118,7 +118,10 @@ typo detection) and pass it as the generic. Mistyped names and out-of-enum
 values then fail to compile:
 
 ```typescript
-import { createAnalytics, defineAnalyticsEvents } from '@01.software/sdk/analytics'
+import {
+  createAnalytics,
+  defineAnalyticsEvents,
+} from '@01.software/sdk/analytics'
 
 type ShopEvents = {
   signup: { plan: 'free' | 'pro'; trial: boolean }
@@ -128,7 +131,7 @@ type ShopEvents = {
 
 const analytics = createAnalytics<ShopEvents>({ publishableKey: 'pk_xxx' })
 analytics.track('signup', { plan: 'pro', trial: false }) // ✅
-analytics.track('checkout_start')                         // ✅ no props
+analytics.track('checkout_start') // ✅ no props
 // analytics.track('signpu', { plan: 'pro', trial: false }) // ❌ unknown event
 // analytics.track('signup', { plan: 'team', trial: false }) // ❌ enum violation
 
@@ -144,7 +147,10 @@ instance for its subtree:
 Reusing the `ShopEvents` type from above:
 
 ```tsx
-import { AnalyticsProvider, useAnalytics } from '@01.software/sdk/analytics/react'
+import {
+  AnalyticsProvider,
+  useAnalytics,
+} from '@01.software/sdk/analytics/react'
 
 function Root() {
   return (
@@ -220,7 +226,8 @@ const order = await server.commerce.orders.create({
     { product: productId, variant: variantId, option: optionId, quantity: 1 },
   ],
   totalAmount: 10000,
-  pgPaymentId: 'provider-payment-id', // optional (omit for free orders)
+  pgProvider: 'portone', // required with pgPaymentId
+  pgPaymentId: 'provider-payment-id', // omit both fields for free orders
   discountCode: 'WELCOME10', // optional
 })
 
@@ -340,14 +347,13 @@ mismatches, still throw
 typed `SDKError` subclasses and preserve request IDs through the existing
 `lastRequestId` / `onRequestId` path.
 
-Public product visibility has two axes. Lifecycle `status` must still be
-`published` and `publishedAt` must be current or empty. Then
-`storefrontVisibility` decides storefront exposure: `listed` products appear in
-listing helpers and direct detail, `unlisted` products are omitted from listing
-helpers but can be fetched by direct detail slug/id, and `hidden` products return
-`{ found: false, reason: 'not_published' }` from detail and are omitted from
-listings. Legacy products without `storefrontVisibility` are treated as
-`listed`.
+Public product visibility is driven by product `status` and `publishedAt`.
+Listing helpers return products with `status: 'published'` when `publishedAt`
+is current or empty. Direct detail and checkout admission also allow
+`status: 'unlisted'`, so an unlisted product can be opened by slug/id without
+appearing in PLP/search/curated listing helpers. Draft, archived, scheduled, or
+malformed lifecycle states return `{ found: false, reason: 'not_published' }`
+from detail and are omitted from listings.
 
 The successful product payload exposes inventory rollups without sentinel
 values: `product.totalInventory` is the tracked stock sum across non-unlimited
@@ -451,13 +457,6 @@ const { docs } = await server.collections.from('products').find({
           { publishedAt: { equals: null } },
         ],
       },
-      {
-        or: [
-          { storefrontVisibility: { equals: 'listed' } },
-          { storefrontVisibility: { exists: false } },
-          { storefrontVisibility: { equals: null } },
-        ],
-      },
     ],
   },
   limit: 24,
@@ -769,7 +768,7 @@ Dotted-path filters (`where: { 'product.slug': { equals } }`) are Payload-native
 
 Checklist when `find()` returns `docs: []` unexpectedly, in order of likelihood:
 
-1. **Access control filtered the document.** Many collections enforce public read filters. Products require `status: 'published'`, a current or unset `publishedAt`, and listable storefront visibility (`listed`, legacy missing, or `null`) for publishable-key raw listing reads. Draft, future, `unlisted`, `hidden`, or malformed products silently disappear from raw listing results even when their slug or ID matches. Use the shaped product detail helper for direct-link `unlisted` products. Correlate with backend logs via `client.lastRequestId` (or catch `SDKError.requestId`).
+1. **Access control filtered the document.** Many collections enforce public read filters. Product listing reads require `status: 'published'` plus a current or unset `publishedAt`. Draft, future, `unlisted`, archived, or malformed products silently disappear from raw listing results even when their slug or ID matches. Use `commerce.product.detail({ slug | id })` for `unlisted` products. Correlate with backend logs via `client.lastRequestId` (or catch `SDKError.requestId`).
 2. **Build-time publishable key / API URL differs from runtime.** SSG `generateStaticParams` / `generateMetadata` / the page render must all see the same tenant context. A wrong or missing key at build time produces a baked-in empty response.
 3. **Next.js SSG fetch cache served a stale empty response.** Use `cache: 'no-store'` or `export const revalidate = 0` on server components that should reflect live data.
 4. **`where: { slug: 'x' }` string shorthand.** Always use `{ slug: { equals: 'x' } }` — bare strings silently match nothing.
@@ -1097,7 +1096,7 @@ Available on ServerClient via `server.commerce.orders.*`. `checkout` and `listMi
 // Orders
 await server.commerce.orders.create(params)
 await server.commerce.orders.update({ orderNumber, status: 'confirmed' })
-await server.commerce.orders.checkout({ cartId, pgPaymentId?, orderNumber, customerSnapshot, discountCode? })
+await server.commerce.orders.checkout({ cartId, orderNumber, customerSnapshot, pgProvider, pgPaymentId, discountCode? })
 
 // Single-order lookup (getOrder endpoint removed — use collection find)
 const { docs: [order] } = await server.collections.from('orders').find({
@@ -1123,6 +1122,12 @@ await server.commerce.orders.confirmPayment({
   providerEventId,
 })
 
+// For paid create/checkout flows, pass pgProvider with the same provider slug
+// you will later use for confirmPayment and getByPaymentId. pgProvider and
+// pgPaymentId are a pair: omit both for free orders, or provide both for paid
+// payment windows. getByPaymentId({ pgProvider, pgPaymentId }) is strict and
+// only resolves payment transactions stored with the same provider.
+
 // Low-level transaction annotation / compatibility path. Prefer confirmPayment()
 // for normal provider-verified paid transitions.
 // status: 'failed' records a retryable PG failure on the Transaction only; the
@@ -1411,7 +1416,7 @@ Source of truth: `packages/sdk/src/core/collection/const.ts` (`COLLECTIONS`).
 | Category           | Browser-public generic collections                                                                                                                                 |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Tenant             | `tenants`, `tenant-metadata`                                                                                                                                       |
-| Products           | `products`, `product-variants`, `product-options`, `product-option-values`, `product-categories`, `product-tags`, `product-collections`, `brands`                  |
+| Products           | `products`, `product-variants`, `product-options`, `product-option-values`, `product-categories`, `product-tags`, `product-collections`, `markets`, `brands`       |
 | Customers          | `customer-profiles`                                                                                                                                                |
 | Commerce           | `discounts`, `shipping-policies`, `shipping-zones`                                                                                                                 |
 | Content            | `documents`, `document-categories`, `document-types`, `articles`, `article-authors`, `article-categories`, `article-tags`, `links`, `link-categories`, `link-tags` |

package/dist/client.cjs

@@ -668,6 +668,64 @@ async function httpFetch(url, options) {
   throw lastError ?? new NetworkError("Request failed after retries");
 }
 
+// src/core/api/endpoints.ts
+var COMMERCE_ENDPOINTS = {
+  orders: {
+    create: "/api/orders/create",
+    update: "/api/orders/update",
+    confirmPayment: "/api/orders/confirm-payment",
+    byPayment: "/api/orders/by-payment",
+    cancel: "/api/orders/cancel",
+    resolveCancelRefund: "/api/orders/resolve-cancel-refund",
+    checkout: "/api/orders/checkout",
+    createFulfillment: "/api/orders/create-fulfillment",
+    updateFulfillment: "/api/orders/update-fulfillment"
+  },
+  transactions: {
+    update: "/api/transactions/update"
+  },
+  returns: {
+    create: "/api/returns/create",
+    update: "/api/returns/update",
+    returnRefund: "/api/returns/return-refund"
+  },
+  fulfillmentOrders: {
+    prepare: "/api/fulfillment-orders/prepare-fulfillment-order"
+  },
+  fulfillments: {
+    bulkImport: "/api/fulfillments/bulk-import"
+  },
+  carts: {
+    mine: "/api/carts/mine",
+    merge: "/api/carts/merge",
+    addItem: "/api/carts/add-item",
+    updateItem: "/api/carts/update-item",
+    removeItem: "/api/carts/remove-item",
+    applyDiscount: "/api/carts/apply-discount",
+    removeDiscount: "/api/carts/remove-discount",
+    clear: "/api/carts/clear"
+  },
+  products: {
+    stockCheck: "/api/products/stock-check",
+    stockSnapshot: "/api/products/stock",
+    listingGroups: "/api/products/listing-groups",
+    listingGroupsCatalog: "/api/products/listing-groups/catalog",
+    listingGroupsQuery: "/api/products/listing-groups/query",
+    listingGroupsQueryCatalog: "/api/products/listing-groups/query/catalog",
+    detail: "/api/products/detail",
+    detailCatalog: "/api/products/detail/catalog",
+    upsert: "/api/products/upsert"
+  }
+};
+var COMMERCE_ENDPOINT_PATHS = Object.values(
+  COMMERCE_ENDPOINTS
+).flatMap((group) => Object.values(group));
+var MEMBERSHIP_ENDPOINTS = {
+  subscribe: "/api/memberships/subscribe",
+  cancel: (id) => `/api/memberships/${id}/cancel`,
+  me: "/api/memberships/me"
+};
+
 // src/core/internal/utils/query-string.ts
 function productDetailQuery(params) {
   const search = new URLSearchParams();
@@ -676,7 +734,7 @@ function productDetailQuery(params) {
   } else {
     search.set("id", params.id);
   }
-  return `/api/products/detail?${search}`;
+  return `${COMMERCE_ENDPOINTS.products.detail}?${search}`;
 }
 function productDetailCatalogQuery(params) {
   const search = new URLSearchParams();
@@ -685,20 +743,17 @@ function productDetailCatalogQuery(params) {
   } else {
     search.set("id", params.id);
   }
-  return `/api/products/detail/catalog?${search}`;
+  return `${COMMERCE_ENDPOINTS.products.detailCatalog}?${search}`;
 }
 function listingGroupsCatalogQuery(params) {
-  return `/api/products/listing-groups/catalog?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
+  return `${COMMERCE_ENDPOINTS.products.listingGroupsCatalog}?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
 }
 function appendListingGroupsQuerySearchParams(search, options) {
   if (options?.page != null) search.set("page", String(options.page));
   if (options?.limit != null) search.set("limit", String(options.limit));
   if (options?.sort != null) {
     const sort = options.sort;
-    search.set(
-      "sort",
-      Array.isArray(sort) ? sort.join(",") : sort
-    );
+    search.set("sort", Array.isArray(sort) ? sort.join(",") : sort);
   }
   if (options?.where != null) {
     search.set("whereJson", JSON.stringify(options.where));
@@ -708,16 +763,16 @@ function listingGroupsQueryUrl(options) {
   const search = new URLSearchParams();
   appendListingGroupsQuerySearchParams(search, options);
   const query = search.toString();
-  return `/api/products/listing-groups/query${query ? `?${query}` : ""}`;
+  return `${COMMERCE_ENDPOINTS.products.listingGroupsQuery}${query ? `?${query}` : ""}`;
 }
 function listingGroupsQueryCatalogUrl(options) {
   const search = new URLSearchParams();
   appendListingGroupsQuerySearchParams(search, options);
   const query = search.toString();
-  return `/api/products/listing-groups/query/catalog${query ? `?${query}` : ""}`;
+  return `${COMMERCE_ENDPOINTS.products.listingGroupsQueryCatalog}${query ? `?${query}` : ""}`;
 }
 function stockSnapshotQuery(params) {
-  return `/api/products/stock?variantIds=${params.variantIds.map(encodeURIComponent).join(",")}`;
+  return `${COMMERCE_ENDPOINTS.products.stockSnapshot}?variantIds=${params.variantIds.map(encodeURIComponent).join(",")}`;
 }
 
 // src/core/collection/http-client.ts
@@ -1606,48 +1661,6 @@ var CustomerNamespace = class {
   }
 };
 
-// src/core/api/endpoints.ts
-var COMMERCE_ENDPOINTS = {
-  orders: {
-    create: "/api/orders/create",
-    update: "/api/orders/update",
-    confirmPayment: "/api/orders/confirm-payment",
-    byPayment: "/api/orders/by-payment",
-    cancel: "/api/orders/cancel",
-    resolveCancelRefund: "/api/orders/resolve-cancel-refund",
-    checkout: "/api/orders/checkout",
-    createFulfillment: "/api/orders/create-fulfillment",
-    updateFulfillment: "/api/orders/update-fulfillment"
-  },
-  transactions: {
-    update: "/api/transactions/update"
-  },
-  returns: {
-    create: "/api/returns/create",
-    update: "/api/returns/update",
-    returnRefund: "/api/returns/return-refund"
-  },
-  fulfillmentOrders: {
-    prepare: "/api/fulfillment-orders/prepare-fulfillment-order"
-  },
-  fulfillments: {
-    bulkImport: "/api/fulfillments/bulk-import"
-  },
-  carts: {
-    mine: "/api/carts/mine",
-    merge: "/api/carts/merge",
-    addItem: "/api/carts/add-item",
-    updateItem: "/api/carts/update-item",
-    removeItem: "/api/carts/remove-item",
-    applyDiscount: "/api/carts/apply-discount",
-    removeDiscount: "/api/carts/remove-discount",
-    clear: "/api/carts/clear"
-  }
-};
-var COMMERCE_ENDPOINT_PATHS = Object.values(
-  COMMERCE_ENDPOINTS
-).flatMap((group) => Object.values(group));
-
 // src/core/api/cart-api.ts
 var CartApi = class extends CustomerScopedApi {
   constructor(options) {
@@ -2871,7 +2884,10 @@ var CommerceClient = class {
       onRequestId: options.onRequestId
     });
     this.product = {
-      stockCheck: (params) => api.post("/api/products/stock-check", params),
+      stockCheck: (params) => api.post(
+        COMMERCE_ENDPOINTS.products.stockCheck,
+        params
+      ),
       stockSnapshot: (params) => api.get(stockSnapshotQuery(params)),
       listingGroups: (params) => api.get(
         listingGroupsCatalogQuery(params)
@@ -2889,7 +2905,9 @@ var CommerceClient = class {
       },
       detail: async (params) => {
         try {
-          const product = await api.get(productDetailQuery(params));
+          const product = await api.get(
+            productDetailQuery(params)
+          );
           return { found: true, product };
         } catch (err) {
           const notFoundResult = productDetailResultFromError(err);
@@ -2937,7 +2955,10 @@ var CommerceClient = class {
       validate: (params) => api.post("/api/discounts/validate", params)
     };
     this.shipping = {
-      calculate: (params) => api.post("/api/shipping-policies/calculate", params)
+      calculate: (params) => api.post(
+        "/api/shipping-policies/calculate",
+        params
+      )
     };
   }
 };
@@ -3026,8 +3047,12 @@ function buildGuestCancelRequestBody(token, params) {
 }
 function buildRangeEndpoint(params) {
   const urlParams = new URLSearchParams();
-  urlParams.set("start", formatDateParam(params.start));
-  urlParams.set("end", formatDateParam(params.end));
+  if (params.start !== void 0) {
+    urlParams.set("start", formatDateParam(params.start));
+  }
+  if (params.end !== void 0) {
+    urlParams.set("end", formatDateParam(params.end));
+  }
   if (params.limit !== void 0) urlParams.set("limit", String(params.limit));
   if (params.page !== void 0) urlParams.set("page", String(params.page));
   appendValues(urlParams, "calendar", params.calendar);
@@ -3050,6 +3075,13 @@ function appendValues(params, key, value) {
 }
 
 // src/core/client/client.ts
+var BrowserMembershipApi = class extends CustomerScopedApi {
+  me() {
+    return this.request(MEMBERSHIP_ENDPOINTS.me, {
+      method: "GET"
+    });
+  }
+};
 var Client = class {
   constructor(options) {
     this.lastRequestId = null;
@@ -3114,6 +3146,16 @@ var Client = class {
       onRequestId,
       this.config.apiUrl
     );
+    const membershipApi = new BrowserMembershipApi("MembershipApi", {
+      publishableKey: this.config.publishableKey,
+      apiUrl: this.config.apiUrl,
+      customerToken: () => this.customer.auth.getToken(),
+      onUnauthorized,
+      onRequestId
+    });
+    this.memberships = {
+      me: membershipApi.me.bind(membershipApi)
+    };
   }
   getState() {
     return { ...this.state };