@01.software/sdk 0.71.0 → 0.72.1

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @01.software/sdk
 
+## 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

@@ -959,6 +959,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 +1629,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 +1789,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 +1946,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

package/dist/client.cjs

@@ -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",