@01.software/sdk 0.49.0 → 0.56.1

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,
@@ -718,8 +779,8 @@ Membership self-service is split by credential boundary:
 - Browser/customer JWT clients can read the signed-in customer's current or
   latest membership and request cancellation for active, trialing, or past-due
   memberships.
-- Server clients with a Secret Key can subscribe a customer after the storefront
-  has completed the delegated first charge.
+- Server clients with a Secret Key prepare a paid customer subscription before
+  the tenant's PSP executes the first charge.
 
 ```typescript
 import { createClient } from '@01.software/sdk'
@@ -740,28 +801,71 @@ const server = createServerClient({
   secretKey: process.env.SOFTWARE_SECRET_KEY!,
 })
 
-await server.memberships.subscribe({
+const prepared = await server.memberships.subscribe({
   planId: 'plan_123',
+  priceId: 'price_monthly_123',
   customerId: 'customer_123',
   customerRef: 'cus_provider_123',
-  pgPaymentId: 'pay_123',
-  amount: 9900,
-  currency: 'KRW',
   subscribeIntentKey: 'checkout-session-123',
   card: { last4: '4242', brand: 'visa' },
 })
+
+if (prepared.status === 'incomplete') {
+  await tenantPsp.charge({
+    idempotencyKey: prepared.firstCharge.idempotencyKey,
+    amount: prepared.firstCharge.amount,
+    currency: prepared.firstCharge.currency,
+  })
+  // Post the PSP outcome to Console's existing signed charge-result webhook.
+}
 ```
 
 `subscribeIntentKey` is sent as `X-Idempotency-Key`; it is not part of the JSON
-body. Replays must use the same plan, customer reference, amount, currency, and
-paid-start provider payment id snapshot as the original incomplete membership.
-Trial subscriptions may omit `pgPaymentId` because no first-period charge has
-been captured yet; paid starts must include the provider payment id that funded
-the first period.
+body. A paid response is `incomplete` and contains the immutable first-charge
+instruction. The tenant charges its PSP with `firstCharge.idempotencyKey`, then
+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
+`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
+charge is pending. A replay after settlement or `expiresAt` returns `409`
+instead of a payment instruction.
 `memberships.me()` and browser `memberships.cancel()` require the customer JWT
 configured on the client. Refund webhook `refundedAmount` values are cumulative
 charge totals, not per-event deltas.
 
+### Source-aware customer groups (server only)
+
+Manage manual Customer Group membership through the shaped server API. The
+read result includes every current reason a customer qualifies, so revoking a
+manual source does not hide a still-active Membership source.
+
+```typescript
+const page = await server.customerGroups.listMembers({
+  groupId: '00000000-0000-4000-8000-000000000002',
+  limit: 100,
+})
+
+await server.customerGroups.grantMember({
+  groupId: '00000000-0000-4000-8000-000000000002',
+  customerId: '00000000-0000-4000-8000-000000000003',
+  reason: 'support-approved',
+})
+
+await server.customerGroups.revokeMember({
+  groupId: '00000000-0000-4000-8000-000000000002',
+  customerId: '00000000-0000-4000-8000-000000000003',
+})
+```
+
+Keep these calls in trusted server code. Do not mutate `customers.groups`
+directly: after source-authority activation it is a read-compatible projection
+and direct writes return `customer_groups_direct_write_retired`.
+
 ## Storefront performance defaults
 
 - **PLP:** prefer `commerce.product.listingPage()` or `useProductListingPage()` (GET `/api/products/listing-groups/query/catalog`, CDN-cacheable, card-ready). Use `listingGroupsCatalog({ productIds })` only when IDs are already known. Treat the full listing-groups response shape as a server-auth escape hatch because it can include operational stock fields. Avoid fetching a product list and then calling `detail()` per card.
@@ -883,6 +987,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 +1501,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 +1531,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 +1636,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 +1720,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 +1808,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 +2015,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 +2041,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 +2053,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 +2106,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 +2131,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 +2148,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 +2158,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