@01.software/sdk 0.48.0 → 0.51.0

package/README.md

@@ -29,11 +29,11 @@ pnpm add @01.software/sdk
 import { createClient } from '@01.software/sdk'
 
 // Server-only entry - keep Secret Key code out of browser-facing imports
-import { createServerClient } from '@01.software/sdk/server'
+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                                        | none                                                                                                       |
-| `@01.software/sdk/server`           | `createServerClient`, server-only collection, commerce, and preview APIs | 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,11 +95,62 @@ 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
   `@01.software/sdk/client`.
 - `createServerClient` must be imported from `@01.software/sdk/server`.
+- Error guards are available from the same `@01.software/sdk/client` or
+  `@01.software/sdk/server` entry as the client that throws; the root and
+  `@01.software/sdk/errors` guards also classify errors across entries.
 - React Query hooks and cache helpers must be imported from
   `@01.software/sdk/query`.
 - Product storefront cache resource helpers must be imported from
@@ -193,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'
 
@@ -200,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
@@ -329,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,
@@ -880,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
@@ -1325,10 +1403,8 @@ 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.
 
 ```typescript
-import {
-  createCommerceIdempotencyKey,
-  isCommerceSDKError,
-} from '@01.software/sdk'
+import { createCommerceIdempotencyKey } from '@01.software/sdk'
+import { isCommerceSDKError } from '@01.software/sdk/errors'
 
 const checkoutIdempotencyKey = createCommerceIdempotencyKey()
 const { checkout, checkoutToken } = await client.commerce.checkouts.create({
@@ -1369,6 +1445,32 @@ if (
   window.location.assign(portOneSession.nextAction.checkoutUrl)
 }
 
+// Standard V2 is a distinct Browser SDK capability, not a Hosted fallback.
+// Do not treat the SDK result or mobile redirect as payment finality.
+const standardPortOneSession =
+  await client.commerce.paymentSessions.createPortOne({
+    checkoutToken,
+    provider: 'portone',
+    providerOptions: { profile: 'standard_v2', paymentMethod: 'CARD' },
+    idempotencyKey: createCommerceIdempotencyKey(),
+  })
+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`.
+  // 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.
+}
+
 // Browser recovery requires the parent capability.
 await client.commerce.paymentSessions.retrieve({
   paymentSessionId: paymentSession.id,
@@ -1386,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()
@@ -1424,6 +1544,12 @@ 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 }`.
 
+Custom bridge sessions intentionally remain `null` in
+`checkout.paymentState.activePaymentSession`: Checkout exposes only managed
+adapters from its closed provider vocabulary. Persist the `providerSessionId`
+returned by `custom.create` and use `custom.retrieve` with that identity as the
+supported custom-lane settlement recovery path.
+
 ```typescript
 const customSession = await server.commerce.paymentSessions.custom.create({
   provider: 'my-provider',
@@ -1467,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
@@ -1491,6 +1631,38 @@ Canonical commerce error envelopes become `CommerceSDKError`. Branch on its
 stable `reason`, inspect `retryable`, and log `requestId`; a newer server reason
 is preserved as `reason: 'unknown_commerce_error'` plus `rawReason`.
 
+Non-commerce endpoints preserve their open-ended machine reason separately as
+`SDKError.apiReason`. Use `getSDKErrorReason(error)` when shared error handling
+must read either family: it returns the canonical commerce reason, the verbatim
+unknown commerce `rawReason`, or the non-commerce `apiReason`. Existing
+`details` payloads remain available for compatibility, but consumers no longer
+need to normalize `details.reason` and `details.body.reason` themselves.
+
+#### Idempotent mutation results are not exactly-once receipts
+
+No commerce mutation response field is a safe exactly-once gate for a
+non-idempotent side effect such as an operational alert, outbound webhook, or
+ledger entry. Use a consumer-owned durable claim keyed by the side effect's
+stable logical identity. The public webhook guide's
+[`processOnce`](https://docs.01.software/developers/webhooks) pattern uses a
+database unique key, queue idempotency store, or provider-safe send ledger.
+
+`custom.confirm` returns `alreadyConfirmed: true` when the session was already
+confirmed at observation time. It does not attribute the transition to the
+current call. The field is absent from the initial successful confirmation, so
+code that only interprets the response shape must test
+`'alreadyConfirmed' in result`, not `result.alreadyConfirmed === false`. That
+presence check is still not a side-effect gate: when the initial commit succeeds
+but its response is lost, a retry returns `alreadyConfirmed: true` and would
+otherwise silently miss the transition.
+
+Likewise, the `orders.cancelOrder` fields `cancelCommitted` and
+`alreadyCanceled` are domain effect dispositions, not transport replay markers.
+A same-key retry replays the cached initial 2xx body byte-for-byte and can
+therefore return the original `cancelCommitted: true` again. Neither field says
+whether the response was replayed or whether an external side effect has already
+run.
+
 ### Commerce Orders (post-placement operations)
 
 Provider-paid `orders.create`, `orders.confirmPayment`, and ordinary
@@ -1505,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' })
@@ -1571,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
@@ -1778,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
@@ -1793,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
@@ -1802,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
@@ -1837,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)) {
@@ -1862,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
@@ -1879,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`                                                                                                 |
@@ -1889,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