@01.software/cli 0.10.6 → 0.11.0

package/dist/mcp/http.js

@@ -12,7 +12,7 @@ import {
   mcpServicePublicJwks,
   requestContext,
   runWithMcpTelemetry
-} from "./chunk-2ULP5WQH.js";
+} from "./chunk-3TIDAOYP.js";
 
 // src/transport/http.ts
 import { createServer as createServer2 } from "http";

package/dist/mcp/stdio.js

@@ -1,6 +1,6 @@
 import {
   createServer
-} from "./chunk-2ULP5WQH.js";
+} from "./chunk-3TIDAOYP.js";
 
 // src/transport/stdio.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/mcp/vercel.js

@@ -760,14 +760,14 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-order",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "POST /api/checkout",
+    consoleSurface: "POST /api/orders/checkout",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
   "create-order": {
     category: "mutation-order",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "POST /api/orders",
+    consoleSurface: "POST /api/orders/create",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
   "confirm-payment": {
@@ -782,7 +782,7 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-order",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "PATCH /api/orders/{id}",
+    consoleSurface: "POST /api/orders/update",
     annotationPolicy: DESTRUCTIVE_IDEMPOTENT_MUTATION_ANNOTATION,
     exemptionReason: REASON_IDEMPOTENT_DESTRUCTIVE_UPDATE
   },
@@ -791,14 +791,14 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-fulfillment",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "POST /api/orders/{id}/fulfillments",
+    consoleSurface: "POST /api/orders/create-fulfillment",
     annotationPolicy: NON_DESTRUCTIVE_MUTATION_ANNOTATION
   },
   "update-fulfillment": {
     category: "mutation-fulfillment",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "PATCH /api/fulfillments/{id}",
+    consoleSurface: "POST /api/orders/update-fulfillment",
     annotationPolicy: DESTRUCTIVE_IDEMPOTENT_MUTATION_ANNOTATION,
     exemptionReason: REASON_IDEMPOTENT_DESTRUCTIVE_UPDATE
   },
@@ -807,14 +807,14 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-return",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "POST /api/returns",
+    consoleSurface: "POST /api/returns/create",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
   "update-return": {
     category: "mutation-return",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "PATCH /api/returns/{id}",
+    consoleSurface: "POST /api/returns/update",
     annotationPolicy: DESTRUCTIVE_IDEMPOTENT_MUTATION_ANNOTATION,
     exemptionReason: REASON_IDEMPOTENT_DESTRUCTIVE_UPDATE
   },
@@ -822,7 +822,7 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-return",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "POST /api/returns/with-refund",
+    consoleSurface: "POST /api/returns/return-refund",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
   // ── Transaction mutations (mcp:write, tenant-admin) ──
@@ -830,7 +830,7 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-transaction",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "PATCH /api/transactions/{id}",
+    consoleSurface: "POST /api/transactions/update",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
   // ── Field-config mutations (mcp:write, tenant-admin) ──
@@ -1430,12 +1430,12 @@ var schema5 = {
     "delivered",
     "confirmed"
   ]).describe(
-    "New order status. Return-related statuses (return_requested, return_processing, returned) must be set via Return endpoints."
+    "New operator-driven order status. The schema keeps SDK status values for compatibility, but the Console update endpoint rejects server-derived statuses (paid, canceled, returned, refunded); those must be set by payment/refund flows, and return-related statuses must be set via Return endpoints."
   )
 };
 var metadata5 = {
   name: "update-order",
-  description: "Update order status. Automatically adjusts stock on status changes (e.g., canceled restores stock).",
+  description: "Update operator-driven order status. Console accepts transitions such as paid\u2192preparing/shipped/delivered/confirmed and rejects server-derived payment/refund statuses such as paid, canceled, returned, and refunded; the MCP schema keeps SDK status values for compatibility.",
   annotations: {
     title: "Update order status",
     readOnlyHint: false,
@@ -1689,12 +1689,12 @@ import { z as z11 } from "zod";
 var schema12 = {
   returnId: z11.string().min(1).describe("Return ID (required)"),
   status: z11.enum(["processing", "approved", "rejected", "completed"]).describe(
-    "New return status (required). Valid transitions: requested\u2192processing/rejected, processing\u2192approved/rejected, approved\u2192completed"
+    "New operator-driven return status (required). The schema keeps SDK status values for compatibility, but Console accepts only requested\u2192processing/rejected and processing\u2192approved/rejected here; completed is server-derived and must be set by return-with-refund."
   )
 };
 var metadata12 = {
   name: "update-return",
-  description: "Update return status with FSM validation. Restores inventory on completion, reverts order status on rejection.",
+  description: "Update operator-driven return status with FSM validation. Rejection can restore the order flow; completion and inventory restoration are handled by return-with-refund after provider-verified refund, while the MCP schema keeps SDK status values for compatibility.",
   annotations: {
     title: "Update return status",
     readOnlyHint: false,
@@ -1708,7 +1708,10 @@ async function updateReturn({
 }) {
   try {
     const client = getClient();
-    const result = await client.commerce.orders.updateReturn({ returnId, status });
+    const result = await client.commerce.orders.updateReturn({
+      returnId,
+      status
+    });
     return toolSuccess({ data: result });
   } catch (error) {
     return toolError(error);
@@ -1719,7 +1722,7 @@ async function updateReturn({
 var schema13 = ReturnWithRefundSchema.shape;
 var metadata13 = {
   name: "return-with-refund",
-  description: "Combined return + refund operation. Creates return, restores stock, cancels transaction, updates order status.",
+  description: "Combined provider-verified return + refund operation. Creates a completed return, restores eligible stock, records the refund transaction, and advances the order to the returned state.",
   annotations: {
     title: "Return with refund",
     readOnlyHint: false,
@@ -1733,6 +1736,7 @@ async function returnWithRefund({
   reasonDetail,
   returnItems,
   refundAmount,
+  returnShippingFee,
   pgPaymentId,
   paymentKey,
   refundReceiptUrl
@@ -1745,6 +1749,7 @@ async function returnWithRefund({
       reasonDetail,
       returnItems,
       refundAmount,
+      returnShippingFee,
       pgPaymentId,
       paymentKey,
       refundReceiptUrl
@@ -2045,7 +2050,7 @@ var schema23 = {
 };
 var metadata23 = {
   name: "product-detail",
-  description: "Fetch full product detail by slug or id. Returns one resolver-ready product with variants, option slugs, option value slugs/media, brand, categories, tags, images, videos, and listing rollup, or null if missing/unpublished/wrong tenant/feature disabled.",
+  description: "Fetch full product detail by slug or id. Returns one resolver-ready product with variants, option slugs, option value slugs/media, brand, categories, tags, images, videos, and listing rollup, or found:false with a reason if missing/unpublished/feature disabled. Permission/auth errors still throw.",
   annotations: {
     title: "Get product detail",
     readOnlyHint: true,
@@ -3675,8 +3680,9 @@ You can perform the "${goal}" task by following the patterns above.
 ### Product detail page (slug-based)
 
 \`\`\`typescript
-const product = await client.commerce.product.detail({ slug })
-if (!product) return notFound()
+const result = await client.commerce.product.detail({ slug })
+if (!result.found) return notFound()
+const product = result.product
 // product: { product, variants, options, brand, categories, tags, images, videos, listing }
 \`\`\`
 
@@ -3912,12 +3918,13 @@ const order = await client.commerce.orders.checkout({
 1. **Create Return** \u2192 \`create-return\` tool
    - Order must be \`delivered\` or \`confirmed\`
    - Specify returnItems and refundAmount
-   - Return status: requested \u2192 processing \u2192 approved \u2192 completed
+   - Operator transitions: requested \u2192 processing/rejected, processing \u2192 approved/rejected
+   - \`completed\` is server-derived and requires \`return-with-refund\`
 
 ### Option B: Return + Refund (atomic, recommended)
 1. **Return with Refund** \u2192 \`return-with-refund\` tool
    - Handles return + stock restoration + transaction update in one call
-   - Return immediately completed (bypasses FSM)
+   - Sets the return to \`completed\` after provider-verified refund
    - Requires pgPaymentId and paymentKey for provider-verified refund
 
 ### Key Points
@@ -3933,8 +3940,9 @@ await client.commerce.orders.returnWithRefund({
   orderNumber: 'ORD-240101-001',
   reason: 'defective',
   reasonDetail: 'Product arrived damaged',
-  returnItems: [{ orderItem: 'oi-id', quantity: 1 }],
+  returnItems: [{ orderItem: 'oi-id', quantity: 1, restockingFee: 500 }],
   refundAmount: 29900,
+  returnShippingFee: 1500,
   pgPaymentId: 'pay_xxx',
   paymentKey: 'payment_key_xxx'
 })
@@ -5541,12 +5549,12 @@ const ret = await client.commerce.orders.createReturn({
 \`\`\`
 
 ### updateReturn()
-Update return status.
+Update operator-driven return status. \`completed\` is server-derived and must go through \`returnWithRefund()\`.
 
 \`\`\`typescript
 const ret = await client.commerce.orders.updateReturn({
   returnId: 'return-id',
-  status: 'processing',  // processing | approved | completed | rejected
+  status: 'processing',  // processing | approved | rejected
 })
 \`\`\`
 
@@ -5559,9 +5567,10 @@ const result = await client.commerce.orders.returnWithRefund({
   reason?: 'defective',
   reasonDetail?: 'Screen cracked on arrival',
   returnItems: [
-    { orderItem: 'order-item-id', quantity: 1 }
+    { orderItem: 'order-item-id', quantity: 1, restockingFee?: 500 }
   ],
   refundAmount: 29900,
+  returnShippingFee?: 1500,
   pgPaymentId: 'provider-payment-id',  // required
   paymentKey: 'provider-payment-key',  // required for provider refund
   refundReceiptUrl?: 'https://...',
@@ -6196,11 +6205,11 @@ var metadata49 = {
 function handler18() {
   return `# Webhooks
 
-The platform dispatches HMAC-SHA256 signed webhook events to your registered URLs. Tenant developers own routing inside their webhook handler.
+The platform dispatches HMAC-SHA256 signed webhook events to registered URLs. Tenant developers own routing inside their webhook handler.
 
 ## Webhook Handling
 
-Use the SDK \`handleWebhook\` helper to verify signatures. For customer auth events, use \`createCustomerAuthWebhookHandler\` to wire delivery behavior in your app.
+Use the SDK \`handleWebhook\` helper to verify signatures. For customer auth events, use \`createCustomerAuthWebhookHandler\`; for semantic events, use SDK guards before reading event-specific fields.
 
 \`\`\`typescript
 import { handleWebhook, createCustomerAuthWebhookHandler } from '@01.software/sdk/webhook'
@@ -6253,28 +6262,119 @@ export async function POST(request: Request) {
 }
 \`\`\`
 
+## Commerce Notification Handler Example
+
+\`\`\`typescript
+import {
+  handleWebhook,
+  isCommerceNotificationWebhookEvent,
+} from '@01.software/sdk/webhook'
+
+function getWebhookSecret(): string {
+  const secret = process.env.WEBHOOK_SECRET
+  if (!secret) throw new Error('WEBHOOK_SECRET is required')
+  return secret
+}
+
+export async function POST(request: Request) {
+  return handleWebhook(request, async (event) => {
+    if (!isCommerceNotificationWebhookEvent(event)) return
+
+    const idempotencyKey = \`\${event.notification.intentId}:\${event.notification.dedupeKey}\`
+    const processed = await processOnce(idempotencyKey, async () => {
+      if (event.notification.event === 'orderPaid') {
+        const orderId = event.notification.orderId ?? event.data.orderId
+        if (orderId) await updateOrderWorkflow(orderId)
+      }
+
+      if (event.notification.event === 'fulfillmentShipped') {
+        const fulfillmentId =
+          event.notification.fulfillmentId ?? event.data.fulfillmentId
+        if (fulfillmentId) await updateFulfillmentWorkflow(fulfillmentId)
+      }
+    })
+
+    if (!processed) return
+  }, {
+    secret: getWebhookSecret(),
+  })
+}
+\`\`\`
+
+Back \`processOnce()\` with durable storage such as a database unique key or queue idempotency store; do not use process-local memory for webhook idempotency.
+
+## Headless Commerce Email Workers
+
+For tenant-owned transactional email, use \`commerce.notification\` as the trigger and build a signed worker with \`createCommerceEmailWebhookHandler()\`. 01.software owns event timing, delivery retries, signing, and idempotency signals; the tenant worker owns template rendering, provider credentials, extra order/customer fetches via \`createServerClient\`, and final delivery through a tenant provider such as Resend.
+
+Use \`getCommerceNotificationIdempotencyKey(event)\` or the \`idempotencyKey\` passed by \`createCommerceEmailWebhookHandler()\`, then guard provider sends with durable \`processOnce(idempotencyKey, ...)\` storage. The webhook payload is PII-light and is not enough for recipient data, so fetch recipient/template context with server SDK credentials. In the v1 headless path, do not store tenant ESP secrets in 01.software and do not ask 01.software to send directly through the tenant provider.
+
 ## Webhook Payload Structure
 
 All webhook events share this envelope:
 
 \`\`\`typescript
 {
-  collection: string,    // e.g. 'customers'
-  operation: string,     // e.g. 'password-reset'
-  data: object,          // event-specific payload
+  collection: string,
+  operation: string,
+  data: object,
+  eventType?: string,
+  change?: object,
+  notification?: object,
+  timestamp?: string,
+  deliveryId?: string,
 }
 \`\`\`
 
 ## Event Types
 
+### Commerce Notification
+
+V1 commerce notification webhooks use \`eventType: "commerce.notification"\` and \`operation: "notification"\`. The public SDK exports \`COMMERCE_NOTIFICATION_EVENT_TYPE\`, \`COMMERCE_NOTIFICATION_OPERATION\`, commerce notification types, and \`isCommerceNotificationWebhookEvent()\` from \`@01.software/sdk/webhook\`.
+
+Canonical example (public operational identifiers only; no PII, payment/provider fields, metadata, tracking number, or tracking URL):
+
+\`\`\`json
+{
+  "eventType": "commerce.notification",
+  "collection": "orders",
+  "operation": "notification",
+  "data": {
+    "orderId": "order_123",
+    "orderNumber": "ORD-1001",
+    "status": "paid",
+    "totalAmount": 5000,
+    "currency": "KRW"
+  },
+  "notification": {
+    "event": "orderPaid",
+    "intentId": "intent_123",
+    "dedupeKey": "orderPaid:order_123",
+    "orderId": "order_123"
+  },
+  "timestamp": "2026-05-29T00:00:00.000Z",
+  "deliveryId": "delivery_attempt_123"
+}
+\`\`\`
+
+Use \`notification.intentId\` plus \`notification.dedupeKey\` for semantic idempotency. \`deliveryId\` is per delivery attempt / observability and may not be stable across semantic retries.
+Some normalized deliveries may include \`data.source\` or \`change\` metadata, but handlers should treat those fields as optional. Route from \`notification.orderId\`, \`notification.fulfillmentId\`, \`notification.returnId\`, or the matching typed \`data.*Id\` field.
+
+V1 source subscription semantics:
+
+- \`orderPaid\` and \`orderDelivered\` are delivered through \`orders\`-scoped endpoints.
+- \`fulfillmentShipped\` is delivered through \`fulfillments\`-scoped endpoints.
+- \`returnRequested\` and \`returnCompleted\` are delivered through \`returns\`-scoped endpoints.
+- Empty, unscoped, and all-collection endpoints do not receive v1 semantic commerce notifications.
+
 ### Collection Order Changed
 
 Admin Panel manual ordering is delivered as a semantic collection update:
 
 - \`operation\` remains \`"update"\` for compatibility.
 - \`eventType\` is \`"collection.orderChanged"\`.
-- \`change.scope\` identifies collection-level ordering versus join ordering.
 - SDK handlers should use \`isOrderChangedWebhookEvent()\` from \`@01.software/sdk/webhook\`.
+- \`change.scope\` identifies collection-level ordering versus join ordering.
 - Route on public semantics such as \`change.scope.collection\`, \`change.scope.field\`, and \`change.moved.id\`.
 - Do not branch on hidden Payload order fields or private backing collections; diagnostic fields may still be present.
 - Customer group member ordering is currently unsupported and does not emit a semantic order-change webhook.
@@ -6324,8 +6424,8 @@ Dispatched when a customer calls \`client.customer.forgotPassword(email)\`.
     customerId: string,
     email: string,
     name: string,
-    resetPasswordToken: string,   // raw token to include in reset link
-    resetPasswordExpiresAt: string,  // ISO 8601 expiry (1 hour from dispatch)
+    resetPasswordToken: string,
+    resetPasswordExpiresAt: string,
   }
 }
 \`\`\`
@@ -6340,11 +6440,13 @@ async function sendPasswordResetEmail(data: {
   resetPasswordToken: string
   resetPasswordExpiresAt: string
 }) {
-  const resetUrl = \`https://yourstore.com/reset-password?token=\${data.resetPasswordToken}\`
+  const resetUrl = new URL('https://yourstore.com/reset-password')
+  resetUrl.searchParams.set('token', data.resetPasswordToken)
+
   await emailService.send({
     to: data.email,
     subject: 'Reset your password',
-    body: \`Reset link (expires \${data.resetPasswordExpiresAt}): \${resetUrl}\`,
+    body: \`Reset link (expires \${data.resetPasswordExpiresAt}): \${resetUrl.toString()}\`,
   })
 }
 \`\`\`
@@ -6355,7 +6457,7 @@ Failed webhook deliveries are queued with automatic retries. Ensure your handler
 
 ## Webhook Configuration
 
-Configure webhook URLs in the 01.software console under Tenant Settings > Webhooks. Multiple URLs can be registered; all receive every event.`;
+Configure webhook URLs in the 01.software console under Tenant Settings > Webhooks. Multiple URLs can be registered; scoped endpoints receive events for their configured source collection.`;
 }
 
 // src/resources/(docs)/product-detail.ts
@@ -6383,8 +6485,8 @@ const client = createClient({
 })
 
 const detail = await client.commerce.product.detail({ slug: 'my-product' })
-if (!detail) return notFound()
-const selection = resolveProductSelection(detail, {
+if (!detail.found) return notFound()
+const selection = resolveProductSelection(detail.product, {
   search: '?opt.option-color=color-black',
 })
 // selection.selectedVariant, selection.price, selection.stock, selection.media
@@ -6435,18 +6537,20 @@ export default async function ProductPage({ params }: { params: { slug: string }
     publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
   })
   const detail = await client.commerce.product.detail({ slug: params.slug })
-  if (!detail) return notFound()
-  return <ProductView detail={detail} />
+  if (!detail.found) return notFound()
+  return <ProductView detail={detail.product} />
 }
 \`\`\`
 
-## The \`null\` return contract
+## The \`ProductDetailResult\` return contract
+
+The endpoint returns 404 for \`not_found\`, \`not_published\`, or \`feature_disabled\`. The SDK maps those product-detail 404s to \`{ found: false, reason }\` so consumer UIs can render a standard 404, preview CTA, or feature-gating UI. Permission/auth errors, including 403 tenant mismatches, still throw typed SDK errors.
 
-The endpoint returns 404 for \`not_found\`, \`not_published\`, \`tenant_mismatch\`, or \`feature_disabled\`. The SDK collapses all 404s to \`null\` so consumer UIs render one "not available" path.
+Successful product payloads expose inventory rollups without sentinel values: \`product.totalInventory\` is the tracked stock sum across non-unlimited variants, \`null\` when no variants are tracked, and \`product.hasUnlimitedVariant\` signals whether any variant is unlimited.
 
 ## Backend correlation
 
-Log \`client.lastRequestId\` against backend logs \u2014 the endpoint records the exact 404 code alongside the request ID.`;
+Log \`client.lastRequestId\` against backend logs \u2014 the endpoint records the exact 404 reason alongside the request ID.`;
 }
 
 // src/server.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@01.software/cli",
-  "version": "0.10.6",
+  "version": "0.11.0",
   "description": "CLI tool for 01.software platform",
   "repository": {
     "type": "git",
@@ -22,7 +22,7 @@
     "commander": "^14.0.3",
     "picocolors": "^1.1.1",
     "zod": "^4.4.3",
-    "@01.software/sdk": "^0.32.0"
+    "@01.software/sdk": "^0.33.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.18",