@01.software/cli 0.11.2 → 0.12.0

package/dist/mcp/.01-cli-mcp-build.json

@@ -1,7 +1,7 @@
 {
   "kind": "01software.cli.mcp-build",
   "version": 1,
-  "sourceHash": "92d74716ea364000ddfe10dcf45eeb85aec32d0831897c1c689ffff455f7e943",
+  "sourceHash": "3565c7d38e25024c7bc2cd007944aed179cd476ee55553f188ada1ff0918f0ea",
   "sourceInputs": [
     "apps/mcp/package.json",
     "apps/mcp/tsconfig.json",

package/dist/mcp/{chunk-D72PPBDH.js → chunk-CBN6MUZE.js}

@@ -333,7 +333,6 @@ var productFieldShape = {
   weight: z2.number().int().min(0).optional().nullable(),
   minOrderQuantity: z2.number().int().min(1).optional().nullable(),
   maxOrderQuantity: z2.number().int().min(1).optional().nullable(),
-  listingPrimaryOption: IdSchema.optional().nullable(),
   isFeatured: z2.boolean().optional(),
   publishedAt: z2.string().optional().nullable(),
   categories: z2.array(IdSchema).optional(),
@@ -536,6 +535,9 @@ var confirmPaymentSchema = z3.object({
     "provider_api_confirm",
     "manual_server"
   ]).optional(),
+  paymentKey: z3.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: z3.record(z3.string(), z3.unknown()).optional()
 }).strict();
 var ConfirmPaymentSchema = confirmPaymentSchema;
@@ -588,20 +590,32 @@ var CancelOrderSchema = cancelOrderSchema;
 var cancelOrderResponseBaseSchema = {
   orderId: z3.string().min(1)
 };
-var unpaidCancelResponseFields = {
+var unpaidLocalCancelCommittedResponseFields = {
   refundedAmount: z3.literal(0),
   providerRefunded: z3.literal(false)
 };
-var alreadyCanceledResponseFields = {
-  refundedAmount: z3.number().int().nonnegative(),
-  providerRefunded: z3.literal(false)
+var paidLocalCancelCommittedResponseFields = {
+  transactionId: z3.string().min(1),
+  refundedAmount: z3.literal(0),
+  providerRefunded: z3.literal(false),
+  refundPending: z3.literal(true)
 };
-var providerRefundResponseFields = {
+var legacyProviderRefundResponseFields = {
   transactionId: z3.string().min(1),
   refundedAmount: z3.number().int().positive(),
   refundSeq: z3.number().int().positive(),
   providerRefunded: z3.literal(true)
 };
+var alreadyCanceledResponseFields = {
+  refundedAmount: z3.number().int().nonnegative(),
+  providerRefunded: z3.literal(false)
+};
+var alreadyCanceledRefundPendingResponseFields = {
+  transactionId: z3.string().min(1),
+  refundedAmount: z3.number().int().nonnegative(),
+  providerRefunded: z3.literal(false),
+  refundPending: z3.literal(true)
+};
 var cancelOrderReconciliationStatusSchema = z3.enum([
   "paid",
   "preparing",
@@ -616,13 +630,13 @@ var cancelOrderReconciliationStatusSchema = z3.enum([
 var cancelOrderResponseSchema = z3.union([
   z3.object({
     ...cancelOrderResponseBaseSchema,
-    ...unpaidCancelResponseFields,
+    ...paidLocalCancelCommittedResponseFields,
     status: z3.literal("canceled"),
     cancelCommitted: z3.literal(true)
   }).strict(),
   z3.object({
     ...cancelOrderResponseBaseSchema,
-    ...providerRefundResponseFields,
+    ...unpaidLocalCancelCommittedResponseFields,
     status: z3.literal("canceled"),
     cancelCommitted: z3.literal(true)
   }).strict(),
@@ -635,12 +649,75 @@ var cancelOrderResponseSchema = z3.union([
   }).strict(),
   z3.object({
     ...cancelOrderResponseBaseSchema,
-    ...providerRefundResponseFields,
+    ...alreadyCanceledRefundPendingResponseFields,
+    status: z3.literal("canceled"),
+    cancelCommitted: z3.literal(false),
+    alreadyCanceled: z3.literal(true)
+  }).strict(),
+  z3.object({
+    ...cancelOrderResponseBaseSchema,
+    ...legacyProviderRefundResponseFields,
     status: cancelOrderReconciliationStatusSchema,
     cancelCommitted: z3.literal(false),
     reconciliationRequired: z3.literal(true)
   }).strict()
 ]);
+var resolveCancelRefundOutcomeSchema = z3.enum(["succeeded", "failed"]);
+var resolveCancelRefundSchema = z3.object({
+  orderNumber: z3.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: z3.number().int("refundedAmount must be an integer minor-unit amount").nonnegative("refundedAmount must be nonnegative"),
+  pgProvider: z3.string().trim().min(1, "pgProvider is required").regex(
+    /^[a-z0-9][a-z0-9_-]*$/,
+    "pgProvider must be a lowercase provider slug"
+  ),
+  pgRefundId: z3.string().trim().min(1).optional()
+}).strict().superRefine((value, ctx) => {
+  if (value.outcome === "succeeded" && value.refundedAmount <= 0) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      path: ["refundedAmount"],
+      message: "refundedAmount must be positive when outcome is succeeded"
+    });
+  }
+  if (value.outcome === "succeeded" && !value.pgRefundId) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      path: ["pgRefundId"],
+      message: "pgRefundId is required when outcome is succeeded"
+    });
+  }
+  if (value.outcome === "failed" && value.refundedAmount !== 0) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      path: ["refundedAmount"],
+      message: "refundedAmount must be 0 when outcome is failed"
+    });
+  }
+});
+var resolveCancelRefundResponseSchema = z3.union([
+  z3.object({
+    orderId: z3.string().min(1),
+    transactionId: z3.string().min(1),
+    refundTransactionId: z3.string().min(1),
+    refundedAmount: z3.number().int().positive(),
+    refundStatus: z3.literal("succeeded"),
+    transactionStatus: z3.literal("refunded")
+  }).strict(),
+  z3.object({
+    orderId: z3.string().min(1),
+    transactionId: z3.string().min(1),
+    refundTransactionId: z3.string().min(1),
+    refundedAmount: z3.literal(0),
+    refundStatus: z3.literal("failed"),
+    transactionStatus: z3.literal("paid")
+  }).strict()
+]);
 
 // ../../packages/contracts/src/mcp/index.ts
 var MCP_TOOL_CONTRACT = {
@@ -4166,7 +4243,7 @@ const order = await client.commerce.orders.checkout({
    - Requires pgPaymentId and paymentKey for provider-verified refund
 
 ### Key Points
-- Full refund: original transaction \u2192 \`canceled\`
+- Full refund: original transaction \u2192 \`canceled\` (**return-with-refund only**; order-cancel does NOT cancel the transaction \u2014 it stays \`paid\` until the storefront PG refund resolves it)
 - Partial refund: new refund transaction created
 - Stock restored: stock += qty, reservedStock -= qty
 - Cumulative refunds tracked: refundAmount + order.refundedAmount \u2264 totalAmount
@@ -4185,23 +4262,24 @@ await client.commerce.orders.returnWithRefund({
   paymentKey: 'payment_key_xxx'
 })
 \`\`\``,
-  "order-cancel": `## Provider-Verified Order Cancellation
+  "order-cancel": `## Local Order Cancellation (PG refund separate)
 
 ### Flow
 
 1. **Cancel Order** -> \`cancel-order\` tool
-   - Pending or failed unpaid orders cancel without a provider call
-   - Paid captured orders use the server-stored provider payment key from the captured transaction
-   - Paid captured orders are refunded through the provider-verified path before local status changes
-   - Successful paid cancellation releases reservedStock and moves the order to \`canceled\`
-   - Duplicate local success returns \`alreadyCanceled: true\`; do not issue a second refund
-   - Provider-refunded local blockers return \`reconciliationRequired: true\` on retry
+   - Pending or failed unpaid orders cancel locally without a PG call
+   - Paid captured orders cancel **locally only**: order \`canceled\`, payment transaction stays \`paid\`, reservedStock released
+   - **PG refund is not performed by Console** \u2014 storefront/BFF calls Toss/Portone; webhook sync is a follow-up
+   - \`refundedAmount\` is not incremented on local cancel; new cancels return \`providerRefunded: false\`
+   - \`refundPending: true\` signals storefront PG refund is still required; idempotent retries may return it from server metadata
+   - Legacy inline-PG-cancel rows may still return \`reconciliationRequired: true\` with \`providerRefunded: true\`
+   - Duplicate local success returns \`alreadyCanceled: true\`
 
 ### V1 Rejections
 - Orders with non-failed fulfillments are rejected
 - \`shipped\`, \`delivered\`, \`confirmed\`, and return-axis orders are rejected
 - Active returns are rejected; use \`return-with-refund\` after delivery
-- Partial line-item cancellation and no-refund paid cancellation are not supported in v1
+- Partial line-item cancellation is not supported in v1
 
 ### Code Example
 \`\`\`typescript
@@ -4213,7 +4291,36 @@ await client.commerce.orders.cancelOrder({
 })
 \`\`\`
 
-If \`reconciliationRequired\` is true, stop provider retries and hand off to an operator to reconcile fulfillment, stock, and accounting manually.`,
+### Storefront PG refund (BFF only)
+
+After \`cancelOrder\`, initiate PG refund **only when all of the following hold**:
+
+- First response: \`cancelCommitted: true\` **and** \`refundPending: true\`
+- Idempotent retry: \`alreadyCanceled: true\` **and** \`refundPending: true\` (read from server metadata)
+- PG lookup confirms the payment is still captured / not yet refunded
+
+**Never** call PG refund when:
+
+- \`providerRefunded: true\` (legacy inline-PG-cancel or refund already recorded)
+- \`reconciliationRequired: true\` (escalate to ops \u2014 do not auto-refund)
+- \`refundPending\` is absent on an unpaid / never-captured order
+
+Prefer persisting the first \`cancelOrder\` response; use PG \`getPayment\` before refund when state is uncertain.
+
+After a PG refund attempt reaches a terminal result, report that exact result back to Console. This is a BFF/server-only operation and requires an \`sk01_\` server API key.
+
+\`\`\`typescript
+await client.commerce.orders.resolveCancelRefund({
+  orderNumber: 'ORD-240101-001',
+  idempotencyKey: 'refund-cancel-ORD-240101-001-attempt-1',
+  outcome: 'succeeded',
+  refundedAmount: 59800,
+  pgProvider: 'toss',
+  pgRefundId: 'toss-refund-abc'
+})
+\`\`\`
+
+Use one idempotency key per distinct PG refund attempt/result. For PG refund failure, call \`resolveCancelRefund({ outcome: 'failed', refundedAmount: 0, ... })\` with that attempt key. If a later PG attempt succeeds after a reported failure, use a new key such as \`refund-cancel-ORD-240101-001-attempt-2\`. Reuse the exact same \`idempotencyKey\` only for transport retries of the same reported result; never reuse it for a different order, outcome, provider, amount, or provider refund id.`,
   "fulfillment-tracking": `## Fulfillment & Tracking
 
 ### Creating Fulfillment
@@ -7224,4 +7331,4 @@ export {
   flushMcpTelemetrySummary,
   createServer
 };
-//# sourceMappingURL=chunk-D72PPBDH.js.map
+//# sourceMappingURL=chunk-CBN6MUZE.js.map