@01.software/sdk 0.70.1 → 0.72.1

package/CHANGELOG.md

@@ -1,5 +1,148 @@
 # @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
+
+- b8af85e: Expose `shipping_address_required` as a typed commerce error reason when Checkout creation rejects shippable lines without a valid request or stored Cart address.
+- e48864c: Add an optional `locale` (`en` or `ko`) to server collection `create()`, `update()`, and `updateMany()`, sent as Payload's `locale` query parameter, so workspaces that enable only `ko` (the Korean onboarding default) can write localized collections. Calls without `locale` send the same request as before. Raw collection errors now expose a Payload `errors[0].data.code` (or `.reason`) as `SDKError.apiReason` when the body has no top-level reason, so `getSDKErrorReason()` identifies `content_locale_not_enabled`; error classes, `code`, and retry behavior are unchanged.
+- d65f43d: Add explicitly negotiated embedded admin collection actions with signed execution context, fixed deadlines and a claim-only durable receiver verification contract. Preserve v1 settings helpers and add CLI action configuration with omission-preserves semantics.
+- 0ded572: Add binding-scoped, default-off embedded admin downloads. Configure with
+  `--allow-downloads` to opt in; full configure without it resets downloads to
+  false on supporting servers. Omit the request field when no download option is
+  supplied for released-server compatibility; `--no-allow-downloads` explicitly
+  sends false. Normalize legacy configuration/readback to false while retaining the
+  version-1 receiver protocol and PAT-only management boundary.
+- 96360d8: Add the server-only membership subscribe intent termination operation.
+- 0d0d8ec: **BREAKING (0.x minor), TypeScript types only.** Prepare strict Cart, Checkout
+  and Order response readers for the complete pickup response shapes while
+  continuing to accept the released server shapes. `PublicCart`,
+  `PublicCheckout`, `ServerCheckout`, `CheckoutListItem` and `PublicOrder` become
+  unions of both shapes; narrow with `'deliveryMethod' in resource`. Because
+  `PublicCart` and `PublicOrder` were object types, an `interface` extending them
+  (TS2312) or a `class` implementing them (TS2422) no longer compiles. Use an
+  intersection type alias (`type AppOrder = PublicOrder & { ... }`), or extend or
+  implement one generation selected with `Exclude`/`Extract` on
+  `{ deliveryMethod: unknown }`; a class cannot implement the intersection, which
+  is still a union. Runtime response acceptance only widens.
+
+  Partial field sets, incomplete pickup projections and unknown fields are
+  rejected, including in envelopes and list entries. Existing response fields,
+  inputs, method signatures, money, source, PortOne action and credit funding
+  semantics are unchanged; no pickup commands, inputs or reasons are added and
+  servers do not emit the new fields yet. The later server default-response
+  cutover (#7760) is a separate breaking semantic contract change that older
+  strict SDKs reject; its Changeset records the actual first published compatible
+  SDK and support floor from `docs/packages/sdk-pickup-response-rollout.md`.
+
+- 57519f0: Add server-only template credit grant, revoke and account readback, customer balance and history reads, and optional Checkout credit input. Checkout funding uses an exact versioned Accept opt-in while legacy responses remain compatible. Missing funding remains unknown, and credit requests never fall back to non-credit checkout.
+
+  Allow an omitted Return refund capture ID only for an original full-credit Order with zero frozen provider payable. Mixed Orders still require the original capture identity, including credit-only refund remainders; existing server money and credential authority remains unchanged.
+
+  Preserve the ordinary refund missing-capture-ID 400 response, reject missing and foreign grant Customers identically, keep account reads from advancing mutation revisions, and return retryable 503 for unavailable Checkout funding readback.
+
+### Patch Changes
+
+- a8a2312: Preserve the current in-memory access and refresh token pair when cloning a
+  `persist: false` client with `withMarket()`, including sessions established by
+  login, rotated sessions, and cleared credentials.
+- 4f1fa0a: Synchronize generated Cart, Checkout, and Order types with the internal, access-closed `deliveryMethod` field. SDK runtime behavior, collection buckets, request inputs, and public responses remain unchanged.
+- eb636d1: Refresh generated commerce field descriptions for returns, carts, and checkouts.
+- dd223b8: Document once-per-customer/plan Membership trials, preserved intent snapshots,
+  and paid preparation confirmation before tenant PSP execution. No SDK runtime,
+  export, or wire shape changes.
+- bc0f481: Synchronize generated PaymentSession and PaymentEventInbox types with two private, nullable payment detection history fields. SDK runtime behavior, collection buckets, and public projections remain unchanged.
+- b61a4b0: Synchronize generated PaymentRefundAttempt types and field selectors with the internal `not_sent_rejected` status and the private, write-once `returnRejection` proof (`gate` and `rejectedAt`). SDK runtime behavior, collection buckets, and public projections remain unchanged.
+- c65e931: Synchronize the optional tenant workspace management IP policy in generated
+  Payload types. This does not add an SDK method or expose the policy to public
+  or service-key callers.
+- 590e41e: Sync generated Tenant types with collection-specific Admin Panel export policy settings.
+- 750a403: Clarify generated Customer order-count documentation: pending orders contribute, while canceled, refunded, returned, test and trashed orders do not.
+
 ## 0.70.1
 
 ### Patch Changes

package/MIGRATION.md

@@ -1,5 +1,33 @@
 # @01.software/sdk Migration Notes
 
+## Pickup response compatibility preparation (#7756)
+
+This SDK reads both the released and the complete final Cart, Checkout and Order
+responses; servers still return the released shape and pickup remains
+unavailable. `PublicCart`, `PublicCheckout`, `ServerCheckout`,
+`CheckoutListItem` and `PublicOrder` are unions of the two shapes. The new
+fields arrive only as a complete set per resource, so narrow with
+`'deliveryMethod' in resource` before reading them. Partial sets, incomplete
+pickup projections and unknown fields fail closed, also in envelopes and lists.
+No field is synthesized for released servers. Existing `amounts`, Cart
+`estimatedTotalMinor` (still excluding shipping), PortOne action negotiation and
+credit funding semantics are unchanged.
+
+This is a `BREAKING (0.x minor)` change for TypeScript types only; runtime
+response acceptance only widens. `PublicCart` and `PublicOrder` were object
+types, so an `interface` extending them (TS2312) or a `class` implementing them
+(TS2422) no longer compiles. Use an intersection type alias
+(`type AppOrder = PublicOrder & { ... }`), or select one generation with
+`Exclude<PublicOrder, { deliveryMethod: unknown }>` (released) /
+`Extract<PublicOrder, { deliveryMethod: unknown }>` (cutover) before extending
+or implementing it. The intersection is still a union, so a class must
+implement a selected generation.
+`PublicCheckout` was already a union. The later server cutover (#7760) is a
+separate breaking contract change for older strict SDKs: upgrade to this SDK or
+later before it. See the
+[response matrix and pending publication record](../../../docs/packages/sdk-pickup-response-rollout.md)
+for the exact field sets, version/support-floor placeholders and cutover gate.
+
 ## Product media compatibility shim retirement (#721)
 
 This is a `BREAKING (0.x minor)` change. The ADR 0025 one-release compatibility

package/README.md

@@ -17,7 +17,7 @@ pnpm add @01.software/sdk
 - React Query integration (both Client and ServerClient)
 - Mutation hooks (useCreate, useUpdate, useRemove) with automatic cache invalidation
 - Customer auth hooks (useCustomerMe, useCustomerLogin, etc.) with cache management
-- Automatic retry with exponential backoff (non-retryable: 400, 401, 403, 404, 409, 422)
+- Automatic failure retries for safe methods (`GET`, `HEAD`, `OPTIONS`) after network/timeout failures and retry-eligible HTTP failures (defaults: 408/500/502/503/504), within the SDK's bounded retry budget and with bounded backoff (exponential by default). GET already retries; avoid stacking an outer retry loop. A rate-limit 429 is terminal (`RateLimitError`; usage-quota 429 remains `UsageLimitError`). Unsafe mutations are not automatically retried after these failures.
 - Webhook handling with HMAC-SHA256 signature verification
 - Sub-path imports (`./server`, `./webhook`, `./realtime`, `./storefront-cache`, `./ui/*`) for tree-shaking
 - Type-safe read-only `collections.from()` for Client (compile-time write prevention)
@@ -151,6 +151,30 @@ CLI (`01 embedded-app configure`) with a user-scoped PAT. Binding management is
 an operator control-plane action and is intentionally not exposed as a public
 SDK mutation facade. A tenant API key (`sk01_`) is rejected.
 
+Collection-list actions use the additive `receiveEmbeddedAdminExecution` browser
+helper and `verifyEmbeddedAdminExecution` server helper. Pin `frameUrl` and pass
+the actual action/collection/selected IDs/execution ID/deadline as `execution`.
+The verifier requires a claim-only `consumeExecution` callback backed by shared
+durable atomic storage, retained through `expiresAt+60`. It performs no business
+effects. False/throw/timeout/uncertain commit fails closed; verification also
+checks a fresh trusted clock after consume. Start effects only after successful
+return and apply app-owned business idempotency/transaction policy. Repeating an
+action is a new execution, not a retry of its business result.
+
+V2 explicitly negotiates `collection-actions` and has a purpose-specific audience
+(`urn:01-software:embedded-admin-execution:` plus the app origin); it cannot be
+verified as v1 identity. Its immutable 60-second prepare deadline is unchanged by
+reload or mint. V1 settings and helpers remain supported. These are context
+proofs, not delegated mutation authority or an exactly-once business service.
+Binding configuration adds optional `allowDownloads` for source compatibility;
+normalization always returns a boolean and defaults missing values to false.
+Downloads require explicit admin opt-in (`01 embedded-app configure
+--allow-downloads`). Full configure without the flag resets false, even after
+an opt-in. The receiver version-1 wire protocol remains unchanged. The setting
+grants an iframe capability; the app owns file encryption and password handling.
+Policy observation may replace/remove the frame, but cannot recall files,
+delivered data, or app-local sessions.
+
 Loopback HTTP is disabled by default. Only non-production fixtures may set
 `allowLoopbackHttp: true` on the receiver and verifier options.
 
@@ -771,19 +795,42 @@ const prepared = await server.memberships.subscribe({
 })
 
 if (prepared.status === 'incomplete') {
-  const expiresAt = Date.parse(prepared.firstCharge.expiresAt)
-  if (!Number.isFinite(expiresAt) || Date.now() >= expiresAt) {
-    throw new Error('First charge instruction expired or invalid')
+  // Show amount, currency and periodStart and obtain explicit paid consent.
+  if (await tenantPsp.confirm(prepared.firstCharge)) {
+    // The customer confirmation may outlast the preparation.
+    const expiresAt = Date.parse(prepared.firstCharge.expiresAt)
+    if (!Number.isFinite(expiresAt) || Date.now() >= expiresAt) {
+      throw new Error('First charge instruction expired or invalid')
+    }
+    await tenantPsp.charge({
+      idempotencyKey: prepared.firstCharge.idempotencyKey,
+      amount: prepared.firstCharge.amount,
+      currency: prepared.firstCharge.currency,
+    })
+    // Post the PSP outcome to Console's existing signed charge-result webhook.
   }
-  await tenantPsp.charge({
-    idempotencyKey: prepared.firstCharge.idempotencyKey,
-    amount: prepared.firstCharge.amount,
-    currency: prepared.firstCharge.currency,
-  })
-  // Post the PSP outcome to Console's existing signed charge-result webhook.
 }
 ```
 
+A customer receives a trial once per plan within the same tenant. Started
+positive-snapshot trials, including cancelled or archived ones, consume it;
+started legacy rows with null/absent snapshots conservatively consume it too.
+Unstarted failed/cancelled setups and paid-only zero snapshots do not. A catalog
+trial badge does not promise customer eligibility. A recipient's new intent
+returns the existing paid preparation, or `409 conflict` without lifecycle
+writes if no active delegated billing connection exists. Present its amount,
+currency and `periodStart`, keep the selected billing cycle visible, and obtain
+customer confirmation before PSP execution; no `periodEnd` is returned.
+Implement `tenantPsp.confirm` in your app's checkout flow. A refusal must result
+in no PSP call. Console preparation does not establish payment or consent.
+A completed trial replay keeps its cached result. Existing payload and live
+duplicate checks run first; another live Membership returns
+`409 duplicate_subscription`. An unfinished trial replay that passes those
+checks returns `409 idempotency_conflict` after another intent received the trial,
+without lifecycle writes, and preserves its snapshot. Use a new confirmed paid
+intent instead. Uncompleted setups expire through the existing sweeper; the
+Membership and charge evidence remain retained.
+
 `subscribeIntentKey` is sent as `X-Idempotency-Key`; it is not part of the JSON
 body. A paid response is `incomplete` and contains the immutable first-charge
 instruction. The tenant charges its PSP with `firstCharge.idempotencyKey`, then
@@ -798,6 +845,18 @@ activate the Membership, so the tenant handles any refund outside this API. Repl
 the same plan, price, customer reference, and idempotency key while the first
 charge is pending. A replay after settlement or `expiresAt` returns `409`
 instead of a payment instruction.
+Server applications can explicitly end a signup intent with
+`server.memberships.endSubscribeIntent({ customerId, subscribeIntentKey })`.
+Use the same tenant, customer, and intent key as the original subscribe. The
+key must contain 1–512 visible ASCII characters without whitespace; use an
+opaque random value without personal data. `ended` fences future creation for
+that intent; `existing` means the existing operation needs recovery. This call
+requires an `sk01_` key with membership write scope and does not cancel, alter,
+or charge an existing membership. An unsupported endpoint, transport error, or
+malformed response does not establish termination. A later subscribe blocked by
+the fence returns `409 intent_ended`; terminal-row replay may instead return its
+existing conflict.
+
 `memberships.me()` and browser `memberships.cancel()` require the customer JWT
 configured on the client. Refund webhook `refundedAmount` values are cumulative
 charge totals, not per-event deltas.
@@ -900,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.
@@ -1149,6 +1214,37 @@ await server.collections.from('articles').updateMany(where, data)
 await server.collections.from('articles').removeMany(where)
 ```
 
+Collection writes (`create`, `update`, `updateMany`) accept an optional
+`locale` (`en` or `ko`) that selects the content locale localized fields are
+written in; it is sent as Payload's `locale` query parameter. Omitting it keeps
+the request unchanged, and the server writes the platform default locale
+(`en`). A write has no locale rewrite, so a workspace without `en` enabled (the
+Korean onboarding default enables only `ko`) rejects an omitted or disabled
+write locale with HTTP 400 and `apiReason` `content_locale_not_enabled`.
+
+```typescript
+import { getSDKErrorReason, isSDKError } from '@01.software/sdk/errors'
+import { createServerClient } from '@01.software/sdk/server'
+
+const server = createServerClient({ publishableKey, secretKey })
+
+try {
+  const { doc } = await server.collections
+    .from('articles')
+    .create({ title: '공지' }, { locale: 'ko' })
+  await server.collections
+    .from('articles')
+    .update(doc.id, { title: '수정된 공지' }, { locale: 'ko' })
+} catch (error) {
+  if (
+    isSDKError(error) &&
+    getSDKErrorReason(error) === 'content_locale_not_enabled'
+  ) {
+    // Retry with a locale that is enabled for this workspace.
+  }
+}
+```
+
 Collection `find`, `count`, `updateMany`, and `removeMany` share filter validation.
 `equals: null` and `not_equals: null` retain their null meaning through Payload
 REST, including text fields; null-containing filters use Payload's native JSON
@@ -1533,10 +1629,24 @@ 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.
 
+Shipping Checkout creation requires a request `shippingAddress` or a valid
+stored Cart address whenever any line has `requiresShipping !== false`.
+`recipientName`, `phone`, `postalCode`, `address`, and `detailAddress` must be nonblank after trimming. Otherwise,
+Console returns HTTP 400 with the typed `shipping_address_required` reason;
+non-shipping-only Carts may omit the address. Request addresses take precedence.
+
+After `shipping_address_required`, adding an address to the same idempotency key
+changes the request fingerprint and returns `409 idempotency_conflict`. Start a
+new logical Checkout with a valid address and a new `idempotencyKey`.
+
 ```typescript
 import { createCommerceIdempotencyKey } from '@01.software/sdk'
 import { isCommerceSDKError } from '@01.software/sdk/errors'
@@ -1679,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`
@@ -1826,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
@@ -2527,6 +2657,12 @@ try {
 
 Error classes: `SDKError`, `ApiError`, `NetworkError`, `ValidationError`, `ConfigError`, `TimeoutError`
 
+Raw collection failures keep Payload's native body. When Payload reports a
+machine code as `errors[0].data.code` (or `.reason`) and the body has no
+top-level `reason`, the SDK exposes it as `SDKError.apiReason`, so
+`getSDKErrorReason()` returns codes such as `content_locale_not_enabled` without
+reading `details.body`. The typed error class and `code` stay status-based.
+
 A customer-token `401 token_expired` permits at most one configured token
 refresh. After a successful refresh, GET/HEAD/OPTIONS may be resent once
 independently of the transient retry budget, including `retry.maxRetries: 0`
@@ -2680,3 +2816,109 @@ Reuse the same sourceNamespace/sourceRef and identical issue input on an unknown
 The staff app server must verify the staff member and Customer before redeeming: voucherId is not a bearer capability. `actorRef` is app-attested evidence, never a platform-verified staff identity or an authorization input. Use opaque references without personal data in sourceRef and actorRef. Definitions snapshot name, description and expiry at issue; later edits do not change issued vouchers. Voucher history survives Customer erasure and blocks tenant hard deletion. Referenced definitions must be archived.
 
 Product purchase quantity policies are enforced by Console at Cart ingress and Checkout creation. A product's optional `maxQuantityPerCustomer` combines all variants, committed Orders minus completed Returns, and open Checkouts. Limited products require a verified Customer; delegated server purchases use the existing `customerToken`. Handle `409 purchase_limit_exceeded` by its scalar `details.productId`, `maxQuantityPerCustomer` and `remainingQuantity`; guests receive `product_not_eligible`. See the [Commerce guide](https://docs.01.software/en/commerce).
+
+## Customer credits
+
+In Console → Customer credits, a `tenant-admin` configures the default validity
+(1–1825 days), redemption cap (1–100%), and immutable fixed or bounded grant
+templates. Other tenant roles can read configuration and customer history.
+Archiving a template stops new grants; it preserves existing grant snapshots.
+Credit settings start disabled. Turning them off blocks new grants and credit
+reservations while preserving existing consumption, release, refund restoration,
+expiry, revocation and reads. This switch does not bypass ecommerce entitlement.
+
+Use a trusted tenant server with `sk01_` credentials for
+`server.credits.grant`, `getGrant`, `getAccount` and `revoke`. Grants and revocations
+require write scope; reads require read scope. Browser clients expose only
+`client.credits.mine()` and `client.credits.history({ page })` using the logged-in
+Customer session and publishable key. These pages contain at most 50 entries;
+balances and history amounts are decimal strings in KRW, including aggregates
+larger than JavaScript's safe integer range. Do not convert such aggregates to
+`Number`. Buckets distinguish original expiry from the one-time restoration
+grace period. A grace period lasts 168 hours and is never renewed.
+
+### Monthly grant recipe for an annual member
+
+The tenant owns its scheduler, membership eligibility and cancellation policy.
+Before running this function, verify that the member qualifies for the selected
+calendar month. An annual payment alone does not cause future monthly grants.
+
+```ts
+import { createServerClient } from '@01.software/sdk/server'
+
+type CreditServer = ReturnType<typeof createServerClient>
+
+export async function grantMembershipMonth(
+  server: CreditServer,
+  input: {
+    customerId: string
+    fixedTemplateId: string
+    membershipId: string
+    month: string
+  },
+) {
+  const source = {
+    sourceNamespace: 'membership-month',
+    sourceRef: `${input.membershipId}:${input.month}`, // month: YYYY-MM in the tenant's calendar
+  }
+  await server.credits.grant({
+    ...source,
+    customerId: input.customerId,
+    templateId: input.fixedTemplateId,
+  })
+  return server.credits.getGrant(source)
+}
+
+export async function revokeMembershipMonth(
+  server: CreditServer,
+  input: { membershipId: string; month: string },
+) {
+  return server.credits.revoke({
+    sourceNamespace: 'membership-month',
+    sourceRef: `${input.membershipId}:${input.month}`,
+  })
+}
+```
+
+Run missed eligible months with their original month identity; retry an uncertain
+request with exactly the same template, customer and source identity. Matching
+replay has one grant effect, even after configuration changes; changing that
+identity's payload conflicts. Fixed templates reject `amount`; bounded templates
+require an exact positive integer `amount` within their maximum. Revocation
+reports `revoked`, `pending` and `spent` separately, never creates debt, and routes
+later release or restoration to revoked funds. Deciding whether a membership
+cancellation or refund warrants revocation remains the tenant's responsibility.
+There is no platform cron, campaign engine, cash loading, transfer or cash-out.
+
+### Apply credit to the current Commerce Checkout
+
+Pass an exact positive safe-integer `creditAmount` with the existing Checkout
+create request and its original idempotency key. Credit needs verified Customer
+proof, active ecommerce, enabled credit settings, available balance and cap
+admission. No browser balance or Accept header is payment authority.
+
+The SDK opts into `application/vnd.01software.credit-funding.v1+json` for successful
+Checkout create/detail/query. Only this entire Accept value (trimmed,
+case-insensitive) opts in; lists, wildcards and parameters do not. The selected
+response uses that Content-Type and `Cache-Control: private, no-store`; errors
+retain their ordinary JSON type. The public `funding` object contains only
+`creditAmount` and `providerPayableAmount`. Show purchase total
+(`checkout.amounts.totalMinor`) separately from these credit and PG amounts.
+Full-credit placement needs no PaymentSession; mixed payment charges the frozen
+provider-payable amount. Refunds retain the original purchase split and restore
+only their attributed credit leg.
+
+Old servers reject the new credit input before business writes. The SDK never
+strips it, changes it to zero, probes a separate endpoint or retries without
+credit. A response without `funding` remains a legacy response with unknown
+funding support, not proof of zero credit. Missing or inconsistent funding after
+a credit create is an uncertain result: retrieve the Checkout or retry the exact
+same request with the original idempotency key. Never fall back to a full PG charge.
+
+For `server.commerce.orders.returnWithRefund`, omit `pgPaymentId` only if the
+original Order's frozen `provider_payable` is zero (a full-credit Order). A mixed
+Order requires its original capture identity even when the current refund has
+zero provider amount and restores credit only. A full-credit Order rejects any
+`pgPaymentId` or `paymentKey`; never invent an identifier. Explicit blank values
+remain invalid. Orders without credit funding retain `400/validation_failed`
+when `pgPaymentId` is omitted. Refund amount, credential, tenant and ecommerce authority remain unchanged.