@01.software/sdk 0.49.0 → 0.51.0

package/CHANGELOG.md

@@ -1,5 +1,134 @@
 # @01.software/sdk
 
+## 0.51.0
+
+### Minor Changes
+
+- 8dd8ef7: BREAKING (0.x minor): reclassify `discounts` from the browser-public
+  `COLLECTIONS` bucket to `SERVER_ONLY_COLLECTIONS`. This is the
+  `PLAT-API-002` security/implementation-boundary correction: raw discount
+  definitions require a server credential, so a publishable-key-only raw read
+  never succeeded. Browser discount validation remains available through the
+  existing shaped `POST /api/discounts/validate` operation.
+
+  `SERVER_COLLECTIONS` continues to include `discounts` for secret-key/PAT SDK
+  clients. The browser `PublicCollection` union no longer accepts `discounts`,
+  and the raw REST route now rejects its publishable-key-only reads at the
+  server-only guard (404) rather than at collection access (403). Contract v1.23.0
+  is a compatible correction of that false callable-surface claim; this SDK
+  package change is still a pre-1.0 breaking minor under `docs/packages/release.md`.
+
+- b08250c: Add a redacted `01 doctor` app-integration diagnostic with structured Agent CLI output.
+  Its explicit app environment input is the Node-runtime-safe `--app-env-file`.
+
+  Export the canonical tenant-context path on the SDK server entry for the
+  diagnostic-only, uncredentialed CORS probe.
+
+  Print the redacted app-integration diagnostic as the next setup step only for
+  Next.js and Node targets that receive its required app credential pair.
+
+- bf6df96: BREAKING (0.x minor): Make signed webhook receivers fail closed when their
+  signing secret is missing, empty, or blank. Use `handleSignedWebhook()` for the
+  default signed path and `handleUnsignedWebhook()` only for an intentionally
+  unsigned endpoint; both new names and `SignedWebhookOptions` are exported from
+  `@01.software/sdk/webhook`, not the SDK root. The deprecated `handleWebhook()`
+  and `WebhookOptions` compatibility exports remain available at their existing
+  root and webhook-subpath locations, require signed options, and follow the same
+  fail-closed runtime behavior.
+
+  `toleranceSeconds` is now validated. It keeps its 300-second default for an
+  absent or null value, but a present value must be a number within an inclusive
+  0-86400-second range; anything else (including `Infinity`, `NaN`, a negative
+  number, a non-number, or a week-long window) is a configuration error that
+  returns 500 with a distinct tolerance message before the body is consumed.
+
+- 2ce3aa9: Add explicit embedded-admin browser and server SDK entrypoints for the receiver
+  handshake and strict assertion verification. Add the PAT-only Human CLI
+  `embedded-app show`, `configure`, and `disable` commands for single-binding
+  management.
+
+### Patch Changes
+
+- 48372ad: Synchronize the optional tenant embedded-admin binding in generated Payload
+  types. This does not add an SDK method or expose embedded session credentials.
+- 3fb53f0: Clarify PAT revocation audit metadata for trusted machine reconciliation.
+- eea3ea8: Align canonical Order and Checkout response validation with the authoritative non-empty nullable item fields.
+- 46c32e6: Ensure the packed SDK runtime declares its `jose` dependency with the portable
+  npm range used by standalone consumers.
+- a1567cc: Validate SDK release tarballs with patched package-analysis dependencies.
+- 9fecd85: Register the internal `commerce-payment-webhook-routes` collection so the SDK
+  collection registry stays in lockstep with Console. The collection is
+  Console-internal PortOne webhook routing state: it adds no SDK method, appears
+  in no public or server-only bucket, and exposes no credential.
+- 41fbcb6: Synchronize required customer, period-end, and idempotency-key fields for the
+  SDK-hidden `membership-charges` generated type. The collection remains
+  server-only and gains no public write method.
+
+## 0.50.0
+
+### Minor Changes
+
+- 0e0ab60: Add server-only full-tuple PortOne payment find and durable reconciliation methods, including atomic domain-and-receipt completion for crash-safe same-key replay.
+- 743b895: Add optional canonical `allDayStartDate` and exclusive
+  `allDayEndDateExclusive` fields to public event-range DTOs while retaining
+  instant compatibility shadows and existing TypeScript object-literal source
+  compatibility. Generated Event types also add optional canonical
+  `recurrence.untilDate` for all-day structured recurrence; existing object
+  literals that omit it remain valid.
+- 743b895: Expose `managed_refund_attestation_forbidden` as the typed commerce error for registered managed captures while preserving existing cancel-refund errors and detail placement.
+- 6b584bc: Expose the PortOne Standard V2 action's permanent non-cancelability and exact-action-only retry policy through an exact negotiated create/retrieve projection, while normalizing released Console responses for bidirectional non-lockstep compatibility. Console may deploy first because unnegotiated responses retain the released exact shape; the SDK may deploy first because it accepts and normalizes that old-server shape. Hosted create and all cancel operations remain unnegotiated. Package publication remains a separate post-merge release action.
+- 743b895: BREAKING (0.x minor): Retire the expired ADR 0025 product media compatibility
+  shims. `resolveProductMedia()` and `resolveProductGallery()` — plus their
+  compatibility-only types `MediaPointerSource`, `ResolveProductMediaInput`,
+  `ResolveProductMediaResult`, `ProductMediaSetMatchType`, `ProductMediaSetInput`,
+  `ProductGallerySource`, `ResolveProductGalleryInput`, and
+  `ResolveProductGalleryResult` — are no longer exported from the package root or
+  `utils`.
+
+  These shipped in 0.34.0 as a one-release migration aid and forwarded to the
+  canonical resolvers. Replace `resolveProductMedia()` and
+  `resolveProductGallery()` with `resolveProductSelectionMedia()` for
+  variant/option selection media and `resolveProductDisplayMedia()` for listing
+  and PDP display fallback. Pre-ADR-0025 `mediaSets` inputs have no replacement:
+  variant `images[]` subsets and `product-option-values.swatch.mediaItemId` are
+  the canonical selection sources.
+
+  Canonical selection and display precedence, result shapes, and edge-case
+  behavior are unchanged. See `packages/published/sdk/MIGRATION.md`.
+
+- bca928f: Add provider-neutral `paymentReconciliationRequired` and
+  `paymentRefundRequiresAttention` commerce notification webhook types, handlers,
+  and runtime validation.
+
+### Patch Changes
+
+- 743b895: Expose the nullable ownership scope on the generated server-only inbound
+  webhook ledger document type.
+- 743b895: Align commerce endpoint descriptors with the shared HTTP contract manifest without changing endpoint methods, paths, or error families.
+- 743b895: Expose the additive Toss capture-evidence variants in generated private
+  PaymentSession types while preserving the existing public payment API.
+- 743b895: Expose the additive durable Return-refund canonical envelope and stable
+  post-commit replay outcome in generated Payload types. Refund execution now
+  rejects changed payment identity and cross-tenant explicit-key reuse before
+  provider I/O while preserving identical cache-loss replay payloads.
+- 0c4c5fd: Synchronize generated ProviderConnection configuration-attestation fields for
+  the SDK-hidden `commerce-payment-accounts` collection. The operator-only REST
+  actions remain internal to Console and add no public SDK transport method.
+- 743b895: Standardize customer-facing Console terminology in initialization guidance and
+  generated SDK descriptions without changing runtime behavior or API contracts.
+- 743b895: Remove the unsupported minor and guardian-consent fields from generated
+  server-only Customer document types as a privacy correction. Shaped customer
+  registration and `/me` response types are unchanged.
+- 743b895: Clarify the generated webhook subscription descriptions: an empty subscription
+  list is a wildcard for ordinary collection create/update events only, and
+  commerce notifications require an explicit row for their source collection.
+  Descriptions only — no schema, runtime, or API contract change.
+- 743b895: Add optional sanitized commerce notification diagnostics fields (`eventType`,
+  `notificationEvent`, `notificationIntentId`, `notificationDedupeKey`,
+  `sourceId`) to the generated internal `WebhookDelivery` document type. The
+  collection stays internal and is not exposed through the SDK surface;
+  existing object literals remain valid because every field is optional.
+
 ## 0.49.0
 
 ### Minor Changes
@@ -1070,7 +1199,7 @@ displayStatus` JSDoc comment from `Order.status`. The Console removed that
   disabled. Customer auth failures now surface the same SDK-specific error classes
   as other SDK requests instead of the previous generic API error shape.
 
-## Unreleased
+## Historical 0.34.0 migration notes
 
 ### Minor Changes
 

package/MIGRATION.md

@@ -1,5 +1,61 @@
 # @01.software/sdk Migration Notes
 
+## Product media compatibility shim retirement (#721)
+
+This is a `BREAKING (0.x minor)` change. The ADR 0025 one-release compatibility
+shims first published in `0.34.0` are removed from the package root and
+`utils`.
+
+| Removed                                                     | Replacement                                                                              |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `resolveProductMedia(input)`                                | `resolveProductSelectionMedia(input)`, then `resolveProductDisplayMedia(input)` fallback |
+| `resolveProductGallery(input)`                              | `resolveProductSelectionMedia(input)`, then `resolveProductDisplayMedia(input)` fallback |
+| `ResolveProductMediaInput` / `ResolveProductGalleryInput`   | `ResolveProductSelectionMediaInput`                                                      |
+| `ResolveProductMediaResult` / `ResolveProductGalleryResult` | `ResolveProductSelectionMediaResult`                                                     |
+| `MediaPointerSource` / `ProductGallerySource`               | `ProductSelectionMediaSource` / `ProductDisplayMediaSource`                              |
+| `ProductMediaSetInput` / `ProductMediaSetMatchType`         | none; use variant `images[]` and `swatch.mediaItemId`                                    |
+
+```ts
+// Before
+const gallery = resolveProductGallery({
+  pool: product.images,
+  selectedVariantId: variant.id,
+  selectedOptionValueIds: valueIds,
+})
+
+// After
+const selection = resolveProductSelectionMedia({
+  productMediaPool: product.images,
+  selectedVariant: variant,
+  selectedOptionValues: optionValues,
+})
+const media =
+  selection.source === 'none'
+    ? resolveProductDisplayMedia({
+        productMediaPool: product.images,
+        featuredImage: product.featuredImage,
+      })
+    : selection
+```
+
+Use this two-step sequence when replacing either shim. Stopping after a
+selection result with `source === 'none'` would drop the previous
+featured-image/product-pool display fallback.
+
+The shims already forwarded to these resolvers, so canonical selection and
+display precedence, result shapes, and edge-case behavior are unchanged. The
+legacy-only inputs they accepted have no replacement:
+`variantFeaturedMediaItemId` and `selectedOptionValueMediaItemIds` become
+`selectedVariant.images[]` and `selectedOptionValues[].swatch`, the `legacy`
+direct-media object was already ignored, and `mediaSets` was removed from the
+product schema before the shims expired.
+
+`source` values also narrow: the shim-only `'variant_featured'`,
+`'exact_variant_set'`, `'option_value_set'`, and `'default_set'` values are gone.
+Selection media reports `'variant_media_selected'`, `'variant_media_matching'`,
+`'option_swatch'`, or `'none'`; display media reports `'featured_image'`,
+`'product_pool'`, or `'none'`.
+
 ## SDK 0.46 server-only custom-provider bridge (#3485)
 
 SDK 0.46 adds

package/README.md

@@ -33,7 +33,7 @@ import { createServerClient, isCommerceSDKError } from '@01.software/sdk/server'
 
 // Webhook only - webhook handlers
 import {
-  handleWebhook,
+  handleSignedWebhook,
   createTypedWebhookHandler,
 } from '@01.software/sdk/webhook'
 
@@ -43,6 +43,12 @@ import { RealtimeConnection } from '@01.software/sdk/realtime'
 // Storefront cache resource names for SSG/ISR adapters
 import { storefrontCacheResources } from '@01.software/sdk/storefront-cache'
 
+// Embedded app browser handshake
+import { receiveEmbeddedAdminSession } from '@01.software/sdk/embedded-admin'
+
+// Embedded app backend verification
+import { verifyEmbeddedAdminSession } from '@01.software/sdk/embedded-admin/server'
+
 // Components - sub-path imports per domain
 import { Analytics } from '@01.software/sdk/analytics/react'
 import { RichTextContent } from '@01.software/sdk/ui/rich-text'
@@ -58,26 +64,28 @@ types lightweight. Server, React Query, and UI features live behind explicit
 sub-paths so consumers install feature peers only when they import the matching
 entry.
 
-| Import                              | Feature(s)                                                               | Install when used                                                                                          |
-| ----------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `@01.software/sdk`                  | browser-safe `createClient`, commerce helpers, collection helpers, types | none                                                                                                       |
-| `@01.software/sdk/client`           | browser-safe `createClient` entry and SDK error guards                   | none                                                                                                       |
-| `@01.software/sdk/server`           | `createServerClient`, server-only APIs, and SDK error guards             | none; keep `secretKey` code on the server                                                                  |
-| `@01.software/sdk/errors`           | SDK error classes and guards                                             | none                                                                                                       |
-| `@01.software/sdk/analytics`        | browser analytics client and typed event helpers                         | none                                                                                                       |
-| `@01.software/sdk/metadata`         | SEO metadata extraction and generation helpers                           | none                                                                                                       |
-| `@01.software/sdk/webhook`          | webhook handlers, event guards, and webhook types                        | none                                                                                                       |
-| `@01.software/sdk/query`            | React Query hooks, cache helpers, `getQueryClient`                       | `@tanstack/react-query`, `react`, `react-dom`                                                              |
-| `@01.software/sdk/realtime`         | `RealtimeConnection`, `useRealtimeQuery`                                 | `@tanstack/react-query`, `react`, `react-dom`                                                              |
-| `@01.software/sdk/storefront-cache` | product storefront cache resource name helpers                           | none                                                                                                       |
-| `@01.software/sdk/analytics/react`  | `<Analytics />`                                                          | `react`, `react-dom`                                                                                       |
-| `@01.software/sdk/ui/rich-text`     | `RichTextContent`, `StyledRichTextContent`                               | `react`, `react-dom`, `@payloadcms/richtext-lexical`                                                       |
-| `@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/video`         | `VideoPlayer`                                                            | `react`, `react-dom`, `@mux/mux-player-react`                                                              |
-| `@01.software/sdk/ui/image`         | `Image`                                                                  | `react`, `react-dom`                                                                                       |
+| Import                                   | Feature(s)                                                               | Install when used                                                                                          |
+| ---------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `@01.software/sdk`                       | browser-safe `createClient`, commerce helpers, collection helpers, types | none                                                                                                       |
+| `@01.software/sdk/client`                | browser-safe `createClient` entry and SDK error guards                   | none                                                                                                       |
+| `@01.software/sdk/server`                | `createServerClient`, server-only APIs, and SDK error guards             | none; keep `secretKey` code on the server                                                                  |
+| `@01.software/sdk/errors`                | SDK error classes and guards                                             | none                                                                                                       |
+| `@01.software/sdk/analytics`             | browser analytics client and typed event helpers                         | none                                                                                                       |
+| `@01.software/sdk/metadata`              | SEO metadata extraction and generation helpers                           | none                                                                                                       |
+| `@01.software/sdk/webhook`               | webhook handlers, event guards, and webhook types                        | none                                                                                                       |
+| `@01.software/sdk/query`                 | React Query hooks, cache helpers, `getQueryClient`                       | `@tanstack/react-query`, `react`, `react-dom`                                                              |
+| `@01.software/sdk/realtime`              | `RealtimeConnection`, `useRealtimeQuery`                                 | `@tanstack/react-query`, `react`, `react-dom`                                                              |
+| `@01.software/sdk/storefront-cache`      | product storefront cache resource name helpers                           | none                                                                                                       |
+| `@01.software/sdk/embedded-admin`        | embedded app browser handshake and shared protocol types                 | none                                                                                                       |
+| `@01.software/sdk/embedded-admin/server` | assertion verification and JWKS loading                                  | none; keep receiver session creation on the server                                                         |
+| `@01.software/sdk/analytics/react`       | `<Analytics />`                                                          | `react`, `react-dom`                                                                                       |
+| `@01.software/sdk/ui/rich-text`          | `RichTextContent`, `StyledRichTextContent`                               | `react`, `react-dom`, `@payloadcms/richtext-lexical`                                                       |
+| `@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/video`              | `VideoPlayer`                                                            | `react`, `react-dom`, `@mux/mux-player-react`                                                              |
+| `@01.software/sdk/ui/image`              | `Image`                                                                  | `react`, `react-dom`                                                                                       |
 
 `CanvasRenderer` renders reserved `shape` nodes (`terminator`, `process`,
 `decision`, `io`, `subprocess`) with first-party SVG geometry, without a tenant
@@ -87,6 +95,54 @@ If a feature is not listed here, it does not need a separate peer install.
 For the full component-to-peer mapping, see
 `packages/published/sdk/.claude/rules/components-reference.md`.
 
+### Embedded Admin App
+
+An embedded admin app is one tenant-owned management UI rendered inside the
+Console Developer Settings surface. The browser helper accepts exactly one
+short-lived Console assertion through the pinned parent/origin challenge. Send
+the receipt immediately to your own backend; do not decode it into a browser
+session or persist it.
+
+```typescript
+import { receiveEmbeddedAdminSession } from '@01.software/sdk/embedded-admin'
+
+const receipt = await receiveEmbeddedAdminSession({
+  consoleOrigin: 'https://console.01.software',
+})
+
+await fetch('/api/embedded-admin/session', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(receipt),
+})
+```
+
+The receiver backend verifies the assertion against the Console JWKS and pins
+its own exact origin. Establish an app-local session only after this succeeds.
+
+```typescript
+import { verifyEmbeddedAdminSession } from '@01.software/sdk/embedded-admin/server'
+
+const claims = await verifyEmbeddedAdminSession({
+  channelId: body.requestId,
+  consoleOrigin: 'https://console.01.software',
+  destination: 'https://admin.example.com',
+  token: body.token,
+})
+```
+
+Tenant admins configure the active tenant's single binding through the Human
+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.
+
+Loopback HTTP is disabled by default. Only non-production fixtures may set
+`allowLoopbackHttp: true` on the receiver and verifier options.
+
+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.
+
 Migration quick reference:
 
 - `createClient` remains available from `@01.software/sdk` and
@@ -196,6 +252,8 @@ honored only when `mode` is unset.
 
 ### Client
 
+<!-- sdk-docs-sync-shaped-first: commerce.product.listingPage -->
+
 ```typescript
 import { createClient } from '@01.software/sdk'
 
@@ -203,13 +261,16 @@ const client = createClient({
   publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY,
 })
 
-// Query data (returns Payload native response)
-const { docs } = await client.collections.from('products').find({
+// Fetch public-safe, card-ready catalog data through the shaped helper.
+const page = await client.commerce.product.listingPage({
   limit: 10,
-  select: { title: true, slug: true },
 })
+const cards = page.cards
 ```
 
+For Payload-native reads that shaped helpers do not cover, use the
+[advanced raw collection escape hatch](#advanced-direct-payload-queries-escape-hatch).
+
 ### Server Client
 
 ```typescript
@@ -332,7 +393,7 @@ gallery item DTOs include title, description, content, gallery reference, and
 image media. Tenant, metadata, draft status, and storage/provider internals are
 omitted. Gallery item reads require either `gallerySlug` or `galleryId`; prefer
 `gallerySlug` for storefront routes. The default gallery item sort is `manual`,
-matching curator order from the Admin Panel.
+matching curator order from the Console.
 
 Both helpers return Payload-style pagination (`docs`, `totalDocs`, `page`,
 `limit`, etc.). `limit` is bounded server-side to `1..100`; invalid query,
@@ -883,6 +944,20 @@ export default async function ProductPage({ params }) {
 }
 ```
 
+The SDK sends
+`Accept: application/vnd.01software.portone-action-capabilities.v1+json` for
+Standard create and browser/server PortOne retrieve. Hosted create and
+browser/server cancel do not send it. It accepts either the negotiated exact action
+or the released Console's exact action, normalizing the latter to
+`cancelable: false` and `retryPolicy: 'same_action_only'`. Partial capability
+fields, different literals, and unknown response fields still fail closed.
+The Accept value must be that sole exact media type after optional surrounding
+whitespace. Lists, wildcards, parameters, and q-values deliberately retain the
+default projection; this makes either Console-first or SDK-first rollout safe.
+Direct HTTP create/retrieve responses use the vendor `Content-Type` only when
+the successful body actually contains the Standard capability action. Hosted,
+Toss, cancel, confirm, and error responses remain `application/json`.
+
 ## API
 
 ### Client Configuration
@@ -1383,8 +1458,16 @@ if (
   standardPortOneSession.presentationStatus === 'actionable' &&
   standardPortOneSession.nextAction.type === 'portone_sdk'
 ) {
+  const { cancelable, retryPolicy, ...paymentRequest } =
+    standardPortOneSession.nextAction
+
   // PortOne V2 requires its currency constant (`CURRENCY_KRW`), not ISO `KRW`.
-  // await PortOne.requestPayment(standardPortOneSession.nextAction)
+  // A Standard action cannot be canceled or replaced. After browser failure,
+  // retry only this exact payment request and paymentId instead of calling
+  // cancelPortOne() or creating a sibling PaymentSession.
+  if (!cancelable && retryPolicy === 'same_action_only') {
+    // await PortOne.requestPayment(paymentRequest)
+  }
   // Always retrieve the session afterwards; Console lookup/webhook is authoritative.
 }
 
@@ -1405,6 +1488,24 @@ await server.commerce.paymentSessions.retrievePortOne({
   paymentSessionId: portOneSession.id,
 })
 
+// Operator recovery can start from PortOne's canonical provider identity.
+// `findPortOne` is strictly local/read-only. `reconcilePortOne` is an explicit
+// mutation and must reuse one durable key for retries of the same operation;
+// its domain result and response complete atomically before delivery.
+const portOneIdentity = {
+  provider: 'portone' as const,
+  providerAccountKey: 'store-id-from-the-registered-connection',
+  environment: 'test' as const,
+  providerPaymentId: 'provider-assigned-payment-id',
+}
+const localPortOneState =
+  await server.commerce.paymentSessions.findPortOne(portOneIdentity)
+const reconciledPortOneState =
+  await server.commerce.paymentSessions.reconcilePortOne({
+    ...portOneIdentity,
+    idempotencyKey: createCommerceIdempotencyKey(),
+  })
+
 // Toss confirmation is a typed server-only adapter action. There is no generic
 // `confirmVerified` or provider-paid Order creation escape hatch.
 const confirmationIdempotencyKey = createCommerceIdempotencyKey()
@@ -1492,6 +1593,20 @@ if (recovered.finalizationStatus === 'committed') {
 }
 ```
 
+### Server-only PortOne identity reconciliation
+
+The PortOne identity facade is available only from `@01.software/sdk/server`.
+Both methods require the complete `provider`, `providerAccountKey`,
+`environment`, and `providerPaymentId` tuple; tenant identity is derived from
+the server credential and is not accepted in the body. `findPortOne` never
+calls the provider or mutates local state. `reconcilePortOne` requires write scope and a
+durable idempotency key, then delegates to the existing managed PortOne
+convergence engine. A retry after an interrupted response replays the first
+atomically completed result without repeating provider I/O. Its result distinguishes `applied`, `observed`,
+`recovered_after_ambiguous_result`, and `requires_attention`. `found: false` is
+the one HTTP/SDK not-found result; reconciliation does not claim or
+heuristically attach an unknown provider payment.
+
 `custom.retrieve` is an exact lookup by either `providerSessionId` or
 `providerPaymentId` (exactly one). It returns only bounded recovery state:
 provider identity, session/provider/finalization status, Money, and the resolved
@@ -1562,8 +1677,30 @@ The SDK root no longer exports raw generated `Order`, `Transaction`, `Cart`, or
 `CartItem` Payload documents. Use the canonical `PublicOrder` / `PublicCart`
 DTOs for storefront code and explicit server collection types only inside
 trusted operational code. Order cancellation no longer returns the deprecated
-inline provider-refund branch: a paid cancellation returns `refundPending`, and
-the dedicated refund-resolution flow reports provider completion.
+inline provider-refund branch. `refundPending` is a local financial marker, not
+authority for caller provider I/O:
+
+| Captured payment lane                                   | Provider refund owner        | `resolveCancelRefund`                                                               |
+| ------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
+| Registered managed PaymentSession (Toss or PortOne)     | Console only                 | Rejects `409 managed_refund_attestation_forbidden`; the pending marker is preserved |
+| Explicit `custom_bridge` capture                        | Trusted external integration | May report the already-completed provider outcome                                   |
+| Legacy NULL-origin capture without a registered account | Bounded migration drain only | May report the already-completed provider outcome                                   |
+
+Do not infer the external lane from a defaulted `sessionOrigin`, an
+`orderCanceled` notification, or provider-observed cancellation. New managed
+captures must use Console's refund operation; `resolveCancelRefund` remains
+only for the two external-drain rows above.
+
+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
+fails closed opaquely as `payment_transaction_mismatch`; another session is
+never substitute evidence.
+
+`managed_refund_attestation_forbidden` is the resolver's typed commerce error.
+Pre-existing resolver reasons remain generic SDK errors available through
+`getSDKErrorReason()` / `apiReason`, with legacy extra fields at the top level
+of the raw body in `error.details.body`.
 
 ```typescript
 await server.commerce.orders.update({ orderNumber, status: 'confirmed' })
@@ -1628,7 +1765,7 @@ 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.
 
-`commerce.product.upsert()` is a graph-write API. For Admin Panel product
+`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` -
 load from `GET /api/products/:id/composer-draft`), options, and variants. Do
@@ -1835,10 +1972,21 @@ await server.community.moderation.unbanCustomer({ customerId })
 
 ### Webhook
 
-Create or open the endpoint in Console → Integrations → Webhooks. After saving,
-use **Reveal signing secret** once for the initial value, or **Rotate secret** to
-invalidate the previous secret and receive a new one-time plaintext value. Set the
-copied value in the receiver environment as `WEBHOOK_SECRET`.
+Webhooks created in Console start inactive. Use this setup order so no event is
+sent before the receiver can verify it:
+
+1. Save the inactive endpoint in Console → Integrations → Webhooks.
+2. Use **Reveal signing secret** once and copy the plaintext value.
+3. Deploy the receiver with that value set as `WEBHOOK_SECRET`.
+4. Return to the saved endpoint and choose **Activate webhook**.
+
+This inactive-first behavior is Console-only and changes no API default.
+Creating an endpoint through the API with `isActive` omitted still yields an
+active endpoint (`true`), and an explicit `isActive` value is honored — so send
+`isActive: false` for the same staged setup outside Console.
+
+After initial setup, **Rotate secret** invalidates the previous secret and
+returns a new one-time plaintext value for receiver deployment.
 
 `Webhook` list/read responses do not include plaintext signing secrets — only
 the Console reveal/rotate flows return them. Use `WebhookWithoutSecret` and
@@ -1850,7 +1998,10 @@ secrets.
 Use HMAC-SHA256 signature verification:
 
 ```typescript
-import { handleWebhook, createTypedWebhookHandler } from '@01.software/sdk'
+import {
+  handleSignedWebhook,
+  createTypedWebhookHandler,
+} from '@01.software/sdk/webhook'
 
 const handler = createTypedWebhookHandler('orders', async (event) => {
   // event.data is typed as Order
@@ -1859,16 +2010,34 @@ const handler = createTypedWebhookHandler('orders', async (event) => {
 
 export async function POST(request: Request) {
   const secret = process.env.WEBHOOK_SECRET
-  if (!secret) throw new Error('WEBHOOK_SECRET is required')
+  if (!secret?.trim()) throw new Error('WEBHOOK_SECRET must be nonblank')
 
-  return handleWebhook(request, handler, {
+  return handleSignedWebhook(request, handler, {
     secret,
   })
 }
 
 // Signed deliveries include x-webhook-signature, x-webhook-timestamp,
-// and x-webhook-delivery-id. handleWebhook rejects stale or unsigned
-// deliveries when secret is set.
+// and x-webhook-delivery-id. handleSignedWebhook rejects stale, invalid,
+// or unsigned deliveries.
+```
+
+`handleSignedWebhook()` requires `secret` at the type boundary and also checks
+it at runtime. A missing, empty, or whitespace-only secret returns a
+configuration `500` before the request body or handler is processed. Missing or
+invalid signature metadata returns `401`. The deprecated `handleWebhook()` name
+remains as a signed compatibility alias with the same fail-closed behavior; it
+no longer selects unsigned mode when the secret is absent.
+
+Only endpoints intentionally configured without a signing secret should use the
+explicit unsigned receiver. It performs no signature authentication:
+
+```typescript
+import { handleUnsignedWebhook } from '@01.software/sdk/webhook'
+
+export async function POST(request: Request) {
+  return handleUnsignedWebhook(request, handler)
+}
 ```
 
 ```typescript
@@ -1894,18 +2063,18 @@ const customerAuthHandler = createCustomerAuthWebhookHandler({
 // Use isOrderChangedWebhookEvent when you need to distinguish manual ordering
 // from content field edits.
 import {
-  handleWebhook,
+  handleSignedWebhook,
   isOrderChangedWebhookEvent,
 } from '@01.software/sdk/webhook'
 
 function getWebhookSecret(): string {
   const secret = process.env.WEBHOOK_SECRET
-  if (!secret) throw new Error('WEBHOOK_SECRET is required')
+  if (!secret?.trim()) throw new Error('WEBHOOK_SECRET must be nonblank')
   return secret
 }
 
 export async function POST(request: Request) {
-  return handleWebhook(
+  return handleSignedWebhook(
     request,
     async (event) => {
       if (isOrderChangedWebhookEvent(event)) {
@@ -1919,7 +2088,7 @@ export async function POST(request: Request) {
 }
 ```
 
-Orderable Admin Panel drag operations are delivered as `operation: "update"`
+Orderable Console drag operations are delivered as `operation: "update"`
 with `eventType: "collection.orderChanged"`. For join ordering, the webhook
 uses the public parent collection as `collection` and points `event.change.moved`
 at the public moved entity when one exists, so handlers do not need to depend on
@@ -1936,7 +2105,7 @@ Source of truth: `packages/published/sdk/src/core/collection/const.ts` (`COLLECT
 | Tenant             | `tenant-metadata`                                                                                                                                                  |
 | Products           | `products`, `product-variants`, `product-options`, `product-option-values`, `product-categories`, `product-tags`, `product-collections`, `markets`, `brands`       |
 | Customers          | `customer-profiles`                                                                                                                                                |
-| Commerce           | `discounts`, `shipping-policies`, `shipping-zones`                                                                                                                 |
+| Commerce           | `shipping-policies`, `shipping-zones`                                                                                                                              |
 | Content            | `documents`, `document-categories`, `document-types`, `articles`, `article-authors`, `article-categories`, `article-tags`, `links`, `link-categories`, `link-tags` |
 | Playlists / Tracks | `playlists`, `playlist-categories`, `playlist-tags`, `tracks`, `track-categories`, `track-tags`                                                                    |
 | Galleries          | `galleries`, `gallery-categories`, `gallery-tags`, `gallery-items`                                                                                                 |
@@ -1946,8 +2115,9 @@ Source of truth: `packages/published/sdk/src/core/collection/const.ts` (`COLLECT
 | Community          | `reaction-types`, `post-categories`, `post-tags`, `customer-profile-lists`                                                                                         |
 | Events             | `event-calendars`, `events`, `event-categories`, `event-occurrences`, `event-tags`                                                                                 |
 
-Server-only collections include raw media/logo records, customer and order
-operational records, raw cart/cart-item records, form submissions, raw community documents
+Server-only collections include raw media/logo records, raw discount
+definitions (use `client.commerce.discounts.validate()` for browser validation),
+customer and order operational records, raw cart/cart-item records, form submissions, raw community documents
 (`posts`, `comments`, `reactions`, `bookmarks`), live stream provider records,
 Canvas graph shell rows (`canvas-nodes`, `canvas-edges`), segmentation records,
 and moderation records. They remain available from