@01.software/sdk 0.71.0 → 0.73.1

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # @01.software/sdk
 
+## 0.73.1
+
+### Patch Changes
+
+- 57e6e15: Sort product options and option values by their orderable `_order` keys in Payload's fractional-indexing (code-unit) order instead of the runtime-locale-dependent `localeCompare` order. For current-format keys this is the order the Admin Panel shows.
+- 623b7e8: Update the generated field descriptions for the tenant base currency and the market exchange rate.
+- 265ad09: Synchronize generated storage types for internal Project invitations and private
+  current-email verification evidence. No invitation SDK API or collection access
+  is added.
+
+## 0.73.0
+
+### Minor Changes
+
+- b271588: Add optional market selection to events.getAdmissionAvailability so callers can display the same market price used by Cart and Checkout. Omitted market uses the catalog default; the public price response keeps its existing fields. Resolved-market reads, including default-market calls, omit admission types whose same-tenant products are not assigned to that market.
+- 41c7d41: Add server-only `memberships.billingCustodyContext` to obtain the Console-owned
+  restore generation through the existing delegated HMAC custody boundary. Keep
+  legacy ciphertext requests and responses compatible. Deploy Console support
+  before publishing the SDK or using the updated Membership and CLUB templates.
+  The bundled starters obtain the generation from Console without a storefront
+  environment variable and retain the generation across custody read/CAS updates.
+
+### Patch Changes
+
+- 163b450: Clarify that form submission email settings are retained for compatibility and do not send notifications, without changing field keys or types.
+- ae622d1: Refresh generated workspace sender, credential, and webhook field descriptions. Public types and API behavior are unchanged.
+- f8a25e1: Clarify that tenant administrators obtain the billing custody restore generation from the authenticated Console delegated billing connection panel.
+- 9cfcc4e: Update generated User membership guidance to point Project workspace member management to Settings > Workspace > Project environments. No SDK type shape or runtime behavior changes.
+- b8a447c: Clarify generated transaction kind and shipping policy descriptions without changing field keys or types.
+- 4781438: Clarify the generated customer address description. Field types and API response shapes are unchanged.
+- 3d0665d: Clarify the generated preview destination description without changing its schema or behavior.
+- 668102b: Webhook.url 필드 설명의 민감정보 경고를 복원합니다. 타입 구조는 변경하지 않습니다.
+- 5ef9bc6: Format the numbers in the `Monthly API usage limit exceeded (current/limit)` error message with a fixed `en-US` locale so the message no longer depends on the runtime's default locale.
+
+## 0.72.1
+
+### Patch Changes
+
+- bbcdc03: Clarify generated event occurrence identity and community comment-setting descriptions in operator-facing wording. Types, field access, and response shapes are unchanged.
+- 327779c: Clarify generated JSDoc for event admission sale windows and usage rate card effective windows after adding date and time pickers in the Admin Panel. Stored instants, SDK runtime behavior, and public API shape remain unchanged.
+- 2075d27: Clarify the generated event registration-list description with operator-facing wording. Types, field access, and response shapes are unchanged.
+- 2990468: Correct the generated event `externalSource` description comment: provider, source ID, and URL can all appear in public read responses. Field access and response shapes are unchanged.
+- 055671d: Clarify generated commerce field descriptions in operator-facing wording. Types, field access, and response shapes are unchanged.
+- 5581c60: Clarify generated event field descriptions for admission quantity limits, attendee privacy, and public API visibility.
+- 5138b42: Clarify generated customer and membership field descriptions without changing field keys or types.
+- 269db8b: Refresh generated Payload type descriptions for workspace and platform operator guidance.
+- 9ec8504: Update generated type description comments without changing request or response shapes. The server applies the calendar timezone when a non-duplicate event create omits timezone.
+- 15e5dc6: Restore privacy, entitlement lifecycle and validation, usage aggregation, and webhook idempotency details in generated field descriptions.
+- 1c23d29: Document the membership delegated billing connection in generated payment credential types.
+- 3b47cff: Clarify generated Product `markets` JSDoc: new products without markets receive the active default market if one exists, and removing every market from an existing product excludes it from market catalogs. Runtime behavior and public API shape remain unchanged.
+
+## 0.72.0
+
+### Minor Changes
+
+- 756ca0b: Document the owner-approved multi-currency reporting correction for server-only
+  customer `lifetimeValue`: retain `number | null`, sum only a verified single
+  currency, and return `null` for mixed or unavailable currencies (zero orders
+  remain `0`). No new SDK field or webhook envelope is introduced and persisted
+  webhook bytes are unchanged. This minor records the public behavior correction
+  under [the #7859 owner decision](https://github.com/01-office/01-software/issues/7859#issuecomment-6540676116),
+  even though the generated property type is unchanged.
+- 181d5ee: **Additive response arms (0.x minor).** `server.commerce.cancelOrder()` can now
+  return the registered managed Toss outcome (ADR 0073). When the paid order was
+  captured through a Console payment connection, Console refunds it after the
+  local cancel commits and the response carries
+  `managedRefund: { outcome: 'completed' | 'convergence_pending' | 'operator_required' }`
+  with `providerRefunded` and the refunded amount, never `refundPending`. Do not
+  run a storefront or BFF provider refund for these responses: retries read or
+  resume the same Console refund. An exhaustive check over `CancelOrderResponse`
+  needs the two new arms (`CancelOrderManagedCommittedResponse`,
+  `CancelOrderManagedAlreadyCanceledResponse`).
+
+  Import both response arms and `ManagedCancelRefundOutcome` as types from
+  `@01.software/sdk`, alongside `CancelOrderResponse`.
+
+  Custom bridge, legacy, PortOne, and credit-funded orders keep the existing
+  `refundPending` handoff unchanged.
+
+- cf8e6d5: **BREAKING (0.x minor).** Prepare strict readers for the reserved `'stripe'`
+  managed provider before the server can emit it.
+  `CheckoutPaymentSessionRef['provider']` widens to
+  `'toss' | 'portone' | 'stripe'`, so an exhaustive `switch` over it needs a
+  `'stripe'` case. Earlier SDK versions reject a `'stripe'` reference as an
+  invalid canonical response; upgrade every consumer that reads Checkouts before
+  Stripe becomes available.
+
+  Checkout references accept `provider: 'stripe'`. PaymentSession methods
+  (`create`, `createPortOne`, `retrieve`, `retrievePortOne`, `cancel`,
+  `cancelPortOne` and server `confirm`) reject a Stripe session after validating
+  it completely, including the strict Stripe Payment Element action
+  (`stripe_payment_element` with `clientSecret`, `publishableKey` and a
+  credential-free HTTPS or loopback `returnUrl`), and report a generic invalid response with
+  `details.expected` and `details.actual`. Partial or unknown action fields are
+  rejected. Stripe is not available yet and the SDK adds no Stripe PaymentSession
+  method. Toss, PortOne and custom bridge behavior, including custom provider
+  names, is unchanged.
+
+### Patch Changes
+
+- 88bee51: Clarify the generated admission type price-reference guidance: the reference is optional when saving and required for sales. The generated field type and public API behavior are unchanged.
+- 9f326b5: Synchronize generated collection and calendar field descriptions with neutral Console copy for workspace menu display names. Type shapes, runtime behavior, and API titles are unchanged.
+- 1d03497: Clarify the generated documentation for membership payment results that were not applied at the time they were received.
+- 931d8a0: Clarify generated Discount type descriptions for code usage counts, pending checkout reservations, and unsupported allocation repair guidance.
+- 1a6e310: Restore the read-only note in the generated Discount `usesCount` type description.
+- 2f4989e: Synchronize generated EventRegistration types with the reordered registration fields (status, attendance, and quantity now come first). Only property order changes; SDK runtime behavior, collection buckets, request inputs, and public responses remain unchanged. Separately, Console now reads `event-occurrences` newest `startsAt` first when a request omits `sort`; pass `sort` explicitly if you depend on a specific order.
+- 4db606a: Clarify the generated membership plan description comment to reflect its inclusion in public query responses for active plans. Field access and response shapes are unchanged.
+- b43cb9c: Synchronize generated Order and Checkout types with the internal Checkout `source` field and the internal `in_person` Order source value. SDK runtime behavior, collection buckets, request inputs, and public responses remain unchanged.
+- ba3ffc2: Synchronize generated FulfillmentOrder and Fulfillment types with the internal, access-closed `method` field. SDK runtime behavior, collection buckets, request inputs, and public responses remain unchanged.
+- c246a93: Clarify generated Customer field descriptions for linked sign-in providers and password change times. Types and runtime behavior are unchanged.
+- 6b9d1ab: Use neutral short-summary comments in generated Payload types without prescribing where tenant apps display descriptions.
+- 8ae95f0: Give the SDK declaration build a bounded 4 GiB heap so release preparation can complete on hosted runners.
+- 2be5e90: Remove unused package-local prerelease publishing commands. Package publication continues through the owner-dispatched trusted publishing workflow.
+- f776ca2: Clarify the generated Return field descriptions for return details, cancellation actors, refund receipts, and original shipping refunds.
+- e1ba296: Synchronize generated PaymentSession types with the private, nullable Standard long-tail detection history field. SDK runtime behavior, collection buckets, and public projections remain unchanged.
+- 9159e72: Clarify the generated customer type documentation for server-recorded hosted consent history. Runtime behavior and public type shapes are unchanged.
+- 9a92a2d: Update generated collection descriptions to match the Console coupon navigation and explain checkout discounts and redemption coupon definitions. Public types and runtime behavior are unchanged.
+
 ## 0.71.0
 
 ### Minor Changes

package/README.md

@@ -933,6 +933,32 @@ request UUID and the current version; exact retries retain the original values.
 A privacy-erased snapshot has state `erased`, null `externalCustomerId`, and
 null `previousState`. Keep these calls and snapshots in trusted server code.
 
+### Delegated billing ciphertext
+
+The server client obtains the Console-owned restore generation through the
+existing custody endpoint, using its server key and delegated connection HMAC:
+
+```ts
+const { generation } = await server.memberships.billingCustodyContext({
+  membershipId,
+  webhookSecret,
+})
+const stored = await server.memberships.billingCustody({
+  action: 'read',
+  membershipId,
+  webhookSecret,
+  generation,
+})
+```
+
+Keep that generation and `stored.version` for mutations based on this read.
+Obtain a context immediately before a fresh initial upload (`expectedVersion: 0`).
+Generation mismatch stops execution; never fetch a new context to retry an old
+mutation or charge. After recovery, provider re-authorization and a fresh encrypted
+upload/readback are required. Existing explicit-generation requests remain
+supported. Deploy Console support before SDK publication and upgraded template
+use; unsupported servers and malformed contexts fail without fallback.
+
 ## Storefront performance defaults
 
 - **PLP:** prefer `commerce.product.listingPage()` or `useProductListingPage()` (GET `/api/products/listing-groups/query/catalog`, CDN-cacheable, card-ready). Use `listingGroupsCatalog({ productIds })` only when IDs are already known. Treat the full listing-groups response shape as a server-auth escape hatch because it can include operational stock fields. Avoid fetching a product list and then calling `detail()` per card.
@@ -959,6 +985,12 @@ Refund and refund-line-item collection reads remain server-only. Their public
 types and native reads omit private funding fields, including populated refund
 relationships. Generated storage types do not grant access to those fields.
 
+Server-only customer documents and customer-update webhooks retain
+`lifetimeValue?: number | null`. The scalar sums original order totals only
+for one verified registry currency with a numeric exponent; mixed or unavailable
+currencies yield `null`, and no contributing orders yield `0`. Currency bucket
+fields are not added. Existing webhook bodies and replay bytes stay unchanged.
+
 ### `depth` — how deep to populate relationship fields
 
 `depth` is the primary control for populating relationships like `category`, `images`, `brand`. Browser publishable-key raw collection reads are constrained to `depth: 0` with `joins: false` and no `populate`; relationship-rich storefront reads should use shaped helpers such as `commerce.product.detail()` / `listingPage()`, or a `createServerClient()` raw query when server credentials are appropriate. Browser SDK raw reads add those safe defaults automatically and reject relationship-expanded raw read options before making a request.
@@ -1623,7 +1655,11 @@ Cart add/update/remove/clear/discount/attribute mutations additionally require
 the last observed `cart.revision` as `expectedRevision`. A
 `cart_revision_conflict` means refetch the Cart and start a new logical mutation
 with a new idempotency key. Cart merge requires the key but not a single revision
-because it atomically resolves two current Cart states.
+because it atomically resolves two current Cart states. Merging a Cart the
+customer already owns returns `resolution: 'unchanged'` and writes nothing, so
+the revision you last observed stays valid for the next mutation. Because it
+writes nothing, such a merge does not count as Cart activity for stale-Cart
+cleanup.
 Treat a replayed Cart result as an operation receipt: never replace a newer
 cached Cart with a lower `revision`; retrieve when response ordering is unclear.
 
@@ -1779,6 +1815,16 @@ authoritative API response or signed webhook, then report the exact captured
 identity and Money. The create response is intentionally limited to
 `{ id, provider, providerSessionId, money }`.
 
+The closed managed provider vocabulary is `'toss' | 'portone' | 'stripe'`.
+`'stripe'` is reserved so that consumers upgrade before the server can emit it:
+Checkout references accept `provider: 'stripe'`, while the PaymentSession
+methods (`create`, `createPortOne`, `retrieve`, `retrievePortOne`, `cancel`,
+`cancelPortOne`, and server `confirm`) reject a Stripe session after validating
+it completely, with a generic invalid-response error carrying
+`details.expected` and `details.actual`. Stripe is not available yet, and the
+SDK has no Stripe PaymentSession method. Custom bridge provider names are a
+separate namespace and are unaffected.
+
 Custom bridge sessions intentionally remain `null` in
 `checkout.paymentState.activePaymentSession`: Checkout exposes only managed
 adapters from its closed provider vocabulary. Persist the `providerSessionId`
@@ -1926,6 +1972,16 @@ Do not infer the external lane from a defaulted `sessionOrigin`, an
 captures must use Console's refund operation; `resolveCancelRefund` remains
 only for the two external-drain rows above.
 
+For a registered managed Toss capture without customer credit, `cancelOrder()`
+no longer returns `refundPending`: Console refunds the payment after the local
+cancel commits and returns `managedRefund.outcome`. `completed` means the
+provider refund and the cancel refund ledger are committed;
+`convergence_pending` means Console still owns the refund and continues it;
+`operator_required` means it needs operator review in Console. Treat all three
+as a committed cancellation and never start a provider refund from your
+storefront or BFF. A retry reads or resumes the same Console refund. Registered
+PortOne and credit-funded managed orders still return the pending marker.
+
 Managed ownership follows the captured Transaction's exact tenant-bound
 PaymentSession and historical registered account. Order/provider/environment
 drift remains Console-owned corruption. Unresolved or cross-tenant identity
@@ -2298,6 +2354,20 @@ replacement API. Pass an empty list to clear codes. Singular `admission`,
 Browser `mine()`/`merge({ guestCartToken })` derive customer identity from the
 JWT; server calls require an explicit `customerToken`.
 
+### Event admission availability
+
+For paid admission choices, call
+`client.events.getAdmissionAvailability({ occurrence, market: 'kr' })` with an
+active market handle or id. Omit `market` for the catalog default. The public
+price includes `amount`, `compareAtPrice`, `currency`, and `marketId` resolved
+from fixed market prices or the market calculation; an unknown market returns
+`404 not_found`. Use the same market for the Cart. Checkout re-reads current
+pricing and eligibility. When a market resolves, admission types are returned
+only when their same-tenant product is assigned to that market. This filter also
+applies to existing calls that omit `market` and use the default market; missing
+products and empty assignments are omitted. With no active market, base pricing
+and the existing unfiltered behavior remain.
+
 ### Customer event registration history
 
 After customer sign-in, `client.events.listMyRegistrations({ page: 1, limit: 10 })`

package/dist/client.cjs

@@ -896,7 +896,7 @@ async function httpFetch(url, options) {
           );
           const usageError = attachRequestId(
             createUsageLimitError(
-              `Monthly API usage limit exceeded (${current.toLocaleString()}/${limit.toLocaleString()})`,
+              `Monthly API usage limit exceeded (${current.toLocaleString("en-US")}/${limit.toLocaleString("en-US")})`,
               { limit, current, remaining },
               {
                 url,
@@ -2613,7 +2613,18 @@ var ABANDONED_REASONS = ["expired", "customer", "operator"];
 function managedPaymentProviders(providers) {
   return providers;
 }
-var PAYMENT_PROVIDERS = managedPaymentProviders(["toss", "portone"]);
+var PAYMENT_PROVIDERS = managedPaymentProviders([
+  "toss",
+  "portone",
+  "stripe"
+]);
+var CANCEL_RECOVERY_METHODS = {
+  toss: "cancel()",
+  portone: "cancelPortOne()",
+  stripe: null
+};
+var STRIPE_RETURN_URL_RAW_CHARACTERS = /^[^\s\u0000-\u001F\u007F\\]+$/;
+var STRIPE_RETURN_URL_AUTHORITY = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/?#@]+(?:[/?#]|$)/;
 var PAYMENT_PROVIDER_STATUSES = [
   "requires_payment_method",
   "requires_action",
@@ -2662,11 +2673,8 @@ function fail(resource, path, expected) {
   invalidCanonicalResponse(resource, { path, expected });
 }
 function providerMismatch(resource, expected, actual, operation2) {
-  if (operation2 === "cancel") {
-    const method = {
-      toss: "cancel()",
-      portone: "cancelPortOne()"
-    }[actual];
+  const method = CANCEL_RECOVERY_METHODS[actual];
+  if (operation2 === "cancel" && method !== null) {
     throw createApiError(
       `Canonical ${resource} response provider mismatch: expected ${expected}, received ${actual}.`,
       502,
@@ -3910,6 +3918,65 @@ function validateRequiredReconciliation(value, allowed, resource, path) {
 }
 function validateNextAction(value, provider, resource, path) {
   const action = record(value, resource, path);
+  if (provider === "stripe") {
+    exact(
+      action,
+      ["type", "clientSecret", "publishableKey", "returnUrl"],
+      [],
+      resource,
+      path
+    );
+    if (action.type !== "stripe_payment_element")
+      fail(resource, `${path}.type`, "stripe_payment_element");
+    const clientSecret = boundedString(
+      action.clientSecret,
+      255,
+      resource,
+      `${path}.clientSecret`
+    );
+    if (!/^pi_[A-Za-z0-9]+_secret_[A-Za-z0-9]+$/.test(clientSecret)) {
+      fail(
+        resource,
+        `${path}.clientSecret`,
+        "Stripe PaymentIntent client secret"
+      );
+    }
+    const publishableKey = boundedString(
+      action.publishableKey,
+      255,
+      resource,
+      `${path}.publishableKey`
+    );
+    if (!/^pk_(?:test|live)_[A-Za-z0-9]+$/.test(publishableKey)) {
+      fail(resource, `${path}.publishableKey`, "Stripe publishable key");
+    }
+    const returnUrl = boundedString(
+      action.returnUrl,
+      2048,
+      resource,
+      `${path}.returnUrl`
+    );
+    if (!STRIPE_RETURN_URL_RAW_CHARACTERS.test(returnUrl) || !STRIPE_RETURN_URL_AUTHORITY.test(returnUrl)) {
+      fail(
+        resource,
+        `${path}.returnUrl`,
+        "HTTPS or loopback URL without embedded credentials"
+      );
+    }
+    try {
+      const parsed = new URL(returnUrl);
+      const loopback = parsed.protocol === "http:" && (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1");
+      if (!loopback && parsed.protocol !== "https:" || parsed.username || parsed.password)
+        throw new Error("unsafe return URL");
+    } catch {
+      fail(
+        resource,
+        `${path}.returnUrl`,
+        "HTTPS or loopback URL without embedded credentials"
+      );
+    }
+    return;
+  }
   if (provider === "portone") {
     if (action.type === "portone_sdk") {
       const hasCancelable = "cancelable" in action;
@@ -4285,7 +4352,7 @@ function validatePublicPaymentSession(value, expectedProvider, operation2) {
     );
   }
   if (expectedProvider !== void 0 && provider !== expectedProvider) {
-    if (operation2 === "cancel" && status !== "canceling" && status !== "canceled") {
+    if (operation2 === "cancel" && CANCEL_RECOVERY_METHODS[provider] !== null && status !== "canceling" && status !== "canceled") {
       fail(
         resource,
         "$.providerStatus",
@@ -5546,6 +5613,11 @@ function getRelationID(value) {
   }
   return void 0;
 }
+function compareOrdinal(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
 function extractEntityId(value) {
   if (typeof value === "string") return value;
   if (typeof value === "number") return String(value);
@@ -6158,7 +6230,7 @@ function compareVariantOrder(a, b) {
   }
   const aId = String(getRelationID(a.id) ?? "");
   const bId = String(getRelationID(b.id) ?? "");
-  return aId.localeCompare(bId);
+  return compareOrdinal(aId, bId);
 }
 function getVariantAvailableForSale(variant) {
   if (variant.isActive === false) return false;
@@ -6763,6 +6835,8 @@ function buildRangeEndpoint(params) {
 function buildAdmissionAvailabilityEndpoint(params) {
   const urlParams = new URLSearchParams();
   urlParams.set("occurrence", params.occurrence);
+  const normalizedMarket2 = params.market?.trim();
+  if (normalizedMarket2) urlParams.set("market", normalizedMarket2);
   return resolveOperationPath(
     EVENTS_ENDPOINT_OPERATIONS.occurrences.admissionAvailability,
     { query: urlParams }