@01.software/cli 0.10.5 → 0.10.6

package/dist/mcp/vercel.js

@@ -15,6 +15,75 @@ var MCP_CONSOLE_SERVICE_AUDIENCE = "https://api.01.software/internal/mcp";
 var MCP_CONSOLE_SERVICE_SCOPE = "console:mcp_proxy";
 var MCP_SERVICE_TOKEN_LIFETIME_SECONDS = 60;
 
+// src/resource-inventory.ts
+var MCP_RESOURCE_INVENTORY = [
+  { uri: "config://app", label: "config", registeredName: "app-config" },
+  {
+    uri: "collections://schema",
+    label: "collections-schema",
+    registeredName: "collections-schema"
+  },
+  {
+    uri: "docs://sdk/getting-started",
+    label: "getting-started",
+    registeredName: "docs-getting-started"
+  },
+  { uri: "docs://sdk/guides", label: "guides", registeredName: "docs-guides" },
+  { uri: "docs://sdk/api", label: "api", registeredName: "docs-api" },
+  {
+    uri: "docs://sdk/query-builder",
+    label: "query-builder",
+    registeredName: "docs-query-builder"
+  },
+  {
+    uri: "docs://sdk/react-query",
+    label: "react-query",
+    registeredName: "docs-react-query"
+  },
+  {
+    uri: "docs://sdk/server-api",
+    label: "server-api",
+    registeredName: "docs-server-api"
+  },
+  {
+    uri: "docs://sdk/customer-auth",
+    label: "customer-auth",
+    registeredName: "docs-customer-auth"
+  },
+  {
+    uri: "docs://sdk/browser-vs-server",
+    label: "browser-vs-server",
+    registeredName: "docs-browser-vs-server"
+  },
+  {
+    uri: "docs://sdk/file-upload",
+    label: "file-upload",
+    registeredName: "docs-file-upload"
+  },
+  {
+    uri: "docs://sdk/webhook",
+    label: "webhook",
+    registeredName: "docs-webhook"
+  },
+  {
+    uri: "docs://sdk/product-detail",
+    label: "product-detail",
+    registeredName: "docs-product-detail"
+  }
+];
+var MCP_RESOURCE_LABELS = MCP_RESOURCE_INVENTORY.map(
+  (resource) => resource.label
+);
+function mcpResourceUri(registeredName) {
+  const resource = MCP_RESOURCE_INVENTORY.find(
+    (entry) => entry.registeredName === registeredName
+  );
+  if (!resource) {
+    throw new Error(`Unknown MCP resource inventory entry: ${registeredName}`);
+  }
+  return resource.uri;
+}
+
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -250,6 +319,38 @@ var transactionStatusSchema = z2.enum([
   "failed",
   "canceled"
 ]);
+var entityIdSchema = z2.union([z2.string(), z2.number()]).transform(String);
+var createOrderItemSchema = z2.object({
+  product: entityIdSchema,
+  variant: entityIdSchema,
+  option: entityIdSchema,
+  quantity: z2.number().int().positive("quantity must be a positive integer"),
+  unitPrice: z2.number().optional(),
+  totalPrice: z2.number().optional()
+});
+var createOrderSchema = z2.object({
+  pgPaymentId: z2.string().min(1).optional(),
+  orderNumber: z2.string().min(1, "orderNumber is required"),
+  customer: entityIdSchema.optional(),
+  customerSnapshot: z2.object({
+    name: z2.string().optional(),
+    email: z2.string().email("Invalid email format"),
+    phone: z2.string().optional()
+  }),
+  shippingAddress: z2.object({
+    postalCode: z2.string().optional(),
+    address: z2.string().optional(),
+    detailAddress: z2.string().optional(),
+    deliveryMessage: z2.string().optional(),
+    recipientName: z2.string().optional(),
+    phone: z2.string().optional()
+  }),
+  orderItems: z2.array(createOrderItemSchema).min(1, "At least one order item is required").max(100, "Maximum 100 items per order"),
+  totalAmount: z2.number().nonnegative("totalAmount must be non-negative"),
+  shippingAmount: z2.number().min(0).optional(),
+  discountCode: z2.string().optional()
+});
+var CreateOrderSchema = createOrderSchema;
 var updateTransactionSchema = z2.object({
   pgPaymentId: z2.string().min(1, "pgPaymentId is required").describe("PG payment ID (required)"),
   status: transactionStatusSchema.describe(
@@ -284,6 +385,7 @@ var confirmPaymentSchema = z2.object({
   ]).optional(),
   metadata: z2.record(z2.string(), z2.unknown()).optional()
 }).strict();
+var ConfirmPaymentSchema = confirmPaymentSchema;
 var returnReasonSchema = z2.enum([
   "change_of_mind",
   "defective",
@@ -413,6 +515,11 @@ var MCP_TOOL_CONTRACT = {
     oauthScope: "mcp:write",
     readOnly: false
   },
+  "confirm-payment": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
   "update-order": {
     consoleRole: "tenant-admin",
     oauthScope: "mcp:write",
@@ -663,6 +770,14 @@ var TOOL_POLICY_MANIFEST = {
     consoleSurface: "POST /api/orders",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
+  "confirm-payment": {
+    category: "mutation-transaction",
+    oauthScope: MCP_SCOPES.write,
+    consoleRole: "tenant-admin",
+    consoleSurface: "POST /api/orders/confirm-payment",
+    annotationPolicy: DESTRUCTIVE_IDEMPOTENT_MUTATION_ANNOTATION,
+    exemptionReason: REASON_IDEMPOTENT_DESTRUCTIVE_UPDATE
+  },
   "update-order": {
     category: "mutation-order",
     oauthScope: MCP_SCOPES.write,
@@ -756,7 +871,15 @@ var TOOL_POLICY_MANIFEST = {
     annotationPolicy: READ_ONLY_ANNOTATION
   }
 };
-function evaluateToolPolicy(toolName, scopes) {
+var CONSOLE_ROLE_RANK = {
+  "tenant-viewer": 0,
+  "tenant-editor": 1,
+  "tenant-admin": 2
+};
+function hasRequiredConsoleRole(tenantRole, requiredRole) {
+  return CONSOLE_ROLE_RANK[tenantRole] >= CONSOLE_ROLE_RANK[requiredRole];
+}
+function evaluateToolPolicy(toolName, scopes, tenantRole) {
   if (!isMcpToolName(toolName)) {
     return {
       allowed: false,
@@ -772,6 +895,13 @@ function evaluateToolPolicy(toolName, scopes) {
       message: `Tool ${toolName} requires ${entry.oauthScope}`
     };
   }
+  if (!hasRequiredConsoleRole(tenantRole, entry.consoleRole)) {
+    return {
+      allowed: false,
+      reason: "insufficient_role",
+      message: `Tool ${toolName} requires ${entry.consoleRole}`
+    };
+  }
   return { allowed: true, entry };
 }
 
@@ -1264,25 +1394,7 @@ async function getOrder({
 }
 
 // src/tools/create-order.ts
-import { z as z6 } from "zod";
-var schema4 = {
-  pgPaymentId: z6.string().optional().describe("PG payment ID (optional \u2014 omit for free orders)"),
-  orderNumber: z6.string().min(1).describe("Unique order number (required)"),
-  customerSnapshot: z6.object({
-    name: z6.string().optional().describe("Customer name"),
-    email: z6.string().describe("Customer email (required)"),
-    phone: z6.string().optional().describe("Customer phone")
-  }).describe("Customer snapshot at time of order (required)"),
-  shippingAddress: z6.record(z6.string(), z6.unknown()).describe(
-    "Shipping address object (required). Fields: postalCode, address1, address2, deliveryMessage, recipientName, phone"
-  ),
-  orderItems: z6.array(z6.record(z6.string(), z6.unknown())).describe(
-    "Array of order item objects (required). Each: { product, variant, option, quantity, unitPrice?, totalPrice? }"
-  ),
-  totalAmount: z6.number().nonnegative().describe("Total order amount (required, min 0)"),
-  shippingAmount: z6.number().nonnegative().optional().describe("Shipping amount (optional, default 0)"),
-  discountCode: z6.string().optional().describe("Discount code to apply (optional)")
-};
+var schema4 = CreateOrderSchema.shape;
 var metadata4 = {
   name: "create-order",
   description: "Create a new order with products and shipping information. Supports idempotency.",
@@ -1296,9 +1408,8 @@ var metadata4 = {
 async function createOrder(params) {
   try {
     const client = getClient();
-    const result = await client.commerce.orders.create(
-      params
-    );
+    const parsed = CreateOrderSchema.parse(params);
+    const result = await client.commerce.orders.create(parsed);
     return toolSuccess({ data: result });
   } catch (error) {
     return toolError(error);
@@ -1306,10 +1417,10 @@ async function createOrder(params) {
 }
 
 // src/tools/update-order.ts
-import { z as z7 } from "zod";
+import { z as z6 } from "zod";
 var schema5 = {
-  orderNumber: z7.string().min(1).describe("Order number (required)"),
-  status: z7.enum([
+  orderNumber: z6.string().min(1).describe("Order number (required)"),
+  status: z6.enum([
     "pending",
     "paid",
     "failed",
@@ -1346,15 +1457,15 @@ async function updateOrder({
 }
 
 // src/tools/checkout.ts
-import { z as z8 } from "zod";
+import { z as z7 } from "zod";
 var schema6 = {
-  cartId: z8.string().min(1).describe("Cart ID to convert to order (required)"),
-  pgPaymentId: z8.string().optional().describe("PG payment ID (optional \u2014 omit for free orders)"),
-  orderNumber: z8.string().min(1).describe("Unique order number (required)"),
-  customerSnapshot: z8.record(z8.string(), z8.unknown()).describe(
+  cartId: z7.string().min(1).describe("Cart ID to convert to order (required)"),
+  pgPaymentId: z7.string().optional().describe("PG payment ID (optional \u2014 omit for free orders)"),
+  orderNumber: z7.string().min(1).describe("Unique order number (required)"),
+  customerSnapshot: z7.record(z7.string(), z7.unknown()).describe(
     "Customer snapshot object (required). Fields: { name?, email, phone? }"
   ),
-  discountCode: z8.string().optional().describe("Discount code to apply (optional)")
+  discountCode: z7.string().optional().describe("Discount code to apply (optional)")
 };
 var metadata6 = {
   name: "checkout",
@@ -1379,17 +1490,17 @@ async function checkout(params) {
 }
 
 // src/tools/create-fulfillment.ts
-import { z as z9 } from "zod";
+import { z as z8 } from "zod";
 var schema7 = {
-  orderNumber: z9.string().min(1).describe("Order number (required)"),
-  carrier: z9.string().optional().describe("Shipping carrier name (optional)"),
-  trackingNumber: z9.string().optional().describe(
+  orderNumber: z8.string().min(1).describe("Order number (required)"),
+  carrier: z8.string().optional().describe("Shipping carrier name (optional)"),
+  trackingNumber: z8.string().optional().describe(
     'Tracking number (optional). Setting carrier + tracking triggers "shipped" status'
   ),
-  items: z9.array(
-    z9.object({
-      orderItem: z9.string().min(1).describe("Order item ID"),
-      quantity: z9.number().int().positive().describe("Quantity to fulfill")
+  items: z8.array(
+    z8.object({
+      orderItem: z8.string().min(1).describe("Order item ID"),
+      quantity: z8.number().int().positive().describe("Quantity to fulfill")
     })
   ).describe("Array of items to fulfill (required)")
 };
@@ -1424,16 +1535,16 @@ async function createFulfillment({
 }
 
 // src/tools/update-fulfillment.ts
-import { z as z10 } from "zod";
+import { z as z9 } from "zod";
 var schema8 = {
-  fulfillmentId: z10.string().min(1).describe("Fulfillment ID (required)"),
-  status: z10.enum(["packed", "shipped", "delivered", "failed"]).describe(
+  fulfillmentId: z9.string().min(1).describe("Fulfillment ID (required)"),
+  status: z9.enum(["packed", "shipped", "delivered", "failed"]).describe(
     "New fulfillment status (required). FSM: pending\u2192packed/shipped/failed, packed\u2192shipped/failed, shipped\u2192delivered/failed"
   ),
-  carrier: z10.string().optional().describe(
+  carrier: z9.string().optional().describe(
     "Shipping carrier (optional, changeable only in pending/packed status)"
   ),
-  trackingNumber: z10.string().optional().describe(
+  trackingNumber: z9.string().optional().describe(
     "Tracking number (optional, changeable only in pending/packed status)"
   )
 };
@@ -1504,21 +1615,44 @@ async function updateTransaction({
   }
 }
 
+// src/tools/confirm-payment.ts
+var schema10 = ConfirmPaymentSchema.shape;
+var metadata10 = {
+  name: "confirm-payment",
+  description: "Confirm a provider-verified ecommerce payment through the generic payment confirmation flow.",
+  annotations: {
+    title: "Confirm payment",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true
+  }
+};
+async function confirmPayment(params) {
+  try {
+    const client = getClient();
+    const parsed = ConfirmPaymentSchema.parse(params);
+    const result = await client.commerce.orders.confirmPayment(parsed);
+    return toolSuccess({ data: result });
+  } catch (error) {
+    return toolError(error);
+  }
+}
+
 // src/tools/create-return.ts
-import { z as z11 } from "zod";
-var schema10 = {
-  orderNumber: z11.string().min(1).describe("Order number (required)"),
-  reason: z11.enum(["change_of_mind", "defective", "wrong_delivery", "damaged", "other"]).optional().describe("Return reason (optional)"),
-  reasonDetail: z11.string().optional().describe("Detailed reason text (optional)"),
-  returnItems: z11.array(
-    z11.object({
-      orderItem: z11.string().min(1).describe("Order item ID"),
-      quantity: z11.number().int().positive().describe("Quantity to return")
+import { z as z10 } from "zod";
+var schema11 = {
+  orderNumber: z10.string().min(1).describe("Order number (required)"),
+  reason: z10.enum(["change_of_mind", "defective", "wrong_delivery", "damaged", "other"]).optional().describe("Return reason (optional)"),
+  reasonDetail: z10.string().optional().describe("Detailed reason text (optional)"),
+  returnItems: z10.array(
+    z10.object({
+      orderItem: z10.string().min(1).describe("Order item ID"),
+      quantity: z10.number().int().positive().describe("Quantity to return")
     })
   ).describe("Array of products to return (required)"),
-  refundAmount: z11.number().nonnegative().describe("Refund amount (required, min 0)")
+  refundAmount: z10.number().nonnegative().describe("Refund amount (required, min 0)")
 };
-var metadata10 = {
+var metadata11 = {
   name: "create-return",
   description: "Create a return request for an order. Only works for delivered/confirmed orders. Updates order status to return_requested.",
   annotations: {
@@ -1551,14 +1685,14 @@ async function createReturn({
 }
 
 // src/tools/update-return.ts
-import { z as z12 } from "zod";
-var schema11 = {
-  returnId: z12.string().min(1).describe("Return ID (required)"),
-  status: z12.enum(["processing", "approved", "rejected", "completed"]).describe(
+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"
   )
 };
-var metadata11 = {
+var metadata12 = {
   name: "update-return",
   description: "Update return status with FSM validation. Restores inventory on completion, reverts order status on rejection.",
   annotations: {
@@ -1582,8 +1716,8 @@ async function updateReturn({
 }
 
 // src/tools/return-with-refund.ts
-var schema12 = ReturnWithRefundSchema.shape;
-var metadata12 = {
+var schema13 = ReturnWithRefundSchema.shape;
+var metadata13 = {
   name: "return-with-refund",
   description: "Combined return + refund operation. Creates return, restores stock, cancels transaction, updates order status.",
   annotations: {
@@ -1623,15 +1757,15 @@ async function returnWithRefund({
 }
 
 // src/tools/add-cart-item.ts
-import { z as z13 } from "zod";
-var schema13 = {
-  cartId: z13.string().min(1).describe("Cart ID (required)"),
-  product: z13.string().min(1).describe("Product ID (required)"),
-  variant: z13.string().min(1).describe("Product variant ID (required)"),
-  option: z13.string().min(1).describe("Product option ID (required)"),
-  quantity: z13.number().int().positive().describe("Quantity to add (required, positive integer)")
+import { z as z12 } from "zod";
+var schema14 = {
+  cartId: z12.string().min(1).describe("Cart ID (required)"),
+  product: z12.string().min(1).describe("Product ID (required)"),
+  variant: z12.string().min(1).describe("Product variant ID (required)"),
+  option: z12.string().min(1).describe("Product option ID (required)"),
+  quantity: z12.number().int().positive().describe("Quantity to add (required, positive integer)")
 };
-var metadata13 = {
+var metadata14 = {
   name: "add-cart-item",
   description: "Add a product to cart. Validates stock, merges quantity if item already exists, recalculates totals.",
   annotations: {
@@ -1664,12 +1798,12 @@ async function addCartItem({
 }
 
 // src/tools/update-cart-item.ts
-import { z as z14 } from "zod";
-var schema14 = {
-  cartItemId: z14.string().min(1).describe("Cart item ID (required)"),
-  quantity: z14.number().int().positive().describe("New quantity (required, positive integer)")
+import { z as z13 } from "zod";
+var schema15 = {
+  cartItemId: z13.string().min(1).describe("Cart item ID (required)"),
+  quantity: z13.number().int().positive().describe("New quantity (required, positive integer)")
 };
-var metadata14 = {
+var metadata15 = {
   name: "update-cart-item",
   description: "Update cart item quantity. Validates stock availability, recalculates cart totals.",
   annotations: {
@@ -1693,11 +1827,11 @@ async function updateCartItem({
 }
 
 // src/tools/remove-cart-item.ts
-import { z as z15 } from "zod";
-var schema15 = {
-  cartItemId: z15.string().min(1).describe("Cart item ID to remove (required)")
+import { z as z14 } from "zod";
+var schema16 = {
+  cartItemId: z14.string().min(1).describe("Cart item ID to remove (required)")
 };
-var metadata15 = {
+var metadata16 = {
   name: "remove-cart-item",
   description: "Remove an item from cart. Recalculates cart totals after removal.",
   annotations: {
@@ -1720,12 +1854,12 @@ async function removeCartItem({
 }
 
 // src/tools/apply-discount.ts
-import { z as z16 } from "zod";
-var schema16 = {
-  cartId: z16.string().min(1).describe("Cart ID (required)"),
-  discountCode: z16.string().describe("Discount code to apply (required)")
+import { z as z15 } from "zod";
+var schema17 = {
+  cartId: z15.string().min(1).describe("Cart ID (required)"),
+  discountCode: z15.string().describe("Discount code to apply (required)")
 };
-var metadata16 = {
+var metadata17 = {
   name: "apply-discount",
   description: "Apply a discount code to a cart. Validates the code, updates cart totals, and sets free shipping if applicable.",
   annotations: {
@@ -1749,11 +1883,11 @@ async function applyDiscount({
 }
 
 // src/tools/remove-discount.ts
-import { z as z17 } from "zod";
-var schema17 = {
-  cartId: z17.string().min(1).describe("Cart ID (required)")
+import { z as z16 } from "zod";
+var schema18 = {
+  cartId: z16.string().min(1).describe("Cart ID (required)")
 };
-var metadata17 = {
+var metadata18 = {
   name: "remove-discount",
   description: "Remove the applied discount code from a cart and recalculate totals.",
   annotations: {
@@ -1776,11 +1910,11 @@ async function removeDiscount({
 }
 
 // src/tools/clear-cart.ts
-import { z as z18 } from "zod";
-var schema18 = {
-  cartId: z18.string().min(1).describe("Cart ID (required)")
+import { z as z17 } from "zod";
+var schema19 = {
+  cartId: z17.string().min(1).describe("Cart ID (required)")
 };
-var metadata18 = {
+var metadata19 = {
   name: "clear-cart",
   description: "Remove all items from a cart, reset discount and amounts. Shipping fee is preserved.",
   annotations: {
@@ -1803,12 +1937,12 @@ async function clearCart({
 }
 
 // src/tools/validate-discount.ts
-import { z as z19 } from "zod";
-var schema19 = {
-  code: z19.string().describe("Discount code to validate (required)"),
-  orderAmount: z19.number().describe("Order amount for validation (required)")
+import { z as z18 } from "zod";
+var schema20 = {
+  code: z18.string().describe("Discount code to validate (required)"),
+  orderAmount: z18.number().describe("Order amount for validation (required)")
 };
-var metadata19 = {
+var metadata20 = {
   name: "validate-discount",
   description: "Validate a discount code. Checks active status, date range, usage limits, minimum order amount, and calculates discount.",
   annotations: {
@@ -1835,13 +1969,13 @@ async function validateDiscount({
 }
 
 // src/tools/calculate-shipping.ts
-import { z as z20 } from "zod";
-var schema20 = {
-  shippingPolicyId: z20.string().optional().describe("Shipping policy ID (uses default policy if omitted)"),
-  orderAmount: z20.number().describe("Order amount for fee calculation (required)"),
-  postalCode: z20.string().optional().describe("Postal code for Jeju surcharge detection (63000-63644)")
+import { z as z19 } from "zod";
+var schema21 = {
+  shippingPolicyId: z19.string().optional().describe("Shipping policy ID (uses default policy if omitted)"),
+  orderAmount: z19.number().describe("Order amount for fee calculation (required)"),
+  postalCode: z19.string().optional().describe("Postal code for Jeju surcharge detection (63000-63644)")
 };
-var metadata20 = {
+var metadata21 = {
   name: "calculate-shipping",
   description: "Calculate shipping fee based on order amount and postal code. Supports free shipping threshold and Jeju surcharge.",
   annotations: {
@@ -1870,18 +2004,18 @@ async function calculateShipping({
 }
 
 // src/tools/stock-check.ts
-import { z as z21 } from "zod";
-var schema21 = {
-  items: z21.array(
-    z21.object({
-      variantId: z21.string().describe("Product variant ID"),
-      quantity: z21.number().int().positive().describe("Requested quantity")
+import { z as z20 } from "zod";
+var schema22 = {
+  items: z20.array(
+    z20.object({
+      variantId: z20.string().describe("Product variant ID"),
+      quantity: z20.number().int().positive().describe("Requested quantity")
     })
   ).describe(
     "Array of items to check stock for (required, max 100). Each: { variantId, quantity }"
   )
 };
-var metadata21 = {
+var metadata22 = {
   name: "stock-check",
   description: "Batch check product option stock availability. Returns per-item availability and an allAvailable flag.",
   annotations: {
@@ -1904,12 +2038,12 @@ async function stockCheck({
 }
 
 // src/tools/product-detail.ts
-import { z as z22 } from "zod";
-var schema22 = {
-  slug: z22.string().optional().describe("Product slug (one of slug or id required)"),
-  id: z22.string().optional().describe("Product id (one of slug or id required)")
+import { z as z21 } from "zod";
+var schema23 = {
+  slug: z21.string().optional().describe("Product slug (one of slug or id required)"),
+  id: z21.string().optional().describe("Product id (one of slug or id required)")
 };
-var metadata22 = {
+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.",
   annotations: {
@@ -1937,66 +2071,66 @@ async function productDetail({
 }
 
 // src/tools/product-upsert.ts
-import { z as z23 } from "zod";
-var optionValueSchema = z23.object({
-  id: z23.string().optional().describe("Stable existing option-value ID for rename-safe updates"),
-  value: z23.string().describe("Display label (e.g. Black, S)"),
-  slug: z23.string().optional().describe(
+import { z as z22 } from "zod";
+var optionValueSchema = z22.object({
+  id: z22.string().optional().describe("Stable existing option-value ID for rename-safe updates"),
+  value: z22.string().describe("Display label (e.g. Black, S)"),
+  slug: z22.string().optional().describe(
     "Optional compatibility value token. The server generates one from value on create when omitted; not canonical identity."
   ),
-  swatchColor: z23.string().nullable().optional(),
-  thumbnail: z23.string().nullable().optional(),
-  images: z23.array(z23.string()).optional(),
-  metadata: z23.unknown().optional()
+  swatchColor: z22.string().nullable().optional(),
+  thumbnail: z22.string().nullable().optional(),
+  images: z22.array(z22.string()).optional(),
+  metadata: z22.unknown().optional()
 });
-var optionSchema = z23.object({
-  id: z23.string().optional().describe("Stable existing option ID for rename-safe updates"),
-  title: z23.string().describe("Option name (e.g. Color, Size)"),
-  slug: z23.string().optional().describe(
+var optionSchema = z22.object({
+  id: z22.string().optional().describe("Stable existing option ID for rename-safe updates"),
+  title: z22.string().describe("Option name (e.g. Color, Size)"),
+  slug: z22.string().optional().describe(
     "Optional compatibility option token. The server generates one from title on create when omitted; not canonical identity."
   ),
-  values: z23.array(optionValueSchema).describe("Allowed option values")
+  values: z22.array(optionValueSchema).describe("Allowed option values")
 });
-var variantOptionValueSchema = z23.object({
-  valueSlug: z23.string().optional(),
-  valueId: z23.string().optional(),
-  value: z23.string().optional()
+var variantOptionValueSchema = z22.object({
+  valueSlug: z22.string().optional(),
+  valueId: z22.string().optional(),
+  value: z22.string().optional()
 });
-var variantSchema = z23.object({
-  id: z23.string().optional().describe("Existing variant ID for updates"),
-  optionValues: z23.union([
-    z23.record(z23.string(), z23.union([z23.string(), variantOptionValueSchema])),
-    z23.array(z23.string())
+var variantSchema = z22.object({
+  id: z22.string().optional().describe("Existing variant ID for updates"),
+  optionValues: z22.union([
+    z22.record(z22.string(), z22.union([z22.string(), variantOptionValueSchema])),
+    z22.array(z22.string())
   ]).optional().describe(
     "Option-value selection. Prefer stable option-value IDs, either as an array or object values using { valueId }. Slug maps and exact { OptionTitle: ValueLabel } maps remain compatibility-only and fail when labels are ambiguous."
   ),
-  sku: z23.string().nullable().optional(),
-  title: z23.string().nullable().optional(),
-  price: z23.number().nonnegative().describe("Selling price (KRW, min 0)"),
-  compareAtPrice: z23.number().nonnegative().nullable().optional(),
-  stock: z23.number().int().nonnegative().optional(),
-  isUnlimited: z23.boolean().optional(),
-  weight: z23.number().nonnegative().nullable().optional(),
-  requiresShipping: z23.boolean().optional(),
-  barcode: z23.string().nullable().optional(),
-  externalId: z23.string().nullable().optional(),
-  isActive: z23.boolean().optional(),
-  thumbnail: z23.string().nullable().optional(),
-  images: z23.array(z23.string()).optional(),
-  metadata: z23.unknown().optional()
+  sku: z22.string().nullable().optional(),
+  title: z22.string().nullable().optional(),
+  price: z22.number().nonnegative().describe("Selling price (KRW, min 0)"),
+  compareAtPrice: z22.number().nonnegative().nullable().optional(),
+  stock: z22.number().int().nonnegative().optional(),
+  isUnlimited: z22.boolean().optional(),
+  weight: z22.number().nonnegative().nullable().optional(),
+  requiresShipping: z22.boolean().optional(),
+  barcode: z22.string().nullable().optional(),
+  externalId: z22.string().nullable().optional(),
+  isActive: z22.boolean().optional(),
+  thumbnail: z22.string().nullable().optional(),
+  images: z22.array(z22.string()).optional(),
+  metadata: z22.unknown().optional()
 });
-var schema23 = {
-  product: z23.record(z23.string(), z23.unknown()).describe(
+var schema24 = {
+  product: z22.record(z22.string(), z22.unknown()).describe(
     "Product fields. Include `id` to update an existing product; omit for create (then `title` is required)."
   ),
-  options: z23.array(optionSchema).optional().describe(
+  options: z22.array(optionSchema).optional().describe(
     "Option definitions. Include stable option/value IDs when updating or renaming existing rows. Slugs are optional compatibility metadata generated from title/value on create when omitted; omitted options on an existing product are deleted (with their values)."
   ),
-  variants: z23.array(variantSchema).optional().describe(
+  variants: z22.array(variantSchema).optional().describe(
     "Variant rows. Prefer stable option-value IDs in optionValues. Slug/title maps are compatibility inputs. Omitted variants on an existing product are deleted, unless referenced by an active cart or non-terminal order \u2014 those are soft-deactivated (isActive: false)."
   )
 };
-var metadata23 = {
+var metadata24 = {
   name: "product-upsert",
   description: "Atomically create or update a product together with its options, option-values, and variants in a single transaction. Mirrors Shopify productSet semantics. Any failure rolls back the entire write.",
   annotations: {
@@ -2033,8 +2167,8 @@ async function getCollectionSchema(collection) {
 }
 
 // src/tools/get-collection-schema.ts
-var schema24 = createCollectionSchemaToolInputSchema(SERVER_COLLECTIONS3).shape;
-var metadata24 = {
+var schema25 = createCollectionSchemaToolInputSchema(SERVER_COLLECTIONS3).shape;
+var metadata25 = {
   name: "get-collection-schema",
   description: "Get the authoritative tenant-aware collection schema from console. Use this before create/update to understand writable fields, hidden fields, required metadata, and collection-level visibility.",
   annotations: {
@@ -2085,8 +2219,8 @@ async function getTenantFeatureProgress(feature, includeEvidence = false) {
 }
 
 // src/tools/get-tenant-context.ts
-var schema25 = tenantContextToolInputSchema.shape;
-var metadata25 = {
+var schema26 = tenantContextToolInputSchema.shape;
+var metadata26 = {
   name: "get-tenant-context",
   description: "Get current tenant features, active collections, and field visibility. Call this at the start of every session. Use includeCounts=true to also get per-collection document counts for setup diagnostics.",
   annotations: {
@@ -2163,8 +2297,8 @@ async function handler({
 }
 
 // src/tools/check-feature-progress.ts
-var schema26 = tenantFeatureProgressInputSchema.shape;
-var metadata26 = {
+var schema27 = tenantFeatureProgressInputSchema.shape;
+var metadata27 = {
   name: "check-feature-progress",
   description: "Check tenant implementation progress for a supported feature. Start with feature=ecommerce to inspect catalog, cart, checkout, payment result, webhook, and operations readiness without mutating tenant data.",
   annotations: {
@@ -2187,7 +2321,7 @@ async function handler2({
 }
 
 // src/tools/list-configurable-fields.ts
-import { z as z24 } from "zod";
+import { z as z23 } from "zod";
 
 // src/lib/field-config.ts
 async function fetchFieldConfigs() {
@@ -2210,12 +2344,12 @@ function invalidateFieldConfigCache() {
 }
 
 // src/tools/list-configurable-fields.ts
-var schema27 = {
-  collection: z24.string().optional().describe(
+var schema28 = {
+  collection: z23.string().optional().describe(
     "Filter by collection slug (optional \u2014 returns all if omitted). Use this filter to reduce response size when you know which collection to check."
   )
 };
-var metadata27 = {
+var metadata28 = {
   name: "list-configurable-fields",
   description: "List all configurable fields for tenant collections with current visibility state. Shows which fields can be shown/hidden and their current status. Returns all collections including inactive features \u2014 cross-reference with get-tenant-context for active features. Response includes ~300 fields across 47 collections \u2014 use collection filter when possible.",
   annotations: {
@@ -2246,17 +2380,17 @@ async function listConfigurableFields(params) {
 }
 
 // src/tools/update-field-config.ts
-import { z as z25 } from "zod";
-var schema28 = {
-  collection: z25.string().min(1).describe("Collection slug (required)"),
-  hiddenFields: z25.array(z25.string().min(1).max(200)).max(300).describe(
+import { z as z24 } from "zod";
+var schema29 = {
+  collection: z24.string().min(1).describe("Collection slug (required)"),
+  hiddenFields: z24.array(z24.string().min(1).max(200)).max(300).describe(
     "Fields to hide (required). This is a FULL REPLACE \u2014 fields NOT in this list will be shown. Pass [] to show all fields. Use list-configurable-fields first to see available field paths."
   ),
-  isHidden: z25.boolean().optional().describe(
+  isHidden: z24.boolean().optional().describe(
     "Hide the entire collection from Admin Panel (optional). When true, individual hiddenFields are irrelevant."
   )
 };
-var metadata28 = {
+var metadata29 = {
   name: "update-field-config",
   description: "Update field visibility configuration for a tenant collection. Hidden fields are removed from the Admin Panel UI. IMPORTANT: hiddenFields is a full replace, not a merge. Always call list-configurable-fields first to see current state.",
   annotations: {
@@ -2284,7 +2418,7 @@ async function updateFieldConfig(params) {
 }
 
 // src/tools/sdk-get-recipe.ts
-import { z as z26 } from "zod";
+import { z as z25 } from "zod";
 
 // src/lib/sdk-recipes.ts
 var recipes = {
@@ -2725,8 +2859,8 @@ function getRecipe(goal, runtime = "both") {
 }
 
 // src/tools/sdk-get-recipe.ts
-var schema29 = {
-  goal: z26.enum([
+var schema30 = {
+  goal: z25.enum([
     "fetch-list",
     "fetch-by-id",
     "create-item",
@@ -2738,11 +2872,11 @@ var schema29 = {
     "file-upload",
     "bulk-operations"
   ]).describe("What the user wants to accomplish"),
-  runtime: z26.enum(["browser", "server", "both"]).default("both").describe("Target runtime environment"),
-  collection: z26.string().optional().describe("Specific collection name if applicable"),
-  includeExample: z26.boolean().default(true).describe("Whether to include a full code example")
+  runtime: z25.enum(["browser", "server", "both"]).default("both").describe("Target runtime environment"),
+  collection: z25.string().optional().describe("Specific collection name if applicable"),
+  includeExample: z25.boolean().default(true).describe("Whether to include a full code example")
 };
-var metadata29 = {
+var metadata30 = {
   name: "sdk-get-recipe",
   description: "Get a complete SDK code recipe for a specific task. Returns recommended approach, code example, and related documentation links. Use this FIRST when the user asks how to do something with the SDK.",
   annotations: {
@@ -2785,7 +2919,7 @@ function handler3({
 }
 
 // src/tools/sdk-search-docs.ts
-import { z as z27 } from "zod";
+import { z as z26 } from "zod";
 
 // src/lib/sdk-doc-index.ts
 var docIndex = [
@@ -2913,8 +3047,19 @@ var docIndex = [
   // Webhooks
   {
     title: "Webhooks",
-    keywords: ["webhook", "hmac", "signature", "WEBHOOK_SECRET", "server-to-server", "event"],
-    summary: "Tenant webhooks deliver server-to-server events such as password reset tokens. Signed with HMAC-SHA256 using PAYLOAD_SECRET.",
+    keywords: [
+      "webhook",
+      "hmac",
+      "signature",
+      "WEBHOOK_SECRET",
+      "server-to-server",
+      "event",
+      "order",
+      "orderChanged",
+      "collection.orderChanged",
+      "isOrderChangedWebhookEvent"
+    ],
+    summary: "Tenant webhooks deliver signed server-to-server events via WEBHOOK_SECRET, including customer password reset and semantic order changes with collection.orderChanged / isOrderChangedWebhookEvent.",
     resourceUri: "docs://sdk/webhook"
   },
   // Order API
@@ -2960,11 +3105,11 @@ function searchDocs(query, limit = 5) {
 }
 
 // src/tools/sdk-search-docs.ts
-var schema30 = {
-  query: z27.string().min(2).describe('Search keyword or phrase (e.g. "infinite scroll", "webhook", "customer login")'),
-  limit: z27.number().min(1).max(10).default(5).describe("Maximum results to return (1-10, default: 5)")
+var schema31 = {
+  query: z26.string().min(2).describe('Search keyword or phrase (e.g. "infinite scroll", "webhook", "customer login")'),
+  limit: z26.number().min(1).max(10).default(5).describe("Maximum results to return (1-10, default: 5)")
 };
-var metadata30 = {
+var metadata31 = {
   name: "sdk-search-docs",
   description: "Search SDK documentation by keyword. Returns matching topics with summaries and resource links. Use when looking for specific SDK features or patterns.",
   annotations: {
@@ -2999,9 +3144,9 @@ function handler4({
 }
 
 // src/tools/sdk-get-auth-setup.ts
-import { z as z28 } from "zod";
-var schema31 = {
-  scenario: z28.enum([
+import { z as z27 } from "zod";
+var schema32 = {
+  scenario: z27.enum([
     "browser-client",
     "server-client",
     "customer-auth",
@@ -3010,7 +3155,7 @@ var schema31 = {
     "webhook-verification"
   ]).describe("Authentication scenario")
 };
-var metadata31 = {
+var metadata32 = {
   name: "sdk-get-auth-setup",
   description: "Get the current authentication setup for a specific scenario. Returns env var names, code snippets, and security notes.",
   annotations: {
@@ -3134,13 +3279,19 @@ export SOFTWARE_SECRET_KEY=sk01_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`,
     envVars: ["WEBHOOK_SECRET"],
     code: `import { handleWebhook, createCustomerAuthWebhookHandler } 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
+}
+
 const customerAuthHandler = createCustomerAuthWebhookHandler({
   passwordReset: sendPasswordResetEmail,
 })
 
 export async function POST(request: Request) {
   return handleWebhook(request, customerAuthHandler, {
-    secret: process.env.WEBHOOK_SECRET!,
+    secret: getWebhookSecret(),
   })
 }`,
     notes: [
@@ -3166,14 +3317,14 @@ function handler5({
 }
 
 // src/tools/sdk-get-collection-pattern.ts
-import { z as z29 } from "zod";
+import { z as z28 } from "zod";
 import { COLLECTIONS, SERVER_COLLECTIONS as SERVER_COLLECTIONS4 } from "@01.software/sdk";
-var schema32 = {
-  collection: z29.enum(SERVER_COLLECTIONS4).describe("Collection name"),
-  operation: z29.enum(["read", "write", "full-crud"]).default("read").describe("What operations are needed"),
-  surface: z29.enum(["query-builder", "react-query", "server-api"]).default("query-builder").describe("Preferred API surface")
+var schema33 = {
+  collection: z28.enum(SERVER_COLLECTIONS4).describe("Collection name"),
+  operation: z28.enum(["read", "write", "full-crud"]).default("read").describe("What operations are needed"),
+  surface: z28.enum(["query-builder", "react-query", "server-api"]).default("query-builder").describe("Preferred API surface")
 };
-var metadata32 = {
+var metadata33 = {
   name: "sdk-get-collection-pattern",
   description: "Get the recommended CRUD pattern for a specific collection. Returns code examples for the chosen API surface and operation type.",
   annotations: {
@@ -3369,14 +3520,14 @@ function handler6({
 }
 
 // src/prompts/sdk-usage-guide.ts
-import { z as z30 } from "zod";
-var schema33 = {
-  goal: z30.string().describe('What the user wants to accomplish (e.g., "query product list", "create order")'),
-  runtime: z30.enum(["browser", "server"]).optional().describe("Target runtime: browser (React/Next.js client) or server (Node.js)"),
-  surface: z30.enum(["query-builder", "react-query", "customer-api", "server-api"]).optional().describe("Preferred API surface"),
-  collection: z30.string().optional().describe("Specific collection if relevant")
+import { z as z29 } from "zod";
+var schema34 = {
+  goal: z29.string().describe('What the user wants to accomplish (e.g., "query product list", "create order")'),
+  runtime: z29.enum(["browser", "server"]).optional().describe("Target runtime: browser (React/Next.js client) or server (Node.js)"),
+  surface: z29.enum(["query-builder", "react-query", "customer-api", "server-api"]).optional().describe("Preferred API surface"),
+  collection: z29.string().optional().describe("Specific collection if relevant")
 };
-var metadata33 = {
+var metadata34 = {
   name: "sdk-usage-guide",
   title: "SDK Usage Guide",
   description: "Provides guidance on how to perform a specific task using the 01.software SDK",
@@ -3547,14 +3698,14 @@ const { allAvailable } = await client.commerce.product.stockCheck({
 }
 
 // src/prompts/collection-query-help.ts
-import { z as z31 } from "zod";
+import { z as z30 } from "zod";
 import { COLLECTIONS as COLLECTIONS2, SERVER_COLLECTIONS as SERVER_COLLECTIONS5 } from "@01.software/sdk";
-var schema34 = {
-  collection: z31.enum(SERVER_COLLECTIONS5).describe("Collection name"),
-  operation: z31.enum(["find", "create", "update", "delete"]).describe("Operation to perform (find, create, update, delete)"),
-  filters: z31.string().optional().describe("Filter conditions (JSON string, optional)")
+var schema35 = {
+  collection: z30.enum(SERVER_COLLECTIONS5).describe("Collection name"),
+  operation: z30.enum(["find", "create", "update", "delete"]).describe("Operation to perform (find, create, update, delete)"),
+  filters: z30.string().optional().describe("Filter conditions (JSON string, optional)")
 };
-var metadata34 = {
+var metadata35 = {
   name: "collection-query-help",
   title: "Collection Query Help",
   description: "Provides guidance on how to write queries for a specific collection",
@@ -3651,16 +3802,16 @@ ${operation === "find" ? `- Use \`where\` option for filtering (Payload query sy
 }
 
 // src/prompts/order-flow-guide.ts
-import { z as z32 } from "zod";
-var schema35 = {
-  scenario: z32.enum([
+import { z as z31 } from "zod";
+var schema36 = {
+  scenario: z31.enum([
     "simple-order",
     "cart-checkout",
     "return-refund",
     "fulfillment-tracking"
   ]).describe("Order flow scenario")
 };
-var metadata35 = {
+var metadata36 = {
   name: "order-flow-guide",
   title: "Order Flow Guide",
   description: "Provides step-by-step guidance for ecommerce order flows including creation, checkout, returns, and fulfillment.",
@@ -3675,9 +3826,10 @@ var SCENARIOS = {
    - Provide: orderNumber, customerSnapshot (email required), shippingAddress, orderItems, totalAmount
    - Optional: pgPaymentId (omit for free orders), shippingAmount, discountCode
 
-2. **Payment Confirmation** \u2192 \`update-transaction\` tool
-   - Confirm provider payment with pgPaymentId, paymentKey, and amount
-   - Stock is automatically adjusted (stock -= qty, reservedStock += qty)
+2. **Payment Confirmation** \u2192 ServerClient \`commerce.orders.confirmPayment()\`
+   - Confirm provider payment with pgPaymentId, provider name, and amount
+   - Successful confirmation transitions the order to \`paid\`
+   - Paid orders reserve sellable quantity (reservedStock += qty); physical stock is decremented on delivery
 
 3. **Fulfillment** \u2192 \`create-fulfillment\` tool
    - Provide carrier + trackingNumber for shipped status
@@ -3697,18 +3849,20 @@ const client = createServerClient({
 const order = await client.commerce.orders.create({
   orderNumber: 'ORD-240101-001',
   customerSnapshot: { email: 'user@example.com', name: 'John' },
-  shippingAddress: { postalCode: '06000', address1: '123 Main St' },
+  shippingAddress: { postalCode: '06000', address: '123 Main St' },
   orderItems: [{ product: 'prod-id', variant: 'var-id', option: 'opt-id', quantity: 2 }],
   totalAmount: 59800,
   pgPaymentId: 'pay_xxx' // omit for free orders
 })
 
 // 2. After payment confirmed by provider
-await client.commerce.orders.updateTransaction({
+await client.commerce.orders.confirmPayment({
+  orderNumber: 'ORD-240101-001',
   pgPaymentId: 'pay_xxx',
-  status: 'paid',
-  paymentKey: 'payment_key_xxx',
-  amount: 59800
+  pgProvider: 'provider',
+  amount: 59800,
+  paymentMethod: 'card',
+  confirmationSource: 'provider_api_confirm'
 })
 
 // 3. Ship items
@@ -3727,7 +3881,7 @@ await client.commerce.orders.createFulfillment({
 2. **Apply Discount** (optional) \u2192 \`apply-discount\` tool
 3. **Calculate Shipping** \u2192 \`calculate-shipping\` tool
 4. **Checkout** \u2192 \`checkout\` tool (converts cart to order)
-5. **Payment** \u2192 \`update-transaction\` for provider-verified paid transitions
+5. **Payment** \u2192 ServerClient \`commerce.orders.confirmPayment()\` for provider-verified paid transitions
 
 ### Key Points
 - Cart has a customer linked \u2014 auto-copied to order on checkout
@@ -3840,14 +3994,14 @@ ${SCENARIOS[scenario] || "Unknown scenario."}
 - \`checkout\`
 - \`create-fulfillment\`, \`update-fulfillment\`
 - \`create-return\`, \`update-return\`, \`return-with-refund\`
-- \`update-transaction\`
+- \`confirm-payment\`, \`update-transaction\`
 - \`validate-discount\`, \`calculate-shipping\``;
 }
 
 // src/prompts/feature-setup-guide.ts
-import { z as z33 } from "zod";
-var schema36 = {
-  feature: z33.enum([
+import { z as z32 } from "zod";
+var schema37 = {
+  feature: z32.enum([
     "ecommerce",
     "customers",
     "articles",
@@ -3862,7 +4016,7 @@ var schema36 = {
     "community"
   ]).describe("Feature to get setup guide for")
 };
-var metadata36 = {
+var metadata37 = {
   name: "feature-setup-guide",
   title: "Feature Setup Guide",
   description: "Setup checklist and remediation guide for a tenant feature. Load with check-feature-progress and get-tenant-context to diagnose setup gaps.",
@@ -4070,7 +4224,7 @@ ${FEATURES[feature] || "Unknown feature."}
 }
 
 // src/resources/(config)/app.ts
-var metadata37 = {
+var metadata38 = {
   name: "app-config",
   title: "Application Config",
   description: "01.software SDK and MCP server configuration information"
@@ -4114,7 +4268,7 @@ The hosted HTTP MCP endpoint at https://mcp.01.software/mcp exposes only these O
 - \`sdk-get-auth-setup\` - Get framework-specific auth setup guidance
 - \`sdk-get-collection-pattern\` - Get collection-specific usage patterns
 
-## Local CLI Stdio Surface (30)
+## Local CLI Stdio Surface (33)
 
 For trusted local server-key workflows, start the stdio server:
 
@@ -4122,7 +4276,7 @@ For trusted local server-key workflows, start the stdio server:
 npx @01.software/cli mcp
 \`\`\`
 
-Local stdio can expose generic read, order, return, cart, validation, stock, schema, tenant context, feature progress, field config, and guidance tools. Generic collection write tools (create/update/delete/update-many/delete-many) are intentionally absent on every transport; use the SDK server client for generic writes.
+Local stdio can expose generic read, order, payment confirmation, return, cart, validation, stock, schema, tenant context, feature progress, field config, and guidance tools. Generic collection write tools (create/update/delete/update-many/delete-many) are intentionally absent on every transport; use the SDK server client for generic writes.
 
 ## Rate Limits
 
@@ -4136,7 +4290,7 @@ Rate limits depend on your tenant plan:
 
 // src/resources/(collections)/schema.ts
 import { COLLECTIONS as COLLECTIONS3 } from "@01.software/sdk";
-var metadata38 = {
+var metadata39 = {
   name: "collections-schema",
   title: "Collection Schema Info",
   description: "Available collections and their schema information"
@@ -4273,7 +4427,7 @@ Total available collections: ${COLLECTIONS3.length}`;
 }
 
 // src/resources/(docs)/getting-started.ts
-var metadata39 = {
+var metadata40 = {
   name: "docs-getting-started",
   title: "Getting Started",
   description: "01.software SDK getting started guide"
@@ -4334,7 +4488,7 @@ const result = await client.collections.from('products').find({
 }
 
 // src/resources/(docs)/guides.ts
-var metadata40 = {
+var metadata41 = {
   name: "docs-guides",
   title: "Guides",
   description: "01.software SDK usage guides"
@@ -4547,7 +4701,7 @@ For more implementation guidance, see the [SDK Guide](/developers/sdk).`;
 }
 
 // src/resources/(docs)/api.ts
-var metadata41 = {
+var metadata42 = {
   name: "docs-api",
   title: "API Reference",
   description: "01.software SDK API reference documentation"
@@ -4830,7 +4984,7 @@ For more details, see the [API documentation](/developers/api).`;
 }
 
 // src/resources/(docs)/query-builder.ts
-var metadata42 = {
+var metadata43 = {
   name: "docs-query-builder",
   title: "Query Builder",
   description: "01.software SDK Query Builder API reference (client.collections.from)"
@@ -5024,7 +5178,7 @@ console.log(result.hasNextPage) // true
 }
 
 // src/resources/(docs)/react-query.ts
-var metadata43 = {
+var metadata44 = {
   name: "docs-react-query",
   title: "React Query Hooks",
   description: "01.software SDK React Query hooks reference (@01.software/sdk/query)"
@@ -5256,7 +5410,7 @@ export function ProductList() {
 }
 
 // src/resources/(docs)/server-api.ts
-var metadata44 = {
+var metadata45 = {
   name: "docs-server-api",
   title: "Server-side API",
   description: "01.software SDK server-side API reference (client.commerce) for orders, fulfillments, returns, carts, and validation"
@@ -5294,16 +5448,16 @@ const order = await client.commerce.orders.create({
     recipientName: 'John Doe',
     phone: '+821012345678',
     postalCode: '06234',
-    address1: '123 Main St',
-    address2: 'Apt 4B',
+    address: '123 Main St',
+    detailAddress: 'Apt 4B',
     deliveryMessage?: 'Leave at door',
   },
   orderItems: [
-    { product: 'product-id', variant: 'variant-id', option: 'option-id', quantity: 2, unitPrice: 29900 }
+    { product: 'product-id', variant: 'variant-id', option: 'option-id', quantity: 2 }
   ],
   totalAmount: 59800,
   shippingAmount?: 3000,
-  pgPaymentId?: 'toss-payment-id',  // omit for free orders
+  pgPaymentId?: 'provider-payment-id',  // omit for free orders
 })
 \`\`\`
 
@@ -5315,7 +5469,7 @@ const order = await client.commerce.orders.checkout({
   cartId: 'cart-id',
   orderNumber: 'ORD-20240101-0001',
   customerSnapshot: { name: 'John Doe', email: 'john@example.com' },
-  pgPaymentId?: 'toss-payment-id',
+  pgPaymentId?: 'provider-payment-id',
 })
 \`\`\`
 
@@ -5408,24 +5562,45 @@ const result = await client.commerce.orders.returnWithRefund({
     { orderItem: 'order-item-id', quantity: 1 }
   ],
   refundAmount: 29900,
-  pgPaymentId: 'toss-payment-id',  // required
-  paymentKey: 'toss-payment-key',  // required for provider refund
+  pgPaymentId: 'provider-payment-id',  // required
+  paymentKey: 'provider-payment-key',  // required for provider refund
   refundReceiptUrl?: 'https://...',
 })
 \`\`\`
 
 ## Transaction API
 
+### confirmPayment()
+Confirm a provider-verified payment and transition the order to paid. Verify the
+payment with the provider first, then call this endpoint with the provider name,
+amount, and an idempotency event ID when available.
+
+\`\`\`typescript
+const result = await client.commerce.orders.confirmPayment({
+  orderNumber: 'ORD-20240101-0001',
+  pgPaymentId: 'provider-payment-id',
+  pgProvider: 'provider-name',
+  amount: 29900,
+  currency: 'KRW',
+  paymentMethod: 'card',
+  providerStatus: 'PAID',
+  providerEventId: 'provider-event-id',
+  confirmationSource: 'provider_api_confirm',
+})
+\`\`\`
+
 ### updateTransaction()
-Confirm or annotate a transaction. Paid transitions require provider
-verification; non-financial annotations can still update pending transactions.
+Lower-level transaction update path. Prefer \`confirmPayment()\` for normal paid
+transitions. Use this only for compatibility paths that still require direct
+transaction annotation after provider verification, or for non-paid pending
+transaction updates.
 
 \`\`\`typescript
 const tx = await client.commerce.orders.updateTransaction({
-  pgPaymentId: 'toss-payment-id',
-  status: 'paid',  // pending | paid | failed | canceled
-  paymentKey: 'toss-payment-key',  // required when status is paid
-  amount: 29900,  // required when status is paid
+  pgPaymentId: 'provider-payment-id',
+  status: 'failed',  // pending | paid | failed | canceled
+  paymentMethod: 'card',
+  receiptUrl: 'https://...',
 })
 \`\`\`
 
@@ -5518,7 +5693,7 @@ const result = await client.commerce.shipping.calculate({
 }
 
 // src/resources/(docs)/customer-auth.ts
-var metadata45 = {
+var metadata46 = {
   name: "docs-customer-auth",
   title: "Customer Auth API",
   description: "01.software SDK Customer Auth API reference (client.customer)"
@@ -5696,7 +5871,7 @@ async function loadProfile() {
 }
 
 // src/resources/(docs)/browser-vs-server.ts
-var metadata46 = {
+var metadata47 = {
   name: "docs-browser-vs-server",
   title: "Client vs ServerClient",
   description: "When to use Client (createClient) vs ServerClient (createServerClient) in the 01.software SDK"
@@ -5862,7 +6037,7 @@ export function ProductList() {
 }
 
 // src/resources/(docs)/file-upload.ts
-var metadata47 = {
+var metadata48 = {
   name: "docs-file-upload",
   title: "File Upload",
   description: "01.software SDK file upload patterns using the images collection"
@@ -6013,7 +6188,7 @@ The platform stores files in Cloudflare R2 and serves via CDN (\`cdn.01.software
 }
 
 // src/resources/(docs)/webhook.ts
-var metadata48 = {
+var metadata49 = {
   name: "docs-webhook",
   title: "Webhooks",
   description: "01.software SDK webhook verification and event handling"
@@ -6030,6 +6205,12 @@ Use the SDK \`handleWebhook\` helper to verify signatures. For customer auth eve
 \`\`\`typescript
 import { handleWebhook, createCustomerAuthWebhookHandler } 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
+}
+
 const handler = createCustomerAuthWebhookHandler({
   passwordReset: async (data) => {
     await sendPasswordResetEmail(data)
@@ -6038,7 +6219,7 @@ const handler = createCustomerAuthWebhookHandler({
 
 export async function POST(request: Request) {
   return handleWebhook(request, handler, {
-    secret: process.env.WEBHOOK_SECRET!,
+    secret: getWebhookSecret(),
   })
 }
 \`\`\`
@@ -6051,6 +6232,12 @@ export async function POST(request: Request) {
 // app/api/webhooks/route.ts
 import { handleWebhook, createCustomerAuthWebhookHandler } 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
+}
+
 const customerAuthHandler = createCustomerAuthWebhookHandler({
   passwordReset: sendPasswordResetEmail,
 })
@@ -6061,7 +6248,7 @@ export async function POST(request: Request) {
 
     await customerAuthHandler(event)
   }, {
-    secret: process.env.WEBHOOK_SECRET!,
+    secret: getWebhookSecret(),
   })
 }
 \`\`\`
@@ -6080,6 +6267,51 @@ All webhook events share this envelope:
 
 ## Event Types
 
+### 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\`.
+- 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.
+
+\`\`\`typescript
+import { handleWebhook, isOrderChangedWebhookEvent } 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 (isOrderChangedWebhookEvent(event)) {
+        if (event.change.scope.kind === 'join') {
+          console.log('Join order changed', {
+            collection: event.change.scope.collection,
+            field: event.change.scope.field,
+            parentId: event.change.scope.id,
+            movedCollection: event.change.moved.collection,
+            movedId: event.change.moved.id,
+          })
+        }
+        return
+      }
+
+      console.log('Content changed', event.collection, event.operation)
+    },
+    { secret: getWebhookSecret() },
+  )
+}
+\`\`\`
+
 ### Customer Password Reset
 
 Dispatched when a customer calls \`client.customer.forgotPassword(email)\`.
@@ -6127,7 +6359,7 @@ Configure webhook URLs in the 01.software console under Tenant Settings > Webhoo
 }
 
 // src/resources/(docs)/product-detail.ts
-var metadata49 = {
+var metadata50 = {
   name: "docs-product-detail",
   title: "Product Detail Helper",
   description: "01.software SDK commerce.product.detail helper guide"
@@ -6219,7 +6451,23 @@ Log \`client.lastRequestId\` against backend logs \u2014 the endpoint records th
 
 // src/server.ts
 var REGISTERED_TOOLS_BY_SERVER = /* @__PURE__ */ new WeakMap();
-function registerTool(server, schema37, meta, handler21) {
+function hasToolPolicy(toolName) {
+  return Object.prototype.hasOwnProperty.call(TOOL_POLICY_MANIFEST, toolName);
+}
+function runtimeAnnotationsFor(meta) {
+  if (!hasToolPolicy(meta.name)) {
+    throw new Error(`No tool-policy entry for registered MCP tool ${meta.name}`);
+  }
+  const policy = TOOL_POLICY_MANIFEST[meta.name];
+  return {
+    title: meta.annotations?.title,
+    readOnlyHint: policy.annotationPolicy.readOnly,
+    destructiveHint: policy.annotationPolicy.destructive,
+    idempotentHint: policy.annotationPolicy.idempotent,
+    openWorldHint: policy.annotationPolicy.openWorld
+  };
+}
+function registerTool(server, schema38, meta, handler21) {
   let registered = REGISTERED_TOOLS_BY_SERVER.get(server);
   if (!registered) {
     registered = /* @__PURE__ */ new Set();
@@ -6230,16 +6478,20 @@ function registerTool(server, schema37, meta, handler21) {
     meta.name,
     {
       description: meta.description,
-      inputSchema: schema37,
-      annotations: meta.annotations
+      inputSchema: schema38,
+      annotations: runtimeAnnotationsFor(meta)
     },
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async (params) => {
       const ctx = tenantAuthContext();
       if (ctx) {
-        const decision = evaluateToolPolicy(meta.name, ctx.scopes);
+        const decision = evaluateToolPolicy(
+          meta.name,
+          ctx.scopes,
+          ctx.tenantRole
+        );
         if (!decision.allowed) {
-          const status = decision.reason === "insufficient_scope" ? 403 : 500;
+          const status = decision.reason === "insufficient_scope" || decision.reason === "insufficient_role" ? 403 : 500;
           return {
             content: [
               {
@@ -6276,13 +6528,13 @@ function registerTool(server, schema37, meta, handler21) {
     }
   );
 }
-function registerPrompt(server, schema37, meta, handler21) {
+function registerPrompt(server, schema38, meta, handler21) {
   server.registerPrompt(
     meta.name,
     {
       title: meta.title,
       description: meta.description,
-      argsSchema: schema37
+      argsSchema: schema38
     },
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (params) => ({
@@ -6354,211 +6606,232 @@ function createServer(options = {}) {
       server,
       schema10,
       metadata10,
-      createReturn
+      confirmPayment
     );
     registerTool(
       server,
       schema11,
       metadata11,
-      updateReturn
+      createReturn
     );
     registerTool(
       server,
       schema12,
       metadata12,
-      returnWithRefund
+      updateReturn
     );
-    registerTool(server, schema13, metadata13, addCartItem);
     registerTool(
       server,
-      schema14,
-      metadata14,
-      updateCartItem
+      schema13,
+      metadata13,
+      returnWithRefund
     );
+    registerTool(server, schema14, metadata14, addCartItem);
     registerTool(
       server,
       schema15,
       metadata15,
-      removeCartItem
+      updateCartItem
     );
     registerTool(
       server,
       schema16,
       metadata16,
-      applyDiscount
+      removeCartItem
     );
     registerTool(
       server,
       schema17,
       metadata17,
-      removeDiscount
+      applyDiscount
     );
-    registerTool(server, schema18, metadata18, clearCart);
     registerTool(
       server,
-      schema19,
-      metadata19,
-      validateDiscount
+      schema18,
+      metadata18,
+      removeDiscount
     );
+    registerTool(server, schema19, metadata19, clearCart);
     registerTool(
       server,
       schema20,
       metadata20,
+      validateDiscount
+    );
+    registerTool(
+      server,
+      schema21,
+      metadata21,
       calculateShipping
     );
-    registerTool(server, schema21, metadata21, stockCheck);
-    registerTool(server, schema22, metadata22, productDetail);
+    registerTool(server, schema22, metadata22, stockCheck);
     registerTool(
       server,
       schema23,
       metadata23,
+      productDetail
+    );
+    registerTool(
+      server,
+      schema24,
+      metadata24,
       productUpsert
     );
   }
-  registerTool(
-    server,
-    schema24,
-    metadata24,
-    getCollectionSchemaTool
-  );
   registerTool(
     server,
     schema25,
     metadata25,
-    handler
+    getCollectionSchemaTool
   );
   registerTool(
     server,
     schema26,
     metadata26,
-    handler2
+    handler
   );
   registerTool(
     server,
     schema27,
     metadata27,
-    listConfigurableFields
+    handler2
   );
   registerTool(
     server,
     schema28,
     metadata28,
-    updateFieldConfig
+    listConfigurableFields
   );
   registerTool(
     server,
     schema29,
     metadata29,
-    handler3
+    updateFieldConfig
   );
   registerTool(
     server,
     schema30,
     metadata30,
-    handler4
+    handler3
   );
   registerTool(
     server,
     schema31,
     metadata31,
-    handler5
+    handler4
   );
   registerTool(
     server,
     schema32,
     metadata32,
-    handler6
+    handler5
   );
-  registerPrompt(
+  registerTool(
     server,
     schema33,
     metadata33,
-    sdkUsageGuide
+    handler6
   );
   registerPrompt(
     server,
     schema34,
     metadata34,
-    collectionQueryHelp
+    sdkUsageGuide
   );
   registerPrompt(
     server,
     schema35,
     metadata35,
-    orderFlowGuide
+    collectionQueryHelp
   );
   registerPrompt(
     server,
     schema36,
     metadata36,
+    orderFlowGuide
+  );
+  registerPrompt(
+    server,
+    schema37,
+    metadata37,
     featureSetupGuide
   );
   registerStaticResource(
     server,
-    "config://app",
-    metadata37,
+    mcpResourceUri("app-config"),
+    metadata38,
     handler7
   );
   registerStaticResource(
     server,
-    "collections://schema",
-    metadata38,
+    mcpResourceUri("collections-schema"),
+    metadata39,
     handler8
   );
   registerStaticResource(
     server,
-    "docs://sdk/getting-started",
-    metadata39,
+    mcpResourceUri("docs-getting-started"),
+    metadata40,
     handler9
   );
-  registerStaticResource(server, "docs://sdk/guides", metadata40, handler10);
-  registerStaticResource(server, "docs://sdk/api", metadata41, handler11);
   registerStaticResource(
     server,
-    "docs://sdk/query-builder",
+    mcpResourceUri("docs-guides"),
+    metadata41,
+    handler10
+  );
+  registerStaticResource(
+    server,
+    mcpResourceUri("docs-api"),
     metadata42,
-    handler12
+    handler11
   );
   registerStaticResource(
     server,
-    "docs://sdk/react-query",
+    mcpResourceUri("docs-query-builder"),
     metadata43,
-    handler13
+    handler12
   );
   registerStaticResource(
     server,
-    "docs://sdk/server-api",
+    mcpResourceUri("docs-react-query"),
     metadata44,
-    handler14
+    handler13
   );
   registerStaticResource(
     server,
-    "docs://sdk/customer-auth",
+    mcpResourceUri("docs-server-api"),
     metadata45,
-    handler15
+    handler14
   );
   registerStaticResource(
     server,
-    "docs://sdk/browser-vs-server",
+    mcpResourceUri("docs-customer-auth"),
     metadata46,
-    handler16
+    handler15
   );
   registerStaticResource(
     server,
-    "docs://sdk/file-upload",
+    mcpResourceUri("docs-browser-vs-server"),
     metadata47,
-    handler17
+    handler16
   );
   registerStaticResource(
     server,
-    "docs://sdk/webhook",
+    mcpResourceUri("docs-file-upload"),
     metadata48,
-    handler18
+    handler17
   );
   registerStaticResource(
     server,
-    "docs://sdk/product-detail",
+    mcpResourceUri("docs-webhook"),
     metadata49,
+    handler18
+  );
+  registerStaticResource(
+    server,
+    mcpResourceUri("docs-product-detail"),
+    metadata50,
     handler19
   );
   return server;
@@ -6861,7 +7134,7 @@ schema, context, field-config, and guidance tools:
   npx @01.software/cli mcp
 
 Prompts (4): sdk-usage-guide, collection-query-help, order-flow-guide, feature-setup-guide
-Resources (12): config, collections-schema, getting-started, guides, api, query-builder, react-query, server-api, customer-auth, browser-vs-server, file-upload, webhook
+Resources (${MCP_RESOURCE_LABELS.length}): ${MCP_RESOURCE_LABELS.join(", ")}
 
 
 Links