@yoryoboy/bi-mcp 1.10.0 → 1.13.0

package/dist/tests/vtex/vtex-order-details.tool.test.js

@@ -0,0 +1,141 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getOrderDocumentsBatch } from "../../src/services/vtex/vtex-orders.js";
+import { formatVtexError } from "../../src/services/vtex/vtex-api.js";
+import { orderDetailsHandler } from "../../src/tools/vtex/order-details.js";
+import { resolveVtexProfileOrSelection } from "../../src/tools/vtex/profile-resolution.js";
+import { formatOrderDetails } from "../../src/utils/format-order-details.js";
+vi.mock("mcp-use/server", () => ({
+  object: vi.fn((payload) => ({ kind: "object", payload })),
+  error: vi.fn((message) => ({ kind: "error", message }))
+}));
+vi.mock("../../src/tools/vtex/profile-resolution.js", () => ({
+  resolveVtexProfileOrSelection: vi.fn()
+}));
+vi.mock("../../src/services/vtex/vtex-orders.js", () => ({
+  getOrderDocumentsBatch: vi.fn()
+}));
+vi.mock("../../src/utils/format-order-details.js", () => ({
+  formatOrderDetails: vi.fn()
+}));
+vi.mock("../../src/services/vtex/vtex-api.js", () => ({
+  formatVtexError: vi.fn(
+    (err, fallback) => `formatted:${fallback}:${err instanceof Error ? err.message : String(err)}`
+  )
+}));
+describe("order-details tool", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(resolveVtexProfileOrSelection).mockResolvedValue({
+      ok: true,
+      value: { profileId: "profile-1" }
+    });
+  });
+  it("deduplicates order ids, delegates batch fetch, and returns formatted payloads", async () => {
+    vi.mocked(getOrderDocumentsBatch).mockResolvedValue({
+      successful: [
+        { document: { orderId: "o-1" }, orderId: "o-1" },
+        { document: { orderId: "o-2" }, orderId: "o-2" }
+      ],
+      failed: [
+        {
+          orderId: "o-3",
+          message: "missing",
+          statusCode: 404,
+          attempts: 1,
+          retryable: false
+        }
+      ]
+    });
+    vi.mocked(formatOrderDetails).mockReturnValueOnce({
+      id: "o-1",
+      status: "ready",
+      created: "2026-06-01 10:00",
+      total: 100,
+      items: [],
+      shipping: [],
+      payments: []
+    }).mockReturnValueOnce({
+      id: "o-2",
+      status: "invoiced",
+      created: "2026-06-01 11:00",
+      total: 200,
+      items: [],
+      shipping: [],
+      payments: []
+    });
+    const result = await orderDetailsHandler({
+      profileId: "custom",
+      orderIds: ["o-1", "o-1", "o-2", "o-3"],
+      reason: "manual-review"
+    });
+    expect(resolveVtexProfileOrSelection).toHaveBeenCalledWith("custom");
+    expect(getOrderDocumentsBatch).toHaveBeenCalledWith(
+      "profile-1",
+      ["o-1", "o-2", "o-3"],
+      {
+        reason: "manual-review",
+        maxConcurrency: 10,
+        maxRetries: 2
+      }
+    );
+    expect(formatOrderDetails).toHaveBeenCalledTimes(2);
+    expect(result).toEqual({
+      kind: "object",
+      payload: {
+        metadata: {
+          profile_id: "profile-1",
+          requested: 3,
+          successful: 2,
+          failed: 1
+        },
+        schemas: {
+          item: ["id", "ref", "name", "qty", "price", "list"],
+          shipping: ["carrier", "estimate", "delivery_date"],
+          payment: ["system", "installments", "value"],
+          payment_validation: {
+            payments_total: "Sum of all payment values",
+            payment_delta: "Difference between payments_total and order total",
+            payment_mismatch: "True if |payment_delta| > 0.5 (potential issue)"
+          }
+        },
+        orders: [
+          {
+            id: "o-1",
+            status: "ready",
+            created: "2026-06-01 10:00",
+            total: 100
+          },
+          {
+            id: "o-2",
+            status: "invoiced",
+            created: "2026-06-01 11:00",
+            total: 200
+          }
+        ],
+        failures: [{ order_id: "o-3", message: "missing", status_code: 404 }]
+      }
+    });
+  });
+  it("returns profile selection payload unchanged when resolution fails", async () => {
+    vi.mocked(resolveVtexProfileOrSelection).mockResolvedValue({
+      ok: false,
+      response: { selection: true }
+    });
+    const result = await orderDetailsHandler({ orderIds: ["o-1"] });
+    expect(result).toEqual({ selection: true });
+    expect(getOrderDocumentsBatch).not.toHaveBeenCalled();
+  });
+  it("formats batch failures through formatVtexError", async () => {
+    vi.mocked(getOrderDocumentsBatch).mockRejectedValue(new Error("boom"));
+    const result = await orderDetailsHandler({
+      profileId: "custom",
+      orderIds: ["o-1"]
+    });
+    expect(formatVtexError).toHaveBeenCalled();
+    expect(result).toEqual({
+      kind: "error",
+      message: "formatted:Failed to fetch order details batch:boom"
+    });
+  });
+});
+//# sourceMappingURL=vtex-order-details.tool.test.js.map

package/dist/tests/vtex/vtex-order-details.tool.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/vtex/vtex-order-details.tool.test.ts"],
+  "sourcesContent": ["import { beforeEach, describe, expect, it, vi } from \"vitest\";\n\nimport { getOrderDocumentsBatch } from \"../../src/services/vtex/vtex-orders.js\";\nimport { formatVtexError } from \"../../src/services/vtex/vtex-api.js\";\nimport { orderDetailsHandler } from \"../../src/tools/vtex/order-details.js\";\nimport { resolveVtexProfileOrSelection } from \"../../src/tools/vtex/profile-resolution.js\";\nimport { formatOrderDetails } from \"../../src/utils/format-order-details.js\";\n\nvi.mock(\"mcp-use/server\", () => ({\n\tobject: vi.fn((payload: unknown) => ({ kind: \"object\", payload })),\n\terror: vi.fn((message: string) => ({ kind: \"error\", message })),\n}));\n\nvi.mock(\"../../src/tools/vtex/profile-resolution.js\", () => ({\n\tresolveVtexProfileOrSelection: vi.fn(),\n}));\n\nvi.mock(\"../../src/services/vtex/vtex-orders.js\", () => ({\n\tgetOrderDocumentsBatch: vi.fn(),\n}));\n\nvi.mock(\"../../src/utils/format-order-details.js\", () => ({\n\tformatOrderDetails: vi.fn(),\n}));\n\nvi.mock(\"../../src/services/vtex/vtex-api.js\", () => ({\n\tformatVtexError: vi.fn(\n\t\t(err: unknown, fallback: string) =>\n\t\t\t`formatted:${fallback}:${err instanceof Error ? err.message : String(err)}`,\n\t),\n}));\n\ndescribe(\"order-details tool\", () => {\n\tbeforeEach(() => {\n\t\tvi.clearAllMocks();\n\t\tvi.mocked(resolveVtexProfileOrSelection).mockResolvedValue({\n\t\t\tok: true,\n\t\t\tvalue: { profileId: \"profile-1\" },\n\t\t});\n\t});\n\n\tit(\"deduplicates order ids, delegates batch fetch, and returns formatted payloads\", async () => {\n\t\tvi.mocked(getOrderDocumentsBatch).mockResolvedValue({\n\t\t\tsuccessful: [\n\t\t\t\t{ document: { orderId: \"o-1\" }, orderId: \"o-1\" },\n\t\t\t\t{ document: { orderId: \"o-2\" }, orderId: \"o-2\" },\n\t\t\t],\n\t\t\tfailed: [\n\t\t\t\t{\n\t\t\t\t\torderId: \"o-3\",\n\t\t\t\t\tmessage: \"missing\",\n\t\t\t\t\tstatusCode: 404,\n\t\t\t\t\tattempts: 1,\n\t\t\t\t\tretryable: false,\n\t\t\t\t},\n\t\t\t],\n\t\t});\n\t\tvi.mocked(formatOrderDetails)\n\t\t\t.mockReturnValueOnce({\n\t\t\t\tid: \"o-1\",\n\t\t\t\tstatus: \"ready\",\n\t\t\t\tcreated: \"2026-06-01 10:00\",\n\t\t\t\ttotal: 100,\n\t\t\t\titems: [],\n\t\t\t\tshipping: [],\n\t\t\t\tpayments: [],\n\t\t\t} as never)\n\t\t\t.mockReturnValueOnce({\n\t\t\t\tid: \"o-2\",\n\t\t\t\tstatus: \"invoiced\",\n\t\t\t\tcreated: \"2026-06-01 11:00\",\n\t\t\t\ttotal: 200,\n\t\t\t\titems: [],\n\t\t\t\tshipping: [],\n\t\t\t\tpayments: [],\n\t\t\t} as never);\n\n\t\tconst result = await orderDetailsHandler({\n\t\t\tprofileId: \"custom\",\n\t\t\torderIds: [\"o-1\", \"o-1\", \"o-2\", \"o-3\"],\n\t\t\treason: \"manual-review\",\n\t\t});\n\n\t\texpect(resolveVtexProfileOrSelection).toHaveBeenCalledWith(\"custom\");\n\t\texpect(getOrderDocumentsBatch).toHaveBeenCalledWith(\n\t\t\t\"profile-1\",\n\t\t\t[\"o-1\", \"o-2\", \"o-3\"],\n\t\t\t{\n\t\t\t\treason: \"manual-review\",\n\t\t\t\tmaxConcurrency: 10,\n\t\t\t\tmaxRetries: 2,\n\t\t\t},\n\t\t);\n\t\texpect(formatOrderDetails).toHaveBeenCalledTimes(2);\n\t\texpect(result).toEqual({\n\t\t\tkind: \"object\",\n\t\t\tpayload: {\n\t\t\t\tmetadata: {\n\t\t\t\t\tprofile_id: \"profile-1\",\n\t\t\t\t\trequested: 3,\n\t\t\t\t\tsuccessful: 2,\n\t\t\t\t\tfailed: 1,\n\t\t\t\t},\n\t\t\t\tschemas: {\n\t\t\t\t\titem: [\"id\", \"ref\", \"name\", \"qty\", \"price\", \"list\"],\n\t\t\t\t\tshipping: [\"carrier\", \"estimate\", \"delivery_date\"],\n\t\t\t\t\tpayment: [\"system\", \"installments\", \"value\"],\n\t\t\t\t\tpayment_validation: {\n\t\t\t\t\t\tpayments_total: \"Sum of all payment values\",\n\t\t\t\t\t\tpayment_delta: \"Difference between payments_total and order total\",\n\t\t\t\t\t\tpayment_mismatch: \"True if |payment_delta| > 0.5 (potential issue)\",\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\torders: [\n\t\t\t\t\t{\n\t\t\t\t\t\tid: \"o-1\",\n\t\t\t\t\t\tstatus: \"ready\",\n\t\t\t\t\t\tcreated: \"2026-06-01 10:00\",\n\t\t\t\t\t\ttotal: 100,\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\t\t\t\tid: \"o-2\",\n\t\t\t\t\t\tstatus: \"invoiced\",\n\t\t\t\t\t\tcreated: \"2026-06-01 11:00\",\n\t\t\t\t\t\ttotal: 200,\n\t\t\t\t\t},\n\t\t\t\t],\n\t\t\t\tfailures: [{ order_id: \"o-3\", message: \"missing\", status_code: 404 }],\n\t\t\t},\n\t\t});\n\t});\n\n\tit(\"returns profile selection payload unchanged when resolution fails\", async () => {\n\t\tvi.mocked(resolveVtexProfileOrSelection).mockResolvedValue({\n\t\t\tok: false,\n\t\t\tresponse: { selection: true },\n\t\t} as never);\n\n\t\tconst result = await orderDetailsHandler({ orderIds: [\"o-1\"] });\n\n\t\texpect(result).toEqual({ selection: true });\n\t\texpect(getOrderDocumentsBatch).not.toHaveBeenCalled();\n\t});\n\n\tit(\"formats batch failures through formatVtexError\", async () => {\n\t\tvi.mocked(getOrderDocumentsBatch).mockRejectedValue(new Error(\"boom\"));\n\n\t\tconst result = await orderDetailsHandler({\n\t\t\tprofileId: \"custom\",\n\t\t\torderIds: [\"o-1\"],\n\t\t});\n\n\t\texpect(formatVtexError).toHaveBeenCalled();\n\t\texpect(result).toEqual({\n\t\t\tkind: \"error\",\n\t\t\tmessage: \"formatted:Failed to fetch order details batch:boom\",\n\t\t});\n\t});\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/tests/vtex/vtex-order-write-tools.test.js

@@ -0,0 +1,483 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { addOrderTrackingHandler } from "../../src/tools/vtex/add-order-tracking.js";
+import { cancelOrderHandler } from "../../src/tools/vtex/cancel-order.js";
+import { invoiceOrderHandler } from "../../src/tools/vtex/invoice-order.js";
+import {
+  cancelOrder,
+  getOrderStateSnapshot,
+  invoiceOrder,
+  updateOrderTrackingStatus,
+  updatePartialInvoiceTracking,
+  validateOrderForCancellation,
+  validateOrderForInvoice,
+  validateOrderForTracking
+} from "../../src/services/vtex/vtex-orders-write.js";
+import {
+  buildWriteSuccessResponse,
+  handleVtexWriteError,
+  requireExplicitConfirmation,
+  resolveVtexWriteProfile
+} from "../../src/tools/vtex/write-helpers.js";
+vi.mock("../../src/tools/vtex/write-helpers.js", () => ({
+  vtexProfileIdSchemaField: z.string().optional(),
+  confirmationSchemaField: z.boolean().optional(),
+  confirmationNoteSchemaField: z.string().optional(),
+  resolveVtexWriteProfile: vi.fn(),
+  requireExplicitConfirmation: vi.fn(),
+  buildWriteSuccessResponse: vi.fn((params) => ({
+    kind: "success",
+    params
+  })),
+  handleVtexWriteError: vi.fn((err, fallback) => ({
+    kind: "error",
+    fallback,
+    err
+  }))
+}));
+vi.mock("../../src/services/vtex/vtex-orders-write.js", () => ({
+  validateOrderForCancellation: vi.fn(),
+  cancelOrder: vi.fn(),
+  getOrderStateSnapshot: vi.fn(),
+  validateOrderForInvoice: vi.fn(),
+  invoiceOrder: vi.fn(),
+  validateOrderForTracking: vi.fn(),
+  updatePartialInvoiceTracking: vi.fn(),
+  updateOrderTrackingStatus: vi.fn()
+}));
+describe("VTEX order write tools", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(requireExplicitConfirmation).mockReturnValue(null);
+    vi.mocked(resolveVtexWriteProfile).mockResolvedValue({
+      ok: true,
+      value: { profileId: "profile-1" }
+    });
+  });
+  describe("cancelOrderHandler", () => {
+    it("returns confirmation-required payload before any write path", async () => {
+      vi.mocked(requireExplicitConfirmation).mockReturnValue({
+        confirmation: true
+      });
+      const result = await cancelOrderHandler({
+        profileId: "custom",
+        orderId: "order-1",
+        reason: "customer request"
+      });
+      expect(requireExplicitConfirmation).toHaveBeenCalledWith(
+        void 0,
+        "cancel_order",
+        {
+          order_id: "order-1"
+        }
+      );
+      expect(result).toEqual({ confirmation: true });
+      expect(resolveVtexWriteProfile).not.toHaveBeenCalled();
+      expect(validateOrderForCancellation).not.toHaveBeenCalled();
+    });
+    it("returns profile selection payload when profile resolution fails", async () => {
+      vi.mocked(resolveVtexWriteProfile).mockResolvedValue({
+        ok: false,
+        response: { selection: true }
+      });
+      const result = await cancelOrderHandler({
+        profileId: "custom",
+        orderId: "order-1",
+        confirmed: true
+      });
+      expect(result).toEqual({ selection: true });
+      expect(validateOrderForCancellation).not.toHaveBeenCalled();
+      expect(cancelOrder).not.toHaveBeenCalled();
+    });
+    it("validates, cancels, and re-fetches the order snapshot", async () => {
+      const beforeOrder = { orderId: "order-1", status: "handling" };
+      const afterOrder = { orderId: "order-1", status: "canceled" };
+      vi.mocked(validateOrderForCancellation).mockResolvedValue(
+        beforeOrder
+      );
+      vi.mocked(getOrderStateSnapshot).mockResolvedValue(afterOrder);
+      const result = await cancelOrderHandler({
+        profileId: "custom",
+        orderId: "order-1",
+        confirmed: true,
+        reason: "customer request",
+        confirmationNote: "User confirmed cancellation"
+      });
+      expect(validateOrderForCancellation).toHaveBeenCalledWith(
+        "profile-1",
+        "order-1",
+        "customer request"
+      );
+      expect(cancelOrder).toHaveBeenCalledWith(
+        "profile-1",
+        "order-1",
+        "customer request"
+      );
+      expect(getOrderStateSnapshot).toHaveBeenCalledWith(
+        "profile-1",
+        "order-1",
+        "customer request"
+      );
+      expect(
+        vi.mocked(validateOrderForCancellation).mock.invocationCallOrder[0]
+      ).toBeLessThan(vi.mocked(cancelOrder).mock.invocationCallOrder[0]);
+      expect(vi.mocked(cancelOrder).mock.invocationCallOrder[0]).toBeLessThan(
+        vi.mocked(getOrderStateSnapshot).mock.invocationCallOrder[0]
+      );
+      expect(buildWriteSuccessResponse).toHaveBeenCalledWith({
+        profileId: "profile-1",
+        operation: "cancel_order",
+        resourceId: "order-1",
+        riskLevel: "high",
+        confirmed: true,
+        confirmationNote: "User confirmed cancellation",
+        message: "Order canceled successfully.",
+        before: beforeOrder,
+        after: afterOrder,
+        details: { order_id: "order-1" }
+      });
+      expect(result).toEqual({
+        kind: "success",
+        params: expect.objectContaining({ operation: "cancel_order" })
+      });
+    });
+    it("maps service errors through handleVtexWriteError", async () => {
+      vi.mocked(validateOrderForCancellation).mockRejectedValue(
+        new Error("boom")
+      );
+      const result = await cancelOrderHandler({
+        profileId: "custom",
+        orderId: "order-1",
+        confirmed: true
+      });
+      expect(handleVtexWriteError).toHaveBeenCalledWith(
+        expect.any(Error),
+        "Failed to cancel order order-1"
+      );
+      expect(result).toEqual({
+        kind: "error",
+        fallback: "Failed to cancel order order-1",
+        err: expect.any(Error)
+      });
+    });
+  });
+  describe("invoiceOrderHandler", () => {
+    const invoicePayload = {
+      type: "Output",
+      issuanceDate: "2026-06-01T12:00:00Z",
+      invoiceNumber: "INV-123",
+      invoiceValue: "15000",
+      items: [
+        { id: "sku-1", price: 15e3, quantity: 1, description: "Main item" }
+      ],
+      invoiceKey: "KEY-1",
+      invoiceUrl: "https://example.com/invoice.pdf",
+      invoiceOrderNumber: "ERP-9",
+      courier: "Andreani",
+      trackingNumber: "TRK-1",
+      trackingUrl: "https://example.com/track/TRK-1"
+    };
+    it("returns confirmation-required payload before any write path", async () => {
+      vi.mocked(requireExplicitConfirmation).mockReturnValue({
+        confirmation: true
+      });
+      const result = await invoiceOrderHandler({
+        profileId: "custom",
+        orderId: "order-2",
+        ...invoicePayload
+      });
+      expect(requireExplicitConfirmation).toHaveBeenCalledWith(
+        void 0,
+        "invoice_order",
+        {
+          order_id: "order-2"
+        }
+      );
+      expect(result).toEqual({ confirmation: true });
+      expect(resolveVtexWriteProfile).not.toHaveBeenCalled();
+      expect(validateOrderForInvoice).not.toHaveBeenCalled();
+    });
+    it("returns profile selection payload when profile resolution fails", async () => {
+      vi.mocked(resolveVtexWriteProfile).mockResolvedValue({
+        ok: false,
+        response: { selection: true }
+      });
+      const result = await invoiceOrderHandler({
+        profileId: "custom",
+        orderId: "order-2",
+        confirmed: true,
+        ...invoicePayload
+      });
+      expect(result).toEqual({ selection: true });
+      expect(validateOrderForInvoice).not.toHaveBeenCalled();
+      expect(invoiceOrder).not.toHaveBeenCalled();
+    });
+    it("validates, invoices, and re-fetches the order snapshot", async () => {
+      const beforeOrder = { orderId: "order-2", invoiceNumbers: [] };
+      const afterOrder = { orderId: "order-2", invoiceNumbers: ["INV-123"] };
+      vi.mocked(validateOrderForInvoice).mockResolvedValue(
+        beforeOrder
+      );
+      vi.mocked(getOrderStateSnapshot).mockResolvedValue(afterOrder);
+      const result = await invoiceOrderHandler({
+        profileId: "custom",
+        orderId: "order-2",
+        confirmed: true,
+        confirmationNote: "User confirmed invoicing",
+        ...invoicePayload
+      });
+      expect(validateOrderForInvoice).toHaveBeenCalledWith(
+        "profile-1",
+        "order-2"
+      );
+      expect(invoiceOrder).toHaveBeenCalledWith(
+        "profile-1",
+        "order-2",
+        invoicePayload
+      );
+      expect(getOrderStateSnapshot).toHaveBeenCalledWith(
+        "profile-1",
+        "order-2"
+      );
+      expect(
+        vi.mocked(validateOrderForInvoice).mock.invocationCallOrder[0]
+      ).toBeLessThan(vi.mocked(invoiceOrder).mock.invocationCallOrder[0]);
+      expect(vi.mocked(invoiceOrder).mock.invocationCallOrder[0]).toBeLessThan(
+        vi.mocked(getOrderStateSnapshot).mock.invocationCallOrder[0]
+      );
+      expect(buildWriteSuccessResponse).toHaveBeenCalledWith({
+        profileId: "profile-1",
+        operation: "invoice_order",
+        resourceId: "order-2",
+        riskLevel: "high",
+        confirmed: true,
+        confirmationNote: "User confirmed invoicing",
+        message: "Order invoiced successfully.",
+        before: beforeOrder,
+        after: afterOrder,
+        details: {
+          order_id: "order-2",
+          invoice_number: "INV-123"
+        }
+      });
+      expect(result).toEqual({
+        kind: "success",
+        params: expect.objectContaining({ operation: "invoice_order" })
+      });
+    });
+    it("maps service errors through handleVtexWriteError", async () => {
+      vi.mocked(validateOrderForInvoice).mockRejectedValue(new Error("boom"));
+      const result = await invoiceOrderHandler({
+        profileId: "custom",
+        orderId: "order-2",
+        confirmed: true,
+        ...invoicePayload
+      });
+      expect(handleVtexWriteError).toHaveBeenCalledWith(
+        expect.any(Error),
+        "Failed to invoice order order-2"
+      );
+      expect(result).toEqual({
+        kind: "error",
+        fallback: "Failed to invoice order order-2",
+        err: expect.any(Error)
+      });
+    });
+  });
+  describe("addOrderTrackingHandler", () => {
+    const baseTrackingPayload = {
+      invoiceNumber: "INV-999",
+      trackingNumber: "TRK-999",
+      trackingUrl: "https://example.com/track/TRK-999",
+      courier: "OCA",
+      dispatchedDate: "2026-06-01T14:00:00Z"
+    };
+    it("returns confirmation-required payload before any write path", async () => {
+      vi.mocked(requireExplicitConfirmation).mockReturnValue({
+        confirmation: true
+      });
+      const result = await addOrderTrackingHandler({
+        profileId: "custom",
+        orderId: "order-3",
+        ...baseTrackingPayload
+      });
+      expect(requireExplicitConfirmation).toHaveBeenCalledWith(
+        void 0,
+        "add_order_tracking",
+        {
+          order_id: "order-3",
+          invoice_number: "INV-999"
+        }
+      );
+      expect(result).toEqual({ confirmation: true });
+      expect(resolveVtexWriteProfile).not.toHaveBeenCalled();
+      expect(validateOrderForTracking).not.toHaveBeenCalled();
+    });
+    it("returns profile selection payload when profile resolution fails", async () => {
+      vi.mocked(resolveVtexWriteProfile).mockResolvedValue({
+        ok: false,
+        response: { selection: true }
+      });
+      const result = await addOrderTrackingHandler({
+        profileId: "custom",
+        orderId: "order-3",
+        confirmed: true,
+        ...baseTrackingPayload
+      });
+      expect(result).toEqual({ selection: true });
+      expect(validateOrderForTracking).not.toHaveBeenCalled();
+      expect(updatePartialInvoiceTracking).not.toHaveBeenCalled();
+    });
+    it("updates partial tracking and skips status update when no events or delivery state are provided", async () => {
+      const beforeOrder = { orderId: "order-3", invoiceNumbers: ["INV-999"] };
+      const afterOrder = { orderId: "order-3", invoiceNumbers: ["INV-999"] };
+      vi.mocked(validateOrderForTracking).mockResolvedValue(
+        beforeOrder
+      );
+      vi.mocked(getOrderStateSnapshot).mockResolvedValue(afterOrder);
+      const result = await addOrderTrackingHandler({
+        profileId: "custom",
+        orderId: "order-3",
+        confirmed: true,
+        confirmationNote: "User confirmed tracking update",
+        ...baseTrackingPayload
+      });
+      expect(validateOrderForTracking).toHaveBeenCalledWith(
+        "profile-1",
+        "order-3",
+        "INV-999"
+      );
+      expect(updatePartialInvoiceTracking).toHaveBeenCalledWith(
+        "profile-1",
+        "order-3",
+        "INV-999",
+        {
+          trackingNumber: "TRK-999",
+          trackingUrl: "https://example.com/track/TRK-999",
+          courier: "OCA",
+          dispatchedDate: "2026-06-01T14:00:00Z"
+        }
+      );
+      expect(updateOrderTrackingStatus).not.toHaveBeenCalled();
+      expect(getOrderStateSnapshot).toHaveBeenCalledWith(
+        "profile-1",
+        "order-3"
+      );
+      expect(buildWriteSuccessResponse).toHaveBeenCalledWith({
+        profileId: "profile-1",
+        operation: "add_order_tracking",
+        resourceId: "order-3",
+        riskLevel: "high",
+        confirmed: true,
+        confirmationNote: "User confirmed tracking update",
+        message: "Order tracking updated successfully.",
+        before: beforeOrder,
+        after: afterOrder,
+        details: {
+          order_id: "order-3",
+          invoice_number: "INV-999",
+          tracking_number: "TRK-999"
+        }
+      });
+      expect(result).toEqual({
+        kind: "success",
+        params: expect.objectContaining({ operation: "add_order_tracking" })
+      });
+    });
+    it("updates tracking status when events or delivery state are provided", async () => {
+      const beforeOrder = { orderId: "order-3", invoiceNumbers: ["INV-999"] };
+      const afterOrder = { orderId: "order-3", invoiceNumbers: ["INV-999"] };
+      vi.mocked(validateOrderForTracking).mockResolvedValue(
+        beforeOrder
+      );
+      vi.mocked(getOrderStateSnapshot).mockResolvedValue(afterOrder);
+      await addOrderTrackingHandler({
+        profileId: "custom",
+        orderId: "order-3",
+        confirmed: true,
+        ...baseTrackingPayload,
+        isDelivered: true,
+        deliveredDate: "2026-06-02 10:30",
+        events: [
+          {
+            city: "CABA",
+            state: "AR-C",
+            description: "Delivered",
+            date: "2026-06-02 10:30"
+          }
+        ]
+      });
+      expect(updateOrderTrackingStatus).toHaveBeenCalledWith(
+        "profile-1",
+        "order-3",
+        "INV-999",
+        {
+          isDelivered: true,
+          deliveredDate: "2026-06-02 10:30",
+          events: [
+            {
+              city: "CABA",
+              state: "AR-C",
+              description: "Delivered",
+              date: "2026-06-02 10:30"
+            }
+          ]
+        }
+      );
+      expect(
+        vi.mocked(updatePartialInvoiceTracking).mock.invocationCallOrder[0]
+      ).toBeLessThan(
+        vi.mocked(updateOrderTrackingStatus).mock.invocationCallOrder[0]
+      );
+    });
+    it("updates tracking status even when isDelivered is explicitly false", async () => {
+      const beforeOrder = { orderId: "order-3", invoiceNumbers: ["INV-999"] };
+      const afterOrder = { orderId: "order-3", invoiceNumbers: ["INV-999"] };
+      vi.mocked(validateOrderForTracking).mockResolvedValue(
+        beforeOrder
+      );
+      vi.mocked(getOrderStateSnapshot).mockResolvedValue(afterOrder);
+      await addOrderTrackingHandler({
+        profileId: "custom",
+        orderId: "order-3",
+        confirmed: true,
+        ...baseTrackingPayload,
+        isDelivered: false
+      });
+      expect(updateOrderTrackingStatus).toHaveBeenCalledWith(
+        "profile-1",
+        "order-3",
+        "INV-999",
+        {
+          isDelivered: false,
+          deliveredDate: null,
+          events: []
+        }
+      );
+      expect(
+        vi.mocked(updatePartialInvoiceTracking).mock.invocationCallOrder[0]
+      ).toBeLessThan(
+        vi.mocked(updateOrderTrackingStatus).mock.invocationCallOrder[0]
+      );
+    });
+    it("maps service errors through handleVtexWriteError", async () => {
+      vi.mocked(validateOrderForTracking).mockRejectedValue(new Error("boom"));
+      const result = await addOrderTrackingHandler({
+        profileId: "custom",
+        orderId: "order-3",
+        confirmed: true,
+        ...baseTrackingPayload
+      });
+      expect(handleVtexWriteError).toHaveBeenCalledWith(
+        expect.any(Error),
+        "Failed to update tracking for order order-3"
+      );
+      expect(result).toEqual({
+        kind: "error",
+        fallback: "Failed to update tracking for order order-3",
+        err: expect.any(Error)
+      });
+    });
+  });
+});
+//# sourceMappingURL=vtex-order-write-tools.test.js.map