@01.software/sdk 0.67.0 → 0.68.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @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

package/README.md

@@ -158,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
@@ -1998,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)
@@ -2543,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.