@01.software/cli 0.12.0 → 0.13.0

package/dist/index.js

@@ -808,79 +808,511 @@ function registerCrudCommands(program2, getClient2, getFormat2) {
   });
 }
 
-// src/commands/order.ts
+// ../contracts/src/tenant/index.ts
 import { z } from "zod";
-var idSchema = z.union([z.string().min(1), z.number()]).transform(String);
-var customerSnapshotSchema = z.object({
-  email: z.string().email("Invalid email format"),
-  name: z.string().optional(),
-  phone: z.string().optional()
+var tenantFieldConfigStateSchema = z.object({
+  hiddenFields: z.array(z.string()),
+  isHidden: z.boolean()
+}).strict();
+var tenantContextQuerySchema = z.object({
+  counts: z.literal("true").optional()
+}).strict();
+var tenantContextToolInputSchema = z.object({
+  includeCounts: z.boolean().optional().default(false).describe(
+    "Include per-collection document counts and config status (bypasses cache, slower)"
+  )
+}).strict();
+var tenantContextResponseSchema = z.object({
+  tenant: z.object({
+    id: z.string(),
+    name: z.string(),
+    plan: z.string(),
+    planSource: z.string().optional(),
+    authoritative: z.boolean().optional(),
+    capabilityVersion: z.string().optional()
+  }).strict(),
+  features: z.array(z.string()),
+  collections: z.object({
+    active: z.array(z.string()),
+    inactive: z.array(z.string())
+  }).strict(),
+  fieldConfigs: z.record(z.string(), tenantFieldConfigStateSchema),
+  counts: z.record(z.string(), z.number()).optional(),
+  config: z.object({
+    webhookConfigured: z.boolean()
+  }).strict().optional()
+}).strict();
+var tenantFeatureProgressFeatureSchema = z.enum(["ecommerce"]);
+var tenantFeatureProgressInputSchema = z.object({
+  feature: tenantFeatureProgressFeatureSchema.describe(
+    "Feature to inspect for tenant implementation readiness"
+  ),
+  includeEvidence: z.boolean().optional().default(false).describe("Include sanitized counts and static surface evidence")
+}).strict();
+var tenantFeatureProgressStatusSchema = z.enum([
+  "ready",
+  "attention",
+  "blocked"
+]);
+var tenantFeatureProgressItemStateSchema = z.enum([
+  "complete",
+  "incomplete",
+  "blocked",
+  "attention",
+  "optional",
+  "unknown",
+  "manual",
+  "not-applicable"
+]);
+var tenantFeatureProgressSeveritySchema = z.enum([
+  "required",
+  "recommended",
+  "optional"
+]);
+var tenantFeatureProgressEvidenceValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null()
+]);
+var tenantFeatureProgressItemSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  state: tenantFeatureProgressItemStateSchema,
+  severity: tenantFeatureProgressSeveritySchema,
+  summary: z.string(),
+  evidence: z.record(z.string(), tenantFeatureProgressEvidenceValueSchema).optional()
+}).strict();
+var tenantFeatureProgressGroupSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  summary: z.string().optional(),
+  items: z.array(tenantFeatureProgressItemSchema)
+}).strict();
+var tenantFeatureProgressResponseSchema = z.object({
+  schemaVersion: z.literal(1),
+  feature: tenantFeatureProgressFeatureSchema,
+  status: tenantFeatureProgressStatusSchema,
+  generatedAt: z.string(),
+  tenant: z.object({
+    id: z.string(),
+    name: z.string(),
+    plan: z.string()
+  }).strict(),
+  capability: z.object({
+    effectiveFeatures: z.array(z.string()),
+    planBlocked: z.array(z.string()),
+    closureAdded: z.array(z.string())
+  }).strict(),
+  summary: z.object({
+    complete: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    blocking: z.number().int().nonnegative(),
+    manual: z.number().int().nonnegative(),
+    unknown: z.number().int().nonnegative()
+  }).strict(),
+  groups: z.array(tenantFeatureProgressGroupSchema)
+}).strict();
+var COLLECTION_SCHEMA_CONTRACT_VERSION = 1;
+var collectionSchemaEndpointParamsSchema = z.object({
+  collectionSlug: z.string().min(1, "collectionSlug is required")
 }).strict();
-var shippingAddressSchema = z.object({
-  postalCode: z.string().optional(),
-  address: z.string().optional(),
-  detailAddress: z.string().optional(),
-  deliveryMessage: z.string().optional(),
-  recipientName: z.string().optional(),
-  phone: z.string().optional()
+var collectionFieldOptionSchema = z.object({
+  label: z.string(),
+  value: z.string()
 }).strict();
-var orderItemSchema = z.object({
-  product: idSchema,
-  variant: idSchema,
-  option: idSchema,
-  quantity: z.number().int().positive("quantity must be a positive integer"),
-  unitPrice: z.number().optional(),
-  totalPrice: z.number().optional()
+var collectionFieldSchema = z.lazy(
+  () => z.object({
+    name: z.string(),
+    path: z.string(),
+    type: z.string(),
+    required: z.literal(true).optional(),
+    unique: z.literal(true).optional(),
+    hasMany: z.literal(true).optional(),
+    relationTo: z.union([z.string(), z.array(z.string())]).optional(),
+    options: z.array(collectionFieldOptionSchema).optional(),
+    hidden: z.literal(true).optional(),
+    systemManaged: z.literal(true).optional(),
+    writable: z.boolean().optional(),
+    fields: z.array(collectionFieldSchema).optional()
+  }).strict()
+);
+var collectionSchemaResponseSchema = z.object({
+  contractVersion: z.literal(COLLECTION_SCHEMA_CONTRACT_VERSION),
+  mode: z.literal("effective"),
+  collection: z.object({
+    slug: z.string(),
+    timestamps: z.boolean(),
+    alwaysActive: z.boolean(),
+    feature: z.string().nullable(),
+    systemFields: z.array(z.string()),
+    visibility: z.object({
+      collectionHidden: z.boolean(),
+      hiddenFields: z.array(z.string())
+    }).strict(),
+    fields: z.array(collectionFieldSchema)
+  }).strict()
 }).strict();
-var orderItemsSchema = z.array(orderItemSchema).min(1, "At least one order item is required").max(100, "Maximum 100 items per order");
-var orderStatusSchema = z.enum([
+
+// ../contracts/src/ecommerce/index.ts
+import { z as z2 } from "zod";
+var transactionStatusSchema = z2.enum([
+  "pending",
+  "paid",
+  "failed",
+  "canceled"
+]);
+var financialStatusSchema = z2.enum([
+  "pending",
+  "paid",
+  "failed",
+  "canceled",
+  "partially_refunded",
+  "refunded"
+]);
+var confirmationStatusSchema = z2.enum(["unconfirmed", "confirmed"]);
+var fulfillmentOrderStatusSchema = z2.enum([
+  "open",
+  "in_progress",
+  "on_hold",
+  "canceled",
+  "closed"
+]);
+var shipmentStatusSchema = z2.enum([
+  "pending",
+  "shipped",
+  "delivered",
+  "canceled",
+  "failed"
+]);
+var orderStatusSchema = z2.enum([
   "pending",
   "paid",
   "failed",
   "canceled",
+  "refunded",
+  "preparing",
+  "shipped",
+  "delivered",
+  "confirmed",
+  "return_requested",
+  "return_processing",
+  "returned"
+]);
+var entityIdSchema = z2.union([z2.string().min(1), 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()
+}).strict();
+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()
+  }).strict(),
+  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()
+  }).strict(),
+  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()
+}).strict();
+var updateTransactionSchema = z2.object({
+  pgPaymentId: z2.string().min(1, "pgPaymentId is required").describe("PG payment ID (required)"),
+  status: transactionStatusSchema.describe(
+    "New transaction status (required)"
+  ),
+  paymentMethod: z2.string().optional().describe("Payment method (optional)"),
+  receiptUrl: z2.string().optional().describe("Receipt URL (optional)"),
+  paymentKey: z2.string().min(1).optional().describe("Provider payment key for verified paid confirmation"),
+  amount: z2.number().int().positive().optional().describe("Provider-confirmed amount for verified paid confirmation")
+}).strict();
+var providerSlugSchema = z2.string().trim().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/, "pgProvider must be lowercase slug");
+var confirmPaymentSchema = z2.object({
+  orderNumber: z2.string().min(1).optional(),
+  pgPaymentId: z2.string().min(1, "pgPaymentId is required").describe("Provider payment identifier stored on the transaction"),
+  pgProvider: providerSlugSchema.describe(
+    "Payment provider slug, e.g. toss, portone, stripe"
+  ),
+  pgOrderId: z2.string().min(1).optional(),
+  amount: z2.number().int().nonnegative("amount must be non-negative").describe("Provider-confirmed amount in minor units"),
+  currency: z2.string().min(1).optional(),
+  paymentMethod: z2.string().optional(),
+  receiptUrl: z2.string().url().optional(),
+  approvedAt: z2.string().optional(),
+  providerStatus: z2.string().optional(),
+  providerEventId: z2.string().min(1).optional(),
+  confirmationSource: z2.enum([
+    "provider_webhook",
+    "provider_lookup",
+    "provider_api_confirm",
+    "manual_server"
+  ]).optional(),
+  paymentKey: z2.string().min(1).optional().describe(
+    "Optional provider payment key from the client confirm handshake; stored for BFF/provider refund workflows (also accepted as metadata.tossPaymentKey). Local cancel does not read this field."
+  ),
+  metadata: z2.record(z2.string(), z2.unknown()).optional()
+}).strict();
+var returnReasonSchema = z2.enum([
+  "change_of_mind",
+  "defective",
+  "wrong_delivery",
+  "damaged",
+  "other"
+]);
+var restockActionSchema = z2.enum(["return_to_stock", "discard"]);
+var returnWithRefundItemSchema = z2.object({
+  orderItem: z2.union([z2.string().min(1), z2.number()]).transform(String),
+  quantity: z2.number().int().positive("quantity must be a positive integer"),
+  restockAction: restockActionSchema.default("return_to_stock"),
+  restockingFee: z2.number().min(0, "restockingFee must be non-negative").optional().describe("Restocking fee charged for this line (ADR 0005 \xA7Gap 1)")
+}).strict();
+var returnWithRefundSchema = z2.object({
+  orderNumber: z2.string().min(1, "orderNumber is required").describe("Order number (required)"),
+  reason: returnReasonSchema.optional().describe("Return reason (optional)"),
+  reasonDetail: z2.string().optional().describe("Detailed reason text (optional)"),
+  returnItems: z2.array(returnWithRefundItemSchema).min(1, "At least one return item is required").max(100, "Too many return items").describe("Array of products to return (required)"),
+  refundAmount: z2.number().min(0, "refundAmount must be non-negative").describe("Refund amount (required, min 0)"),
+  returnShippingFee: z2.number().min(0, "returnShippingFee must be non-negative").optional().describe(
+    "Return shipping fee charged to the customer (ADR 0005 \xA7Gap 1)"
+  ),
+  initialShippingRefundAmount: z2.number().min(0, "initialShippingRefundAmount must be non-negative").optional().describe("Initial order shipping amount refunded to the customer"),
+  initialShippingRefundOverrideNote: z2.string().min(1).optional().describe(
+    "Operator audit note required when overriding policy suggestion"
+  ),
+  pgPaymentId: z2.string().min(1, "pgPaymentId is required").describe("PG payment ID for refund (required)"),
+  paymentKey: z2.string().min(1).optional().describe("Provider payment key for verified refund"),
+  refundReceiptUrl: z2.string().optional().describe("Refund receipt URL (optional)")
+}).strict();
+var createReturnSchema = z2.object({
+  orderNumber: z2.string().min(1, "orderNumber is required").describe("Order number (required)"),
+  reason: returnReasonSchema.optional().describe("Return reason (optional)"),
+  reasonDetail: z2.string().optional().describe("Detailed reason text (optional)"),
+  returnItems: z2.array(returnWithRefundItemSchema).min(1, "At least one return item is required").max(100, "Too many return items").describe("Array of products to return (required)"),
+  refundAmount: z2.number().min(0, "refundAmount must be non-negative").describe(
+    "Line refund amount before initial shipping refund (required, min 0)"
+  ),
+  returnShippingFee: z2.number().min(0, "returnShippingFee must be non-negative").optional().describe("Return shipping fee charged to the customer"),
+  initialShippingRefundAmount: z2.number().min(0, "initialShippingRefundAmount must be non-negative").optional().describe("Initial order shipping amount refunded to the customer"),
+  initialShippingRefundOverrideNote: z2.string().min(1).optional().describe(
+    "Operator audit note required when overriding policy suggestion"
+  )
+}).strict();
+var cancelReasonCodeSchema = z2.enum([
+  "customer",
+  "inventory",
+  "fraud",
+  "declined",
+  "staff",
+  "other"
+]);
+var idempotencyKeySchema = z2.string().trim().min(1, "idempotencyKey is required").max(255, "idempotencyKey must be 255 characters or fewer").regex(
+  /^[\x21-\x7E]+$/,
+  "idempotencyKey must contain only printable header-safe characters"
+);
+var cancelOrderSchema = z2.object({
+  orderNumber: z2.string().min(1, "orderNumber is required").describe("Order number to cancel"),
+  reasonCode: cancelReasonCodeSchema.default("other").describe("Operator-selected cancel reason code"),
+  reasonDetail: z2.string().trim().max(2e3, "reasonDetail must be 2000 characters or fewer").optional().describe("Internal cancellation detail stored on the order")
+}).strict();
+var cancelOrderResponseBaseSchema = {
+  orderId: z2.string().min(1)
+};
+var unpaidLocalCancelCommittedResponseFields = {
+  refundedAmount: z2.literal(0),
+  providerRefunded: z2.literal(false)
+};
+var paidLocalCancelCommittedResponseFields = {
+  transactionId: z2.string().min(1),
+  refundedAmount: z2.literal(0),
+  providerRefunded: z2.literal(false),
+  refundPending: z2.literal(true)
+};
+var legacyProviderRefundResponseFields = {
+  transactionId: z2.string().min(1),
+  refundedAmount: z2.number().int().positive(),
+  refundSeq: z2.number().int().positive(),
+  providerRefunded: z2.literal(true)
+};
+var alreadyCanceledResponseFields = {
+  refundedAmount: z2.number().int().nonnegative(),
+  providerRefunded: z2.literal(false)
+};
+var alreadyCanceledRefundPendingResponseFields = {
+  transactionId: z2.string().min(1),
+  refundedAmount: z2.number().int().nonnegative(),
+  providerRefunded: z2.literal(false),
+  refundPending: z2.literal(true)
+};
+var cancelOrderReconciliationStatusSchema = z2.enum([
+  "paid",
   "preparing",
   "shipped",
   "delivered",
-  "confirmed"
+  "confirmed",
+  "return_requested",
+  "return_processing",
+  "returned",
+  "refunded"
+]);
+var cancelOrderResponseSchema = z2.union([
+  z2.object({
+    ...cancelOrderResponseBaseSchema,
+    ...paidLocalCancelCommittedResponseFields,
+    status: z2.literal("canceled"),
+    cancelCommitted: z2.literal(true)
+  }).strict(),
+  z2.object({
+    ...cancelOrderResponseBaseSchema,
+    ...unpaidLocalCancelCommittedResponseFields,
+    status: z2.literal("canceled"),
+    cancelCommitted: z2.literal(true)
+  }).strict(),
+  z2.object({
+    ...cancelOrderResponseBaseSchema,
+    ...alreadyCanceledResponseFields,
+    status: z2.literal("canceled"),
+    cancelCommitted: z2.literal(false),
+    alreadyCanceled: z2.literal(true)
+  }).strict(),
+  z2.object({
+    ...cancelOrderResponseBaseSchema,
+    ...alreadyCanceledRefundPendingResponseFields,
+    status: z2.literal("canceled"),
+    cancelCommitted: z2.literal(false),
+    alreadyCanceled: z2.literal(true)
+  }).strict(),
+  z2.object({
+    ...cancelOrderResponseBaseSchema,
+    ...legacyProviderRefundResponseFields,
+    status: cancelOrderReconciliationStatusSchema,
+    cancelCommitted: z2.literal(false),
+    reconciliationRequired: z2.literal(true)
+  }).strict()
+]);
+var resolveCancelRefundOutcomeSchema = z2.enum(["succeeded", "failed"]);
+var resolveCancelRefundSchema = z2.object({
+  orderNumber: z2.string().min(1, "orderNumber is required").describe("Order number whose pending cancel refund is being resolved"),
+  idempotencyKey: idempotencyKeySchema.describe(
+    "Stable key for this PG refund result report"
+  ),
+  outcome: resolveCancelRefundOutcomeSchema.describe(
+    "PG refund result reported by the storefront or BFF"
+  ),
+  refundedAmount: z2.number().int("refundedAmount must be an integer minor-unit amount").nonnegative("refundedAmount must be nonnegative"),
+  pgProvider: z2.string().trim().min(1, "pgProvider is required").regex(
+    /^[a-z0-9][a-z0-9_-]*$/,
+    "pgProvider must be a lowercase provider slug"
+  ),
+  pgRefundId: z2.string().trim().min(1).optional()
+}).strict().superRefine((value, ctx) => {
+  if (value.outcome === "succeeded" && value.refundedAmount <= 0) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      path: ["refundedAmount"],
+      message: "refundedAmount must be positive when outcome is succeeded"
+    });
+  }
+  if (value.outcome === "succeeded" && !value.pgRefundId) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      path: ["pgRefundId"],
+      message: "pgRefundId is required when outcome is succeeded"
+    });
+  }
+  if (value.outcome === "failed" && value.refundedAmount !== 0) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      path: ["refundedAmount"],
+      message: "refundedAmount must be 0 when outcome is failed"
+    });
+  }
+});
+var resolveCancelRefundResponseSchema = z2.union([
+  z2.object({
+    orderId: z2.string().min(1),
+    transactionId: z2.string().min(1),
+    refundTransactionId: z2.string().min(1),
+    refundedAmount: z2.number().int().positive(),
+    refundStatus: z2.literal("succeeded"),
+    transactionStatus: z2.literal("refunded")
+  }).strict(),
+  z2.object({
+    orderId: z2.string().min(1),
+    transactionId: z2.string().min(1),
+    refundTransactionId: z2.string().min(1),
+    refundedAmount: z2.literal(0),
+    refundStatus: z2.literal("failed"),
+    transactionStatus: z2.literal("paid")
+  }).strict()
 ]);
-var fulfillmentItemsSchema = z.array(
-  z.object({
+
+// src/commands/order.ts
+import { z as z3 } from "zod";
+var idSchema = z3.union([z3.string().min(1), z3.number()]).transform(String);
+var customerSnapshotSchema = z3.object({
+  email: z3.string().email("Invalid email format"),
+  name: z3.string().optional(),
+  phone: z3.string().optional()
+}).strict();
+var orderStatusSchema2 = z3.enum(["confirmed"]);
+var fulfillmentStatusSchema = z3.enum(["shipped", "delivered", "failed"]);
+var updateFulfillmentSchema = z3.object({
+  fulfillmentId: idSchema,
+  status: fulfillmentStatusSchema.optional(),
+  carrier: z3.string().min(1).optional(),
+  trackingNumber: z3.string().min(1).optional()
+}).refine(
+  (value) => value.status !== void 0 || value.carrier !== void 0 || value.trackingNumber !== void 0,
+  {
+    message: "status, carrier, or trackingNumber is required"
+  }
+);
+var fulfillmentItemsSchema = z3.array(
+  z3.object({
     orderItem: idSchema,
-    quantity: z.number().int().positive("quantity must be a positive integer")
+    quantity: z3.number().int().positive("quantity must be a positive integer")
   }).strict()
 ).min(1, "At least one fulfillment item is required").max(100, "Maximum 100 items per fulfillment");
 function registerOrderCommands(program2, getClient2, getFormat2) {
   const order = program2.command("order").description("Order management");
-  order.command("create").description("Create a new order").option("--payment-id <id>", "Payment ID").requiredOption("--order-number <num>", "Order number").requiredOption("--email <email>", "Customer email").option("--customer <id>", "Customer ID").option("--name <name>", "Customer name").option("--phone <phone>", "Customer phone").requiredOption("--shipping-address <json>", "Shipping address (JSON)").requiredOption("--products <json>", "Order products array (JSON)").requiredOption("--total-amount <n>", "Total amount", parseFloat).option("--dry-run", "Validate inputs without executing").action(async (opts) => {
+  order.command("create").description("Create a new order").option("--payment-id <id>", "Payment ID").requiredOption("--order-number <num>", "Order number").requiredOption("--email <email>", "Customer email").option("--customer <id>", "Customer ID").option("--name <name>", "Customer name").option("--phone <phone>", "Customer phone").requiredOption("--shipping-address <json>", "Shipping address (JSON)").requiredOption("--products <json>", "Order products array (JSON)").requiredOption("--total-amount <n>", "Total amount", parseFloat).option("--shipping-amount <n>", "Shipping amount", parseFloat).option("--discount-code <code>", "Discount code").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
-      const shippingAddress = parseWithSchema(
-        parseJson(opts.shippingAddress, "shipping-address"),
-        "shipping-address",
-        shippingAddressSchema
-      );
-      const orderItems = parseWithSchema(
-        parseJsonArray(opts.products, "products"),
-        "products",
-        orderItemsSchema
-      );
-      const totalAmount = parseWithSchema(
-        opts.totalAmount,
-        "total-amount",
-        z.number().nonnegative("totalAmount must be non-negative")
-      );
-      const data = {
-        pgPaymentId: opts.paymentId,
-        orderNumber: opts.orderNumber,
-        customerSnapshot: {
-          email: opts.email,
-          name: opts.name,
-          phone: opts.phone
+      const data = parseWithSchema(
+        {
+          pgPaymentId: opts.paymentId,
+          orderNumber: opts.orderNumber,
+          customerSnapshot: {
+            email: opts.email,
+            name: opts.name,
+            phone: opts.phone
+          },
+          customer: opts.customer,
+          shippingAddress: parseJson(
+            opts.shippingAddress,
+            "shipping-address"
+          ),
+          orderItems: parseJsonArray(opts.products, "products"),
+          totalAmount: opts.totalAmount,
+          shippingAmount: opts.shippingAmount,
+          discountCode: opts.discountCode
         },
-        customer: opts.customer,
-        shippingAddress,
-        orderItems,
-        totalAmount
-      };
+        "order",
+        createOrderSchema
+      );
       if (opts.dryRun) {
         printResult(
           { dryRun: true, valid: true, action: "order create", data },
@@ -889,10 +1321,7 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
         return;
       }
       const client = getClient2();
-      const result = await client.commerce.orders.create({
-        ...data,
-        orderItems
-      });
+      const result = await client.commerce.orders.create(data);
       printResult(result, getFormat2());
     } catch (e) {
       exitWithError(e);
@@ -901,16 +1330,22 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
   order.command("get <orderNumber>").description("Get an order by order number").action(async (orderNumber) => {
     try {
       const client = getClient2();
-      const { docs: [order2] } = await client.collections.from("orders").find({ where: { orderNumber: { equals: orderNumber } }, limit: 1, depth: 1 });
+      const {
+        docs: [order2]
+      } = await client.collections.from("orders").find({
+        where: { orderNumber: { equals: orderNumber } },
+        limit: 1,
+        depth: 1
+      });
       if (!order2) throw new Error("Order not found");
       printResult(order2, getFormat2());
     } catch (e) {
       exitWithError(e);
     }
   });
-  order.command("update <orderNumber>").description("Update order status").requiredOption("--status <status>", "New status").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
+  order.command("update <orderNumber>").description("Confirm a delivered order purchase").requiredOption("--status <status>", "New status (confirmed only)").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
     try {
-      const status = parseWithSchema(opts.status, "status", orderStatusSchema);
+      const status = parseWithSchema(opts.status, "status", orderStatusSchema2);
       const data = { orderNumber, status };
       if (opts.dryRun) {
         printResult(
@@ -956,18 +1391,35 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
       exitWithError(e);
     }
   });
-  order.command("fulfill <orderNumber>").description("Create a fulfillment for an order").requiredOption("--items <json>", "Fulfillment items array (JSON)").option("--carrier <name>", "Shipping carrier").option("--tracking-number <num>", "Tracking number").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
+  order.command("prepare <orderNumber>").description("Move paid order fulfillment work to preparation").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
+    try {
+      const data = { orderNumber };
+      if (opts.dryRun) {
+        printResult(
+          { dryRun: true, valid: true, action: "order prepare", data },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
+      const result = await client.commerce.orders.prepareFulfillmentOrder(data);
+      printResult(result, getFormat2());
+    } catch (e) {
+      exitWithError(e);
+    }
+  });
+  order.command("fulfill <orderNumber>").description("Create a shipment for a prepared order").option("--items <json>", "Fulfillment items array (JSON)").option("--carrier <name>", "Shipping carrier").option("--tracking-number <num>", "Tracking number").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
     try {
-      const items = parseWithSchema(
+      const items = opts.items ? parseWithSchema(
         parseJsonArray(opts.items, "items"),
         "items",
         fulfillmentItemsSchema
-      );
+      ) : void 0;
       const data = {
         orderNumber,
-        items,
-        carrier: opts.carrier,
-        trackingNumber: opts.trackingNumber
+        ...opts.carrier ? { carrier: opts.carrier } : {},
+        ...opts.trackingNumber ? { trackingNumber: opts.trackingNumber } : {},
+        ...items ? { items } : {}
       };
       if (opts.dryRun) {
         printResult(
@@ -979,62 +1431,88 @@ function registerOrderCommands(program2, getClient2, getFormat2) {
       const client = getClient2();
       const result = await client.commerce.orders.createFulfillment({
         ...data,
-        items
+        ...items ? {
+          items
+        } : {}
       });
       printResult(result, getFormat2());
     } catch (e) {
       exitWithError(e);
     }
   });
+  order.command("update-fulfillment <fulfillmentId>").description("Update shipment status or tracking information").option("--status <status>", "Shipment status (shipped, delivered, failed)").option("--carrier <name>", "Shipping carrier").option("--tracking-number <num>", "Tracking number").option("--dry-run", "Validate inputs without executing").action(async (fulfillmentId, opts) => {
+    try {
+      const data = parseWithSchema(
+        {
+          fulfillmentId,
+          ...opts.status ? { status: opts.status } : {},
+          ...opts.carrier ? { carrier: opts.carrier } : {},
+          ...opts.trackingNumber ? { trackingNumber: opts.trackingNumber } : {}
+        },
+        "fulfillment",
+        updateFulfillmentSchema
+      );
+      if (opts.dryRun) {
+        printResult(
+          {
+            dryRun: true,
+            valid: true,
+            action: "order update-fulfillment",
+            data
+          },
+          getFormat2()
+        );
+        return;
+      }
+      const client = getClient2();
+      const result = await client.commerce.orders.updateFulfillment(data);
+      printResult(result, getFormat2());
+    } catch (e) {
+      exitWithError(e);
+    }
+  });
 }
 
 // src/commands/return.ts
-import { z as z2 } from "zod";
-var idSchema2 = z2.union([z2.string().min(1), z2.number()]).transform(String);
-var returnReasonSchema = z2.enum(["change_of_mind", "defective", "wrong_delivery", "damaged", "other"]).optional();
-var returnItemsSchema = z2.array(
-  z2.object({
-    orderItem: idSchema2,
-    quantity: z2.number().int().positive("quantity must be a positive integer"),
-    restockAction: z2.enum(["return_to_stock", "discard"]).default("return_to_stock")
-  }).strict()
-).min(1, "At least one return item is required").max(100, "Too many return items");
-var returnStatusSchema = z2.enum([
+import { z as z4 } from "zod";
+var returnStatusSchema = z4.enum([
   "processing",
   "approved",
   "rejected",
   "completed"
 ]);
-var refundAmountSchema = z2.number().nonnegative("refundAmount must be non-negative");
 function registerReturnCommands(program2, getClient2, getFormat2) {
   const ret = program2.command("return").description("Return management");
   ret.command("create <orderNumber>").description("Create a return request").requiredOption("--products <json>", "Return products array (JSON)").requiredOption("--refund-amount <n>", "Refund amount", parseFloat).option(
+    "--return-shipping-fee <n>",
+    "Return shipping fee charged to the customer",
+    parseFloat
+  ).option(
+    "--initial-shipping-refund-amount <n>",
+    "Initial order shipping refund amount",
+    parseFloat
+  ).option(
+    "--initial-shipping-refund-note <text>",
+    "Audit note for manual initial shipping refund override"
+  ).option(
     "--reason <reason>",
     "Return reason (change_of_mind, defective, wrong_delivery, damaged, other)"
   ).option("--reason-detail <text>", "Detailed reason").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
     try {
-      const returnItems = parseWithSchema(
-        parseJsonArray(opts.products, "products"),
-        "products",
-        returnItemsSchema
-      );
-      const refundAmount = parseWithSchema(
-        opts.refundAmount,
-        "refund-amount",
-        refundAmountSchema
-      );
-      const reason = parseWithSchema(
-        opts.reason,
-        "reason",
-        returnReasonSchema
+      const data = parseWithSchema(
+        {
+          orderNumber,
+          returnItems: parseJsonArray(opts.products, "products"),
+          refundAmount: opts.refundAmount,
+          returnShippingFee: opts.returnShippingFee,
+          reason: opts.reason,
+          reasonDetail: opts.reasonDetail,
+          initialShippingRefundAmount: opts.initialShippingRefundAmount,
+          initialShippingRefundOverrideNote: opts.initialShippingRefundNote
+        },
+        "return",
+        createReturnSchema
       );
-      const data = {
-        orderNumber,
-        returnItems,
-        refundAmount,
-        reason,
-        reasonDetail: opts.reasonDetail
-      };
       if (opts.dryRun) {
         printResult(
           { dryRun: true, valid: true, action: "return create", data },
@@ -1045,7 +1523,7 @@ function registerReturnCommands(program2, getClient2, getFormat2) {
       const client = getClient2();
       const result = await client.commerce.orders.createReturn({
         ...data,
-        returnItems
+        returnItems: data.returnItems
       });
       printResult(result, getFormat2());
     } catch (e) {
@@ -1057,7 +1535,11 @@ function registerReturnCommands(program2, getClient2, getFormat2) {
     "New status (processing, approved, rejected, completed)"
   ).option("--dry-run", "Validate inputs without executing").action(async (returnId, opts) => {
     try {
-      const status = parseWithSchema(opts.status, "status", returnStatusSchema);
+      const status = parseWithSchema(
+        opts.status,
+        "status",
+        returnStatusSchema
+      );
       const data = { returnId, status };
       if (opts.dryRun) {
         printResult(
@@ -1073,32 +1555,36 @@ function registerReturnCommands(program2, getClient2, getFormat2) {
       exitWithError(e);
     }
   });
-  ret.command("refund <orderNumber>").description("Return with refund").requiredOption("--products <json>", "Return products array (JSON)").requiredOption("--refund-amount <n>", "Refund amount", parseFloat).requiredOption("--payment-id <id>", "Payment ID").option("--reason <reason>", "Return reason").option("--reason-detail <text>", "Detailed reason").option("--refund-receipt-url <url>", "Refund receipt URL").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
+  ret.command("refund <orderNumber>").description("Return with refund").requiredOption("--products <json>", "Return products array (JSON)").requiredOption("--refund-amount <n>", "Refund amount", parseFloat).requiredOption("--payment-id <id>", "Payment ID").option(
+    "--return-shipping-fee <n>",
+    "Return shipping fee charged to the customer",
+    parseFloat
+  ).option(
+    "--initial-shipping-refund-amount <n>",
+    "Initial order shipping refund amount",
+    parseFloat
+  ).option(
+    "--initial-shipping-refund-note <text>",
+    "Audit note for manual initial shipping refund override"
+  ).option("--reason <reason>", "Return reason").option("--reason-detail <text>", "Detailed reason").option("--refund-receipt-url <url>", "Refund receipt URL").option("--payment-key <key>", "Provider payment key").option("--dry-run", "Validate inputs without executing").action(async (orderNumber, opts) => {
     try {
-      const returnItems = parseWithSchema(
-        parseJsonArray(opts.products, "products"),
-        "products",
-        returnItemsSchema
-      );
-      const refundAmount = parseWithSchema(
-        opts.refundAmount,
-        "refund-amount",
-        refundAmountSchema
-      );
-      const reason = parseWithSchema(
-        opts.reason,
-        "reason",
-        returnReasonSchema
+      const data = parseWithSchema(
+        {
+          orderNumber,
+          returnItems: parseJsonArray(opts.products, "products"),
+          refundAmount: opts.refundAmount,
+          returnShippingFee: opts.returnShippingFee,
+          pgPaymentId: opts.paymentId,
+          reason: opts.reason,
+          reasonDetail: opts.reasonDetail,
+          refundReceiptUrl: opts.refundReceiptUrl,
+          paymentKey: opts.paymentKey,
+          initialShippingRefundAmount: opts.initialShippingRefundAmount,
+          initialShippingRefundOverrideNote: opts.initialShippingRefundNote
+        },
+        "return",
+        returnWithRefundSchema
       );
-      const data = {
-        orderNumber,
-        returnItems,
-        refundAmount,
-        pgPaymentId: opts.paymentId,
-        reason,
-        reasonDetail: opts.reasonDetail,
-        refundReceiptUrl: opts.refundReceiptUrl
-      };
       if (opts.dryRun) {
         printResult(
           { dryRun: true, valid: true, action: "return refund", data },
@@ -1109,7 +1595,7 @@ function registerReturnCommands(program2, getClient2, getFormat2) {
       const client = getClient2();
       const result = await client.commerce.orders.returnWithRefund({
         ...data,
-        returnItems
+        returnItems: data.returnItems
       });
       printResult(result, getFormat2());
     } catch (e) {
@@ -1211,19 +1697,33 @@ function registerStockCommands(program2, getClient2, getFormat2) {
 }
 
 // src/commands/transaction.ts
+import { z as z5 } from "zod";
+var transactionAmountSchema = z5.object({
+  amount: z5.string().regex(/^[1-9]\d*$/, "amount must be a positive integer").transform(Number)
+});
+function parseTransactionAmount(value) {
+  if (value === void 0) return void 0;
+  return parseWithSchema({ amount: value }, "amount", transactionAmountSchema).amount;
+}
 function registerTransactionCommands(program2, getClient2, getFormat2) {
   const tx = program2.command("transaction").description("Transaction management");
   tx.command("update").description("Update transaction status").requiredOption("--payment-id <id>", "Payment ID").requiredOption(
     "--status <status>",
     "New status (pending, paid, failed, canceled)"
-  ).requiredOption("--payment-method <method>", "Payment method").requiredOption("--receipt-url <url>", "Receipt URL").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
+  ).option("--payment-method <method>", "Payment method").option("--receipt-url <url>", "Receipt URL").option("--payment-key <key>", "Provider payment key").option("--amount <n>", "Provider-confirmed amount").option("--dry-run", "Validate inputs without executing").action(async (opts) => {
     try {
-      const data = {
-        pgPaymentId: opts.paymentId,
-        status: opts.status,
-        paymentMethod: opts.paymentMethod,
-        receiptUrl: opts.receiptUrl
-      };
+      const data = parseWithSchema(
+        {
+          pgPaymentId: opts.paymentId,
+          status: opts.status,
+          paymentMethod: opts.paymentMethod,
+          receiptUrl: opts.receiptUrl,
+          paymentKey: opts.paymentKey,
+          amount: parseTransactionAmount(opts.amount)
+        },
+        "transaction",
+        updateTransactionSchema
+      );
       if (opts.dryRun) {
         printResult(
           { dryRun: true, valid: true, action: "transaction update", data },
@@ -1572,152 +2072,6 @@ function registerSchemaCommands(program2, getClient2, getFormat2) {
   });
 }
 
-// ../contracts/src/tenant/index.ts
-import { z as z3 } from "zod";
-var tenantFieldConfigStateSchema = z3.object({
-  hiddenFields: z3.array(z3.string()),
-  isHidden: z3.boolean()
-}).strict();
-var tenantContextQuerySchema = z3.object({
-  counts: z3.literal("true").optional()
-}).strict();
-var tenantContextToolInputSchema = z3.object({
-  includeCounts: z3.boolean().optional().default(false).describe(
-    "Include per-collection document counts and config status (bypasses cache, slower)"
-  )
-}).strict();
-var tenantContextResponseSchema = z3.object({
-  tenant: z3.object({
-    id: z3.string(),
-    name: z3.string(),
-    plan: z3.string(),
-    planSource: z3.string().optional(),
-    authoritative: z3.boolean().optional(),
-    capabilityVersion: z3.string().optional()
-  }).strict(),
-  features: z3.array(z3.string()),
-  collections: z3.object({
-    active: z3.array(z3.string()),
-    inactive: z3.array(z3.string())
-  }).strict(),
-  fieldConfigs: z3.record(z3.string(), tenantFieldConfigStateSchema),
-  counts: z3.record(z3.string(), z3.number()).optional(),
-  config: z3.object({
-    webhookConfigured: z3.boolean()
-  }).strict().optional()
-}).strict();
-var tenantFeatureProgressFeatureSchema = z3.enum(["ecommerce"]);
-var tenantFeatureProgressInputSchema = z3.object({
-  feature: tenantFeatureProgressFeatureSchema.describe(
-    "Feature to inspect for tenant implementation readiness"
-  ),
-  includeEvidence: z3.boolean().optional().default(false).describe("Include sanitized counts and static surface evidence")
-}).strict();
-var tenantFeatureProgressStatusSchema = z3.enum([
-  "ready",
-  "attention",
-  "blocked"
-]);
-var tenantFeatureProgressItemStateSchema = z3.enum([
-  "complete",
-  "incomplete",
-  "blocked",
-  "attention",
-  "optional",
-  "unknown",
-  "manual",
-  "not-applicable"
-]);
-var tenantFeatureProgressSeveritySchema = z3.enum([
-  "required",
-  "recommended",
-  "optional"
-]);
-var tenantFeatureProgressEvidenceValueSchema = z3.union([
-  z3.string(),
-  z3.number(),
-  z3.boolean(),
-  z3.null()
-]);
-var tenantFeatureProgressItemSchema = z3.object({
-  id: z3.string(),
-  title: z3.string(),
-  state: tenantFeatureProgressItemStateSchema,
-  severity: tenantFeatureProgressSeveritySchema,
-  summary: z3.string(),
-  evidence: z3.record(z3.string(), tenantFeatureProgressEvidenceValueSchema).optional()
-}).strict();
-var tenantFeatureProgressGroupSchema = z3.object({
-  id: z3.string(),
-  title: z3.string(),
-  summary: z3.string().optional(),
-  items: z3.array(tenantFeatureProgressItemSchema)
-}).strict();
-var tenantFeatureProgressResponseSchema = z3.object({
-  schemaVersion: z3.literal(1),
-  feature: tenantFeatureProgressFeatureSchema,
-  status: tenantFeatureProgressStatusSchema,
-  generatedAt: z3.string(),
-  tenant: z3.object({
-    id: z3.string(),
-    name: z3.string(),
-    plan: z3.string()
-  }).strict(),
-  capability: z3.object({
-    effectiveFeatures: z3.array(z3.string()),
-    planBlocked: z3.array(z3.string()),
-    closureAdded: z3.array(z3.string())
-  }).strict(),
-  summary: z3.object({
-    complete: z3.number().int().nonnegative(),
-    total: z3.number().int().nonnegative(),
-    blocking: z3.number().int().nonnegative(),
-    manual: z3.number().int().nonnegative(),
-    unknown: z3.number().int().nonnegative()
-  }).strict(),
-  groups: z3.array(tenantFeatureProgressGroupSchema)
-}).strict();
-var COLLECTION_SCHEMA_CONTRACT_VERSION = 1;
-var collectionSchemaEndpointParamsSchema = z3.object({
-  collectionSlug: z3.string().min(1, "collectionSlug is required")
-}).strict();
-var collectionFieldOptionSchema = z3.object({
-  label: z3.string(),
-  value: z3.string()
-}).strict();
-var collectionFieldSchema = z3.lazy(
-  () => z3.object({
-    name: z3.string(),
-    path: z3.string(),
-    type: z3.string(),
-    required: z3.literal(true).optional(),
-    unique: z3.literal(true).optional(),
-    hasMany: z3.literal(true).optional(),
-    relationTo: z3.union([z3.string(), z3.array(z3.string())]).optional(),
-    options: z3.array(collectionFieldOptionSchema).optional(),
-    hidden: z3.literal(true).optional(),
-    systemManaged: z3.literal(true).optional(),
-    writable: z3.boolean().optional(),
-    fields: z3.array(collectionFieldSchema).optional()
-  }).strict()
-);
-var collectionSchemaResponseSchema = z3.object({
-  contractVersion: z3.literal(COLLECTION_SCHEMA_CONTRACT_VERSION),
-  mode: z3.literal("effective"),
-  collection: z3.object({
-    slug: z3.string(),
-    timestamps: z3.boolean(),
-    alwaysActive: z3.boolean(),
-    feature: z3.string().nullable(),
-    systemFields: z3.array(z3.string()),
-    visibility: z3.object({
-      collectionHidden: z3.boolean(),
-      hiddenFields: z3.array(z3.string())
-    }).strict(),
-    fields: z3.array(collectionFieldSchema)
-  }).strict()
-}).strict();
-
 // src/commands/feature.ts
 function flattenProgress(progress) {
   return progress.groups.flatMap(