@01.software/sdk 0.65.1 → 0.68.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # @01.software/sdk
 
+## 0.68.0
+
+### Minor Changes
+
+- 0211dc7: Add server benefitVouchers issue/get/list/redeem/voidVoucher commands and Customer listMine. Vouchers are single-use non-monetary benefits; source identity and request UUIDs make explicit retries safe.
+- 0211dc7: Support explicit embedded app execution-role opt-in on both the tenant binding
+  and receiver verifier, preserving administrator-only defaults. Add CLI
+  allowed-role configuration and binding-state readback.
+
+### Patch Changes
+
+- 342cda2: Sync the generated benefit voucher definition documentation with its bilingual Admin description.
+
+## 0.67.0
+
+### Minor Changes
+
+- 79bec7b: Add events.listMyRegistrations() for paginated customer-authenticated event registration history with a PII-free DTO.
+
+  BREAKING (0.x minor): `createServerClient().events` now returns an object facade instead of an `EventsClient` instance, excluding the customer-only `listMyRegistrations` method. The existing `getRange`, `getAdmissionAvailability`, `register`, `getGuestRegistration`, and `cancelGuestRegistration` calls remain supported. Consumers that accept server event helpers should import `RootServerClientWithEvents` from `@01.software/sdk/server` and use `RootServerClientWithEvents['events']` instead of `EventsClient`. Replace `instanceof EventsClient` checks with checks for the methods they need (for example, `typeof events.getRange === 'function'`). For customer registration history in a server BFF, create a request-scoped `createClient({ publishableKey, customer: { persist: false, token } })`.
+
+### Patch Changes
+
+- 6d58a9c: Fix compiled Canvas template nodes with transparent backgrounds so their slug scope and transparent background classes remain separate tokens.
+- 40d78bd: Sync generated types for the optional, operator-only virtual adminTitle on commerce config and tenant metadata. Storefront metadata reads and persisted fields are unchanged.
+
+  Private singleton titles are omitted from publishable-key, customer, and service-credential responses, including requests with a coincident Console session. They use the response document's tenant authority. GraphQL returns null when this denied optional field is explicitly selected.
+
+- 5662849: Clarify the generated Link clickCount documentation: the field is read-only, and Console does not currently collect clicks automatically. Stored fields and access rules are unchanged.
+
+## 0.66.6
+
+### Patch Changes
+
+- 0599ab4: 기존 CustomerAuth 요청의 path/method를 공통 HTTP manifest에 연결합니다. 등록·로그인·refresh·profile·password 요청의 body, 인증, 응답 및 세션 동작은 유지합니다.
+
+## 0.66.5
+
+### Patch Changes
+
+- 604f443: Refresh generated community ban types to match the Admin Panel field order and temporary expiry guidance. The field types and API behavior are unchanged.
+
+## 0.66.4
+
+### Patch Changes
+
+- ed09398: Clarify that a blank sender display name uses the workspace name for commerce and event notifications, and document the hosted sign-in logo URL fallback.
+- c7b8803: Regenerate membership plan Payload declarations to match the Admin Panel's basic information field order. Field names, types, and fallback semantics are unchanged.
+- e879ec4: Update generated type documentation comments to call the account boundary a workspace in English descriptions. Type names, field names, collection slugs, and runtime behavior are unchanged.
+
+## 0.66.3
+
+### Patch Changes
+
+- 35568b4: Map stored video aspect-ratio enums to valid CSS ratios for VideoPlayer placeholders and ready players, preserving the 16/9 default and explicit style overrides. A stored ratio is now a valid inline `aspect-ratio`, so it takes precedence over an aspect ratio set through `className`; use `style.aspectRatio` or `placeholderStyle.aspectRatio` to override it.
+
+## 0.66.2
+
+### Patch Changes
+
+- 055cb8d: Synchronize generated internal payment-account types with optional Commerce market assignments. Account management remains SDK-internal; this adds no public payment API.
+
+## 0.66.1
+
+### Patch Changes
+
+- 8abfca5: Clarify that live-stream counters expose stored values and are not automatically aggregated by Console.
+- 167f186: Clarify generated customer address field guidance comments.
+
+## 0.66.0
+
+### Minor Changes
+
+- 29f068e: Add server-only `commerce.product.graphRevision` and `updateVariantPrices` for updating existing variant base prices without submitting the complete product graph. Keep one explicit content locale while reading the baseline, reviewing current values, writing, and independently reading back. Conflicts require a fresh review; the helper does not retry, refresh the revision, or fall back to upsert. Stock, deletes, options, and market prices are excluded. Existing PATCH receipts, projection warnings, and conflict metadata remain available.
+
+### Patch Changes
+
+- fbb0715: Add optional closed-month observation quality metadata to the generated internal usage snapshot type.
+- 62d1c63: Classify platform billing consent receipts as an internal Console collection.
+- a9ca714: Synchronize generated usage invoice types with the private, transition-gated precharge notice protocol fields.
+
 ## 0.65.1
 
 ### Patch Changes

package/README.md

@@ -96,6 +96,12 @@ monthly allowance is exhausted or 503 when admission cannot be verified.
 legacy public-ID paths for unmigrated paid assets. A signed asset's retained
 `muxPlaybackId` is historical usage evidence and is not a playable URL.
 
+`VideoPlayer` displays the stored `aspectRatio` values `16_9`, `9_16`,
+`4_3`, and `1_1` as CSS ratios in both the placeholder and ready player.
+An unset ratio defaults to `16/9`. Override the ready player with
+`style.aspectRatio`, or the placeholder with `placeholderStyle.aspectRatio`;
+each override applies only to its own rendering path.
+
 `CanvasRenderer` renders reserved `shape` nodes (`terminator`, `process`,
 `decision`, `io`, `subprocess`) with first-party SVG geometry, without a tenant
 catalog row or QuickJS template.
@@ -152,6 +158,20 @@ The assertion proves operator and tenant context only. It is not a Console API
 credential; the external backend must use its own server-held credential and
 authorization policy for tenant data.
 
+The verifier defaults to `super-admin` and `tenant-admin` only. To allow an
+editor or viewer, both the administrator-managed binding `allowedRoles` and the
+receiver's trusted server `allowedRoles` option must include that exact role.
+For example, a receiver can pass
+`allowedRoles: ['super-admin', 'tenant-admin', 'tenant-viewer']`; never take this
+allowlist from browser input. Only opted-in operators see the execution view;
+binding configuration remains administrator-only.
+
+The receiver server must enforce each app feature's permissions from verified
+`tenant_role` and `operator_id`, independently of its server credential. Direct
+platform viewer mutation denial remains unchanged. The 60-second assertion
+expiry does not revoke an app-local session; the receiver owns its session
+expiry, authorization rechecks, and revocation.
+
 Migration quick reference:
 
 - `createClient` remains available from `@01.software/sdk` and
@@ -751,6 +771,10 @@ 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')
+  }
   await tenantPsp.charge({
     idempotencyKey: prepared.firstCharge.idempotencyKey,
     amount: prepared.firstCharge.amount,
@@ -767,8 +791,8 @@ posts the signed outcome through the configured charge-result webhook. A trial
 response is immediately `trialing` and has no `firstCharge` field. Before a paid
 subscribe, configure an active delegated billing connection for
 the tenant; otherwise Console returns `409 conflict` without lifecycle writes.
-Do not start
-the PSP payment at or after `expiresAt`; deduplicate PSP work with
+Do not start the PSP payment if `expiresAt` is invalid or the current time is
+at or after it; deduplicate PSP work with
 `firstCharge.idempotencyKey`. A late paid result remains evidence but cannot
 activate the Membership, so the tenant handles any refund outside this API. Replays use
 the same plan, price, customer reference, and idempotency key while the first
@@ -1869,6 +1893,55 @@ options, option values, and variants. It is the tenant-admin safe path because
 it applies the product/option/variant transaction that raw collection writes do
 not provide.
 
+For an existing variant's **base price only**, use the server-only narrow helper:
+
+```typescript
+const locale = 'ko'
+const baseline = await server.commerce.product.graphRevision({
+  productId,
+  locale,
+})
+// Review current base prices after taking the baseline, in the same locale.
+const current = await server.collections.from('product-variants').find({
+  where: { product: { equals: productId } },
+  locale,
+})
+const variantId = current.docs[0].id
+const saved = await server.commerce.product.updateVariantPrices({
+  productId,
+  locale,
+  graphRevision: baseline.graphRevision,
+  updates: [{ id: variantId, price: 1250 }],
+})
+// Independent readback; this does not replace the revision of an older draft.
+const readback = await server.collections
+  .from('product-variants')
+  .findById(variantId, { locale })
+if (saved.productProjectionStale) {
+  console.warn('Prices saved; product listing projection may still be stale.')
+}
+```
+
+`graphRevision()` returns only `{ productId, graphRevision }` from a private,
+no-store server read. `updateVariantPrices()` sends only the supplied existing
+rows to the variants PATCH and returns its `ok`, `productId`, `updated`,
+`deleted`, and `productProjectionStale` fields unchanged. It accepts 1–250
+`{ id, price }` rows; price uses the existing numeric shop-currency amount,
+with currency precision enforced by Console. Stock, deletions, option changes,
+compare-at prices, and market prices are rejected as SDK inputs. They are not
+silently stripped or sent. Full graph upsert remains a separate operation.
+
+Use the same explicit enabled content `locale` (`ko` or `en`) for baseline,
+value review, save, and readback. A `409 graph_conflict` requires reviewing fresh
+values before a deliberate new edit; the SDK never fetches a replacement
+revision, retries the PATCH, or falls back to upsert. The existing conflict
+fields remain at `SDKError.details.body.currentGraphRevision` and
+`SDKError.details.body.currentGraphUpdatedAt`, together with
+`apiReason` and `requestId`. Read-only service keys can read the revision but
+cannot change prices; operator/PAT tenant roles and tenant pinning still apply.
+A saved projection warning reports committed graph data, not a failed save or
+permission to repeat the write.
+
 `commerce.product.upsert()` is a graph-write API. For Console product
 documents, Payload saves product fields first; upsert receives `productId`,
 `graphRevision` (required when updating an existing product via `productId` -
@@ -1939,20 +2012,92 @@ if (!result.ok) {
 }
 ```
 
-Existing product graph edits send the saved product id and the composer draft
-baseline, without product document fields:
+Existing product graph edits send the saved product id and the revision from
+the composer draft baseline, without product document fields. The draft is an
+editor read model, not an SDK mutation payload: construct `options` and
+`variants` explicitly instead of forwarding `draft.options` / `draft.variants`.
+
+This example assumes the complete persisted graph has one Color option, two
+values, and two variants. Replace the sample IDs and reviewed values with
+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({
   productId: 'prod_123',
   graphRevision: draft.graphRevision,
-  options: draft.options,
-  variants: draft.variants,
+  options: [
+    {
+      id: 'opt_color',
+      title: 'Color',
+      slug: 'color',
+      values: [
+        {
+          id: 'val_black',
+          value: 'Black',
+          slug: 'black',
+          swatch: { type: 'color', color: '#111111' },
+        },
+        {
+          id: 'val_white',
+          value: 'White',
+          slug: 'white',
+          swatch: { type: 'media', mediaItemId: 'img_white' },
+        },
+      ],
+    },
+  ],
+  variants: [
+    {
+      id: 'var_black',
+      optionValues: { color: { valueId: 'val_black' } },
+      price: 29000,
+      images: ['img_black'],
+    },
+    {
+      id: 'var_white',
+      optionValues: { color: { valueId: 'val_white' } },
+      price: 29000,
+      images: ['img_white'],
+    },
+  ],
 })
 ```
 
-For updates to existing options or option-values, prefer `id` / `valueId` when
-available so rename-safe updates do not depend on slugs.
+Keep persisted option/value/variant `id`s and select existing values by
+`valueId`; do not regenerate identity from labels or change stored slugs.
+Resolve editor `optionValueKeys` (client keys) to SDK `optionValues`, as above,
+whose record keys are option slugs or titles, not option IDs. Do not send
+unsaved matrix proposal rows (`included: false` with no `id`). Preserve IDs
+for persisted rows you retain, and send `isActive: false` when deliberately
+deactivating one. Copy only mutation fields, excluding `clientKey`, `included`,
+and other editor state. SDK `images` contains string IDs, not hydrated media
+objects.
+An SDK swatch object requires `type: 'color'` with a color string or
+`type: 'media'` with a `mediaItemId` string. For an existing value, omit
+`swatch` to preserve its stored swatch. The SDK type also accepts `swatch: null`;
+runtime clearing with it is not verified here. Do not copy a draft swatch
+with a missing/null tag or null active value into that object shape.
+
+Upsert synchronizes the full graph, not just changed rows: omitted options or
+values can be deleted, and omitted variants can be deleted or deactivated.
+If reservation history prevents variant deletion, omission can instead reject
+the write with `409` and roll it back.
+Keep the revision of the reviewed baseline and review fresh values after a
+`graph_conflict`; do not substitute a newer revision onto stale values.
+`graphRevision` excludes inventory-only changes, so this graph edit omits
+loaded `stock` on persisted variants. New finite variants may carry initial
+stock. An intentional stock write is different from replaying loaded stock;
+this example does not perform one.
+
+This example is for a persisted option graph. For editor-only placeholders,
+use the simple-variant branch only when `editorPlaceholderGraph` is true and
+the structure still matches: one unsaved `Default` option, one unsaved value
+with a nonempty label (not necessarily `Standard`), and one included variant
+selecting only that value. Send `options: []` and that simple variant with
+`optionValues: {}`. Preserve its variant ID if persisted; a new variant has
+no saved ID. Omit loaded stock on persisted variants. Base-price-only changes
+use `updateVariantPrices()` above, rather than a full graph upsert.
 
 ```typescript
 // Batch stock check (point-in-time read, NOT a reservation)
@@ -2046,6 +2191,24 @@ 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`.
 
+### Customer event registration history
+
+After customer sign-in, `client.events.listMyRegistrations({ page: 1, limit: 10 })`
+returns only that session's registrations with status, quantity, created time,
+and event/occurrence references plus current public title/time metadata.
+`page` defaults to 1; `limit` defaults to 10 and is capped at 100. The result has
+`docs`, `totalDocs`, `limit`, `page`, `totalPages`, `hasNextPage`, `hasPrevPage`.
+A customer JWT and matching publishable key are required; server keys cannot
+impersonate customers. Reads and responses use `no-store`. Non-public/missing
+metadata becomes null while registration references/status remain. PII expiry
+and cleanup preserve the same attendee-free DTO. Guest credentials, answers,
+audit fields and locations are absent; same-email guest records are not linked.
+
+`createServerClient().events` excludes this customer-only method, following the
+customer-only membership/profile/order helpers. A server BFF creates a client
+per request with `createClient({ publishableKey, customer: { persist: false, token } })`
+and calls `client.events.listMyRegistrations()` with the customer's JWT.
+
 ### Community public reads
 
 Use the shaped `community` helpers for browser/customer community screens. A
@@ -2466,3 +2629,33 @@ P5 also adds JWT-`jti` revocation: `revokeCustomerJti(jti, ttl)` on the server i
 **Boolean field renames** (6 collections):
 
 - `status: 'active' | 'inactive'` → `isActive: boolean` on Forms, ArticleAuthors, CustomerGroups, ShippingPolicies, ProductVariants
+
+### Customer benefit vouchers
+
+Tenant-admins manage benefit voucher definitions in Console. These are single-use, non-monetary benefits, with no Checkout discount or credit effect. Your server decides recipients and timing (for example from a membership webhook or your own cron); source uniqueness prevents duplicate effects only.
+
+```ts
+import { createServerClient } from '@01.software/sdk/server'
+
+const server = createServerClient({ publishableKey, secretKey })
+const { voucher, created } = await server.benefitVouchers.issue({
+  definitionId,
+  customerId,
+  sourceNamespace: 'member-benefits',
+  sourceRef: 'period:2030-01:member-opaque-id',
+})
+const redeemed = await server.benefitVouchers.redeem({
+  customerId,
+  voucherId: voucher.id,
+  requestId,
+  actorRef: 'staff:opaque-id',
+})
+```
+
+`server.benefitVouchers.get({ customerId, voucherId })` and `list({ customerId, state?, definitionId?, limit?, cursor? })` require a read-scoped server key. `issue`, `redeem`, and `voidVoucher({ customerId, voucherId, requestId, actorRef, reason })` require write scope, sk01 credentials and no browser Origin. Void reasons are `issued_in_error`, `benefit_revoked`, `customer_request`, and `other`. Issuing and redeeming require effective Ecommerce and Customers; reads and void remain available after feature loss.
+
+Reuse the same sourceNamespace/sourceRef and identical issue input on an unknown outcome. For redeem/void, create a request UUID once and reuse it on retries; these POSTs are not automatically retried. Reusing an identity with different input returns 409. A successful transition is irreversible. Expiry uses database time and is inclusive at expiresAt. Correct an issued benefit by voiding it and issuing a new source identity.
+
+`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.