@01.software/sdk 0.68.0 → 0.70.1

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @01.software/sdk
 
+## 0.70.1
+
+### Patch Changes
+
+- 063fa7b: Guarantee one safe request resend after a successful token_expired refresh independently of the transient retry budget, including maxRetries: 0 and expiry on the final attempt. Preserve the single-refresh bound, unsafe-method replay restriction, and typed errors with request IDs.
+
+  Keep the refreshed response's retry admission authoritative, including canonical retry denial and an excessive Retry-After hint, while retaining retries for actual transport failures.
+
+- 86272b6: Sync the generated Order return-status help with the Console display label
+  “No return”. Field types and stored status values are unchanged.
+- 45817d4: Synchronize generated Payload types for the internal `audit-logs` collection. `AuditLog` and `AuditLogsSelect` gain one optional, nullable `entryKey` field, a private deduplication digest that every caller-facing read denies.
+
+  Additive only. No collection becomes addressable, no existing field changes, and no SDK runtime behavior changes.
+
+- d2a88cd: Keep unavailable refund funding fields out of public collection types and
+  native reads, including populated refund relationships. Preserve existing
+  server-only collection availability, ordinary refund fields, and internal
+  funding evidence.
+
+  Exclude owning Refund metadata from caller responses and unavailable fields from
+  tenant schema discovery. Reject private metadata predicates, whole-metadata
+  comparisons other than existence, whole-metadata sorting (including subpath
+  sort spellings), and caller Local distinct over Refund metadata. These native
+  400 query errors preserve ordinary metadata subpath filters, non-metadata sorts,
+  server collection access and internal overrideAccess owning reads/replay.
+
+## 0.70.0
+
+### Minor Changes
+
+- e5849e7: Preserve `admission_not_eligible`, `admission_eligibility_unavailable`, `admission_authority_unavailable`, `admission_customer_binding_required`, and `admission_eligibility_unproven` as typed commerce error reasons across Cart, Checkout, and PaymentSession operations. Their existing meanings and HTTP statuses are unchanged. Older SDKs retain unrecognized reasons as `unknown_commerce_error` with `rawReason`.
+
+### Patch Changes
+
+- 729e6cc: Synchronize generated internal Refund types with frozen funding attribution and optional capture linkage for refunds without a provider leg. Public credit operations remain unavailable.
+- 6e7f1e3: Sync the generated customer collection documentation with its neutral Admin description.
+- c93137c: Use the shared HTTP operation manifest for the existing event registration and guest helpers, preserving their request signatures and terminal rate-limit errors.
+- 054184f: After a token-expired 401, refresh the customer token but resend the original request only for GET, HEAD, or OPTIONS. Unsafe requests retain the original authentication error so callers can explicitly retry.
+
+## 0.69.0
+
+### Minor Changes
+
+- 88a5db7: 상품의 고객별 누적 구매 한도 타입과 `purchase_limit_exceeded` 오류 reason을 추가합니다.
+
+  운영 주의: 애플리케이션을 rollback하면 이 상한 집행이 사라집니다. **rollback 전 한도 상품 판매 중지**가 필요합니다. 스키마 마이그레이션은 forward-only이며, 컬럼·미검증 CHECK 추가 → CHECK 검증 → 트랜잭션 밖 동시 인덱스 생성 순서로 적용합니다.
+
+- 349785e: Add the `product_not_eligible` commerce reason for products restricted to eligible Customer Groups. Restricted purchases require a Customer-bound Cart and verified Customer session or server delegation; unrestricted products retain existing behavior.
+- 7488329: Add the stable `admission_required` error reason for public event registration.
+  RSVP/approval registration now rejects applicable non-deleted admission types,
+  including inactive, out-of-sale and zero-price types. Use the admission purchase
+  flow for these events; the SDK preserves the 409 reason without retrying.
+
 ## 0.68.0
 
 ### Minor Changes

package/README.md

@@ -80,7 +80,7 @@ entry.
 | `@01.software/sdk/ui/form`               | `FormRenderer`                                                           | `react`, `react-dom`                                                                                       |
 | `@01.software/sdk/ui/code-block`         | `CodeBlock`, `highlight`                                                 | `react`, `react-dom`, `shiki`, `hast-util-to-jsx-runtime`                                                  |
 | `@01.software/sdk/ui/canvas`             | `CanvasRenderer`, `CanvasFrame`, `useCanvas`, `prefetchCanvas`           | `react`, `react-dom`, `@tanstack/react-query`, `@xyflow/react`, `quickjs-emscripten`, `postcss`, `sucrase` |
-| `@01.software/sdk/ui/canvas/server`      | canvas server helpers                                                    | none                                                                                                       |
+| `@01.software/sdk/ui/canvas/server`      | canvas server helpers                                                    | `postcss` >=8 (optional peer)                                                                              |
 | `@01.software/sdk/ui/video`              | `VideoPlayer`                                                            | `react`, `react-dom`, `@mux/mux-player-react`                                                              |
 | `@01.software/sdk/ui/image`              | `Image`                                                                  | `react`, `react-dom`                                                                                       |
 
@@ -896,6 +896,10 @@ const query = createQueryHooks(client, getStorefrontQueryClient())
 
 Most consumers should use the helper APIs above (`commerce.product.detail`, etc.). The query builder below is the escape hatch for advanced cases the helpers do not cover: bulk operations, custom filter combinations, or fields the helper response does not expose.
 
+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.
+
 ### `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.
@@ -1509,11 +1513,14 @@ their state fields before reading state-specific data such as `nextAction` or
 customer JWT when a resource is customer-bound. Server calls use the secret
 credential and never expose provider secrets in returned DTOs.
 
-Browser and server commerce writes use separate transports even when their JSON
-shapes match. `createServerClient()` routes every Cart operation, Checkout
-create/retrieve/query, and PaymentSession create/retrieve/cancel/confirm through
-the resource-owned `/server/*` namespace. Public paths retain only their exact
-capability/customer bodies and never advertise the server credential.
+Cart and Checkout browser/server aliases reuse the same registered operations
+in their respective credential contexts; sharing an endpoint does not grant the
+same permissions. SDK alias mappings follow the `@01.software/http-contracts`
+manifest. Managed PaymentSession server operations use the resource-owned
+`/server/*` transport, while the server-only custom PaymentSession bridge uses
+separate orders-owned manifest operations. Keep Secret Keys on trusted servers;
+public calls retain their capability/customer bodies and never include server
+credentials.
 
 Generate one idempotency key per logical mutation, persist it with the pending
 operation, and reuse it after timeouts or lost responses. Creating a fresh key
@@ -2023,7 +2030,7 @@ your own baseline, retaining every option, value, and variant you intend to
 keep. Media IDs must already belong to the saved product's image pool.
 
 ```ts
-await client.commerce.product.upsert({
+await server.commerce.product.upsert({
   productId: 'prod_123',
   graphRevision: draft.graphRevision,
   options: [
@@ -2520,6 +2527,18 @@ try {
 
 Error classes: `SDKError`, `ApiError`, `NetworkError`, `ValidationError`, `ConfigError`, `TimeoutError`
 
+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`
+or expiry on the final attempt. This does not reset the transient retry budget.
+Another 401 returns its typed authentication error and request ID without a
+second refresh; unsafe methods return the original authentication error without
+resending the request.
+
+After refresh, a canonical commerce response with `retryable: false` or no
+`retryable` field, or a `Retry-After` beyond the automatic wait bound, returns
+its typed error and request ID without another automatic retry.
+
 ## Environment Variables
 
 ```bash
@@ -2659,3 +2678,5 @@ Reuse the same sourceNamespace/sourceRef and identical issue input on an unknown
 `client.benefitVouchers.listMine({ status: 'available', limit: 20 })` uses the Customer JWT and returns only identity, customer-visible copy, state and timestamps. Use `status: 'all'` for history and the returned `nextCursor` for another page (maximum 100). The response is private, no-store. Server lists return the server DTO and require customerId; cross-customer/tenant targets are masked as 404. Console customer detail shows a read-only list; Console action buttons follow separately.
 
 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).

package/dist/client.cjs

@@ -153,7 +153,13 @@ var COMMERCE_ERROR_CODES = [
   "checkout_reservation_release_requires_transaction",
   "admission_metadata_invalid",
   "admission_metadata_required",
+  "admission_not_eligible",
+  "admission_eligibility_unavailable",
+  "admission_authority_unavailable",
+  "admission_customer_binding_required",
+  "admission_eligibility_unproven",
   "capacity_exceeded",
+  "admission_required",
   "occurrence_lock_unavailable",
   "occurrence_not_open",
   "admission_type_capacity_exceeded",
@@ -172,6 +178,8 @@ var COMMERCE_ERROR_CODES = [
   "variant_inactive",
   "variant_product_mismatch",
   "product_not_public",
+  "product_not_eligible",
+  "purchase_limit_exceeded",
   "market_not_found",
   "market_shipping_currency_unsupported",
   "missing_market_rate",
@@ -819,6 +827,7 @@ async function httpFetch(url, options) {
   let lastError;
   let hasRetried401 = false;
   for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
+    let terminalResponseError;
     try {
       const headers = new Headers(requestInit.headers);
       if (publishableKey) {
@@ -887,8 +896,9 @@ async function httpFetch(url, options) {
           hasRetried401 = true;
           try {
             const newToken = await onUnauthorized();
-            if (newToken) {
+            if (newToken && SAFE_METHODS.includes((requestInit.method || "GET").toUpperCase())) {
               authToken = newToken;
+              attempt--;
               continue;
             }
           } catch {
@@ -921,11 +931,15 @@ async function httpFetch(url, options) {
           await delay(retryDelay);
           continue;
         }
+        terminalResponseError = error;
         throw error;
       }
       return response;
     } catch (error) {
       debugLog(debug, "error", url, error);
+      if (terminalResponseError && error === terminalResponseError) {
+        throw error;
+      }
       const method2 = (requestInit.method || "GET").toUpperCase();
       const isSafe = SAFE_METHODS.includes(method2);
       if (error instanceof Error && error.name === "AbortError") {
@@ -1337,6 +1351,15 @@ var EMBEDDED_ADMIN_ENDPOINT_OPERATIONS = {
 };
 var EVENTS_ENDPOINT_OPERATIONS = {
   registrations: {
+    register: operation("event-registrations", "post", "/register"),
+    guestLookup: operation("event-registrations", "post", "/guest/lookup"),
+    guestLookupByUrl: operation("event-registrations", "get", "/guest/:token"),
+    guestCancel: operation("event-registrations", "post", "/guest/cancel"),
+    guestCancelByUrl: operation(
+      "event-registrations",
+      "post",
+      "/guest/:token/cancel"
+    ),
     listMine: operation("event-registrations", "get", "/my")
   },
   events: {
@@ -6355,24 +6378,32 @@ var EventsClient = class {
   }
   register(params) {
     return this.execute(
-      "/api/event-registrations/register",
-      "POST",
+      resolveOperationPath(EVENTS_ENDPOINT_OPERATIONS.registrations.register),
+      resolveOperationMethod(EVENTS_ENDPOINT_OPERATIONS.registrations.register),
       buildRegistrationRequestBody(params),
       { useCustomerAuth: true }
     );
   }
   getGuestRegistration(token) {
     return this.execute(
-      "/api/event-registrations/guest/lookup",
-      "POST",
+      resolveOperationPath(
+        EVENTS_ENDPOINT_OPERATIONS.registrations.guestLookup
+      ),
+      resolveOperationMethod(
+        EVENTS_ENDPOINT_OPERATIONS.registrations.guestLookup
+      ),
       { token },
       { useCustomerAuth: false }
     );
   }
   cancelGuestRegistration(token, params = {}) {
     return this.execute(
-      "/api/event-registrations/guest/cancel",
-      "POST",
+      resolveOperationPath(
+        EVENTS_ENDPOINT_OPERATIONS.registrations.guestCancel
+      ),
+      resolveOperationMethod(
+        EVENTS_ENDPOINT_OPERATIONS.registrations.guestCancel
+      ),
       buildGuestCancelRequestBody(token, params),
       { useCustomerAuth: false }
     );