@yoryoboy/bi-mcp 1.14.3 → 1.16.0

package/dist/tests/meli/mercadolibre-billing-provisions.test.js

@@ -0,0 +1,940 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+const { axiosGetMock, errorMock, objectMock, resolveProfileMock, formatErrorMock, apiContextMock } = vi.hoisted(() => ({
+  axiosGetMock: vi.fn(),
+  errorMock: vi.fn((message) => ({ kind: "error", message })),
+  objectMock: vi.fn((payload) => ({ kind: "object", payload })),
+  resolveProfileMock: vi.fn(),
+  formatErrorMock: vi.fn(
+    (err, fallback) => `formatted:${fallback}:${err instanceof Error ? err.message : String(err)}`
+  ),
+  apiContextMock: vi.fn(
+    (profileId) => Promise.resolve({
+      sellerId: `seller-${profileId}`,
+      scopes: ["read"],
+      expiresAt: "2026-12-31T00:00:00.000Z",
+      api: { get: axiosGetMock }
+    })
+  )
+}));
+vi.mock("mcp-use/server", () => ({
+  object: objectMock,
+  error: errorMock
+}));
+vi.mock("../../src/services/mercadolibre/mercadolibre-api.js", () => ({
+  getMercadoLibreApiContext: apiContextMock,
+  formatMercadoLibreError: formatErrorMock
+}));
+vi.mock("../../src/tools/mercadolibre/profile-resolution.js", () => ({
+  resolveMercadoLibreProfileOrSelection: resolveProfileMock
+}));
+import {
+  getMercadoLibreBillingProvisionPage,
+  getMercadoLibreBillingProvisions,
+  scopeToGroupPath
+} from "../../src/services/mercadolibre/mercadolibre-billing.js";
+import {
+  meliGetBillingProvisionsSummaryHandler,
+  meliGetBillingProvisionsSummarySchema,
+  detailsSchema,
+  detailsSalesSchema,
+  detailsItemsSchema
+} from "../../src/tools/mercadolibre/get-billing-provisions-summary.js";
+function nestedRow(overrides = {}) {
+  const chargeInfo = overrides.charge_info ?? {};
+  const currencyInfo = overrides.currency_info ?? {};
+  const salesInfo = overrides.sales_info;
+  const itemsInfo = overrides.items_info;
+  const marketplaceInfo = overrides.marketplace_info;
+  return {
+    charge_info: {
+      detail_id: chargeInfo.detail_id ?? `id-${Math.random().toString(36).slice(2, 8)}`,
+      detail_amount: chargeInfo.detail_amount ?? 0,
+      detail_sub_type: chargeInfo.detail_sub_type ?? "",
+      concept_type: chargeInfo.concept_type ?? "",
+      transaction_detail: chargeInfo.transaction_detail ?? "",
+      detail_type: chargeInfo.detail_type ?? "",
+      creation_date_time: chargeInfo.creation_date_time ?? "",
+      ...chargeInfo
+    },
+    currency_info: {
+      currency_id: currencyInfo.currency_id ?? "ARS",
+      ...currencyInfo
+    },
+    sales_info: salesInfo ?? [],
+    items_info: itemsInfo ?? [],
+    marketplace_info: marketplaceInfo ?? {},
+    ...overrides
+  };
+}
+describe("scopeToGroupPath", () => {
+  it("maps ml to ML", () => {
+    expect(scopeToGroupPath("ml")).toBe("ML");
+  });
+  it("maps mp to MP", () => {
+    expect(scopeToGroupPath("mp")).toBe("MP");
+  });
+  it("maps flex to ML/flex", () => {
+    expect(scopeToGroupPath("flex")).toBe("ML/flex");
+  });
+  it("maps full to ML/full", () => {
+    expect(scopeToGroupPath("full")).toBe("ML/full");
+  });
+});
+describe("getMercadoLibreBillingProvisionPage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  function mockApiResponse(results = [], overrides = {}) {
+    const total = overrides.total ?? results.length;
+    const limit = overrides.limit ?? 1e3;
+    const last_id = overrides.last_id ?? (results.length > 0 ? "last-99" : null);
+    return {
+      data: { results, last_id, total, limit }
+    };
+  }
+  it("builds correct URL for flex scope", async () => {
+    axiosGetMock.mockResolvedValue(mockApiResponse());
+    await getMercadoLibreBillingProvisionPage("profile-1", {
+      periodKey: "2026-06-01",
+      scope: "flex",
+      documentType: "BILL",
+      limit: 1e3
+    });
+    const call = axiosGetMock.mock.calls[0];
+    expect(call[0]).toContain("/group/ML/flex/details");
+    expect(call[1].params.document_type).toBe("BILL");
+    expect(call[1].params.limit).toBe(1e3);
+  });
+  it("builds correct URL for mp scope", async () => {
+    axiosGetMock.mockResolvedValue(mockApiResponse());
+    await getMercadoLibreBillingProvisionPage("profile-1", {
+      periodKey: "2026-06-01",
+      scope: "mp",
+      documentType: "BILL",
+      limit: 1e3
+    });
+    expect(axiosGetMock.mock.calls[0][0]).toContain("/group/MP/details");
+  });
+  it("passes from_id when provided", async () => {
+    axiosGetMock.mockResolvedValue(mockApiResponse());
+    await getMercadoLibreBillingProvisionPage("profile-1", {
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL",
+      limit: 1e3,
+      fromId: "abc-123"
+    });
+    expect(axiosGetMock.mock.calls[0][1].params.from_id).toBe("abc-123");
+  });
+  it("passes optional filter params", async () => {
+    axiosGetMock.mockResolvedValue(mockApiResponse());
+    await getMercadoLibreBillingProvisionPage("profile-1", {
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL",
+      limit: 1e3,
+      detailType: "sale",
+      detailSubTypes: ["commission"],
+      marketplaceType: "classic",
+      orderIds: ["O1"],
+      itemIds: ["I1"]
+    });
+    const p = axiosGetMock.mock.calls[0][1].params;
+    expect(p.detail_type).toBe("sale");
+    expect(p.detail_sub_types).toBe("commission");
+    expect(p.marketplace_type).toBe("classic");
+    expect(p.order_ids).toBe("O1");
+    expect(p.item_ids).toBe("I1");
+  });
+  it("reads flat total/limit from real MELI envelope (no paging nesting)", async () => {
+    axiosGetMock.mockResolvedValue({
+      data: {
+        results: [nestedRow({ charge_info: { detail_id: "d1", detail_amount: 10 } })],
+        last_id: "last-1",
+        total: 42,
+        limit: 500
+      }
+    });
+    const page = await getMercadoLibreBillingProvisionPage("profile-1", {
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL",
+      limit: 1e3
+    });
+    expect(page.total).toBe(42);
+    expect(page.limit).toBe(500);
+    expect(page.paging).toBeUndefined();
+  });
+});
+describe("getMercadoLibreBillingProvisions", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  function mockApi(results, last_id, total, limit = 1e3) {
+    return { data: { results, last_id, total, limit } };
+  }
+  it("deduplicates by charge_info.detail_id across pages", async () => {
+    axiosGetMock.mockResolvedValueOnce(mockApi([
+      nestedRow({ charge_info: { detail_id: "a", detail_amount: 10 } }),
+      nestedRow({ charge_info: { detail_id: "b", detail_amount: 20 } })
+    ], "last-1", 3)).mockResolvedValueOnce(mockApi([
+      nestedRow({ charge_info: { detail_id: "b", detail_amount: 20 } }),
+      // duplicate
+      nestedRow({ charge_info: { detail_id: "c", detail_amount: 30 } })
+    ], null, 3));
+    const result = await getMercadoLibreBillingProvisions("profile-1", {
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    expect(result.detail_count_total).toBe(3);
+    expect(result.coverage_complete).toBe(true);
+    expect(result.rows.length).toBe(3);
+  });
+  it("stops when last_id does not advance", async () => {
+    axiosGetMock.mockResolvedValueOnce(mockApi([
+      nestedRow({ charge_info: { detail_id: "a", detail_amount: 10 } })
+    ], "stuck-id", 1)).mockResolvedValueOnce(mockApi([
+      nestedRow({ charge_info: { detail_id: "b", detail_amount: 20 } })
+    ], "stuck-id", 2));
+    const result = await getMercadoLibreBillingProvisions("profile-1", {
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    expect(result.pages_requested).toBe(2);
+    expect(result.detail_count_total).toBe(2);
+    expect(result.coverage_complete).toBe(false);
+  });
+  it("returns coverage_complete=false with failures and breaks on error", async () => {
+    axiosGetMock.mockResolvedValueOnce(mockApi([
+      nestedRow({ charge_info: { detail_id: "a", detail_amount: 10 } })
+    ], "page-1-last", 10)).mockRejectedValueOnce(new Error("Network error"));
+    const result = await getMercadoLibreBillingProvisions("profile-1", {
+      periodKey: "2026-06-01",
+      scope: "mp",
+      documentType: "BILL"
+    });
+    expect(result.pages_requested).toBe(2);
+    expect(result.pages_succeeded).toBe(1);
+    expect(result.pages_failed).toBe(1);
+    expect(result.coverage_complete).toBe(false);
+    expect(result.failures).toHaveLength(1);
+    expect(result.failures[0].page).toBe(2);
+    expect(result.rows.length).toBe(1);
+  });
+  it("handles empty results gracefully", async () => {
+    axiosGetMock.mockResolvedValueOnce(mockApi([], null, 0));
+    const result = await getMercadoLibreBillingProvisions("profile-1", {
+      periodKey: "2026-06-01",
+      scope: "full",
+      documentType: "BILL"
+    });
+    expect(result.pages_requested).toBe(1);
+    expect(result.detail_count_total).toBe(0);
+    expect(result.coverage_complete).toBe(true);
+  });
+});
+describe("meliGetBillingProvisionsSummaryHandler", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(resolveProfileMock).mockResolvedValue({
+      ok: true,
+      value: { profileId: "meli-profile-1" }
+    });
+  });
+  function mockApi(results, last_id = null, total) {
+    return { data: { results, last_id, total: total ?? results.length, limit: 1e3 } };
+  }
+  it("validates schema: periodKey must be YYYY-MM-01 format", () => {
+    const valid = "2026-06-01";
+    const invalid = "2026-06-15";
+    expect(() => meliGetBillingProvisionsSummarySchema.parse({ periodKey: valid, scope: "ml" })).not.toThrow();
+    expect(() => meliGetBillingProvisionsSummarySchema.parse({ periodKey: invalid, scope: "ml" })).toThrow();
+  });
+  it("validates schema: scope must be valid enum", () => {
+    expect(
+      () => meliGetBillingProvisionsSummarySchema.parse({ periodKey: "2026-06-01", scope: "ml" })
+    ).not.toThrow();
+    expect(
+      () => meliGetBillingProvisionsSummarySchema.parse({ periodKey: "2026-06-01", scope: "invalid" })
+    ).toThrow();
+  });
+  it("aggregates single scope with currency totals using nested payload shape", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({
+        charge_info: { detail_id: "d1", detail_amount: 100, detail_sub_type: "CVFV", transaction_detail: "Cargo por vender" },
+        sales_info: [{ order_id: "O1" }],
+        items_info: [{ item_id: "I1" }]
+      }),
+      nestedRow({
+        charge_info: { detail_id: "d2", detail_amount: 25, detail_sub_type: "CFF", transaction_detail: "Cargo por env\xEDos de Mercado Libre" },
+        sales_info: [{ order_id: "O2" }]
+      }),
+      nestedRow({
+        charge_info: { detail_id: "d3", detail_amount: 150, detail_sub_type: "CVFV", transaction_detail: "Cargo por vender" },
+        currency_info: { currency_id: "USD" },
+        sales_info: [{ order_id: "O3" }]
+      })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    expect(result).toHaveProperty("kind", "object");
+    const payload = result.payload;
+    expect(payload.profile_id).toBe("meli-profile-1");
+    expect(payload.scope).toBe("ml");
+    expect(payload.details_schema).toEqual(detailsSchema);
+    const details = payload.details;
+    expect(details).toHaveLength(3);
+    for (const row of details) {
+      expect(Array.isArray(row)).toBe(true);
+      expect(row).toHaveLength(detailsSchema.length);
+    }
+    expect(details[0][0]).toBe("d1");
+    expect(details[0][4]).toBe(100);
+    expect(details[0][5]).toBe("ARS");
+    expect(details[0][8]).toBe("O1");
+    expect(details[0][10]).toBe("I1");
+    expect(details[2][5]).toBe("USD");
+    const summary = payload.summary;
+    expect(summary.detail_count).toBe(3);
+    expect(summary.order_count_detected).toBe(3);
+    expect(summary.item_count_detected).toBe(1);
+    const currTotals = summary.currency_totals;
+    expect(currTotals).toHaveProperty("ARS");
+    expect(currTotals).toHaveProperty("USD");
+    const arsBucket = currTotals.ARS;
+    expect(Object.keys(arsBucket).sort()).toEqual([
+      "bonus_amount_total",
+      "charge_amount_total",
+      "discount_amount_total",
+      "net_effect_total"
+    ]);
+    expect(arsBucket.charge_amount_total).toBe(125);
+    expect(arsBucket.bonus_amount_total).toBe(0);
+    expect(arsBucket.discount_amount_total).toBe(0);
+    expect(arsBucket.net_effect_total).toBe(125);
+    expect(currTotals.USD.charge_amount_total).toBe(150);
+    expect(summary.totals_by_concept).toBeUndefined();
+    expect(summary.totals_by_concept_by_currency).toBeUndefined();
+    expect(payload.raw_sections).toBeUndefined();
+    expect(payload.enriched_sections).toBeUndefined();
+    expect(payload.classification_diagnostics).toBeUndefined();
+    expect(payload.summary_by_scope).toBeUndefined();
+    const diag = payload.diagnostics;
+    expect(diag).toHaveProperty("detail_sub_types_observed");
+    expect(diag).toHaveProperty("marketplaces_observed");
+    expect(diag).toHaveProperty("concept_types_observed");
+    expect(Array.isArray(diag.detail_sub_types_observed)).toBe(true);
+    const metadata = payload.metadata;
+    expect(metadata.coverage_complete).toBe(true);
+    expect(metadata.coverage_by_scope).toBeDefined();
+  });
+  it("handles scope=all by calling all four scopes with nested payload", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({
+        charge_info: { detail_id: "shared-1", detail_amount: 50, detail_sub_type: "sale" },
+        sales_info: [{ order_id: "O-COMMON" }],
+        items_info: [{ item_id: "I-COMMON" }]
+      })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "all",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    expect(payload.scope).toBe("all");
+    const summary = payload.summary;
+    expect(summary.detail_count).toBe(4);
+    expect(summary.order_count_detected).toBe(1);
+    expect(summary.item_count_detected).toBe(1);
+    const details = payload.details;
+    expect(details).toHaveLength(4);
+    const metadata = payload.metadata;
+    expect(metadata.sources_called).toBe(4);
+    expect(metadata.pages_succeeded).toBe(4);
+    expect(metadata.coverage_complete).toBe(true);
+    expect(metadata.coverage_by_scope).toBeDefined();
+  });
+  it("handles credit notes with negative amounts \u2014 nested shape", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "d1", detail_amount: 500, detail_sub_type: "CVFV", transaction_detail: "Cargo por vender" } }),
+      nestedRow({ charge_info: { detail_id: "d2", detail_amount: -150, detail_sub_type: "BVFV", transaction_detail: "Anulaci\xF3n del cargo por vender" } }),
+      nestedRow({ charge_info: { detail_id: "d3", detail_amount: -50, detail_sub_type: "BFF", transaction_detail: "Anulaci\xF3n del cargo por env\xEDos" } })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "CREDIT_NOTE"
+    });
+    const payload = result.payload;
+    expect(payload.document_type).toBe("CREDIT_NOTE");
+    const currTotals = payload.summary.currency_totals;
+    expect(currTotals.ARS.charge_amount_total).toBe(500);
+    expect(currTotals.ARS.bonus_amount_total).toBe(-200);
+    expect(currTotals.ARS.discount_amount_total).toBe(0);
+    expect(currTotals.ARS.net_effect_total).toBe(300);
+  });
+  it("handles mixed positive and negative amounts within same concept (nested)", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "d1", detail_amount: 200, detail_sub_type: "CVFV", transaction_detail: "Cargo por vender" } }),
+      nestedRow({ charge_info: { detail_id: "d2", detail_amount: -80, detail_sub_type: "BVFF", transaction_detail: "Anulaci\xF3n del costo por unidad vendida" } }),
+      nestedRow({ charge_info: { detail_id: "d3", detail_amount: 50, detail_sub_type: "CFF", transaction_detail: "Cargo por env\xEDos de Mercado Libre" } }),
+      nestedRow({ charge_info: { detail_id: "d4", detail_amount: -20, detail_sub_type: "BXD", transaction_detail: "Anulaci\xF3n del cargo por env\xEDos" } })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const currTotals = payload.summary.currency_totals;
+    expect(currTotals.ARS.charge_amount_total).toBe(250);
+    expect(currTotals.ARS.bonus_amount_total).toBe(-100);
+    expect(currTotals.ARS.discount_amount_total).toBe(0);
+    expect(currTotals.ARS.net_effect_total).toBe(150);
+  });
+  it("deduplicates order and item counts globally across scopes", async () => {
+    let callCount = 0;
+    axiosGetMock.mockImplementation(() => {
+      callCount++;
+      const scopeIndex = callCount - 1;
+      const scopes = ["ml", "mp", "flex", "full"];
+      const isPayment = scopes[scopeIndex] === "mp";
+      return Promise.resolve(mockApi([
+        nestedRow({
+          charge_info: {
+            detail_id: `d-${scopes[scopeIndex]}`,
+            detail_amount: 50,
+            detail_sub_type: isPayment ? "payment" : "sale"
+          },
+          sales_info: [{ order_id: "ORDER-1" }],
+          items_info: [{ item_id: scopeIndex < 2 ? "ITEM-A" : "ITEM-B" }]
+        })
+      ]));
+    });
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "all",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const summary = payload.summary;
+    expect(summary.detail_count).toBe(4);
+    expect(summary.order_count_detected).toBe(1);
+    expect(summary.item_count_detected).toBe(2);
+  });
+  it("includes coverage_by_scope with per-scope operational metadata", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "d1", detail_amount: 10 } })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const covByScope = payload.metadata.coverage_by_scope;
+    expect(covByScope).toHaveProperty("ml");
+    expect(covByScope.ml.coverage_complete).toBe(true);
+    expect(covByScope.ml.last_id_seen).toBeUndefined();
+    expect(typeof covByScope.ml.pages_requested).toBe("number");
+    expect(typeof covByScope.ml.pages_succeeded).toBe("number");
+    expect(typeof covByScope.ml.pages_failed).toBe("number");
+    expect(typeof covByScope.ml.detail_count).toBe("number");
+  });
+  it("continuation_by_scope is absent when coverage is complete", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "d1", detail_amount: 10 } })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    expect(payload.metadata.continuation_by_scope).toBeUndefined();
+  });
+  it("reports coverage_complete=false and continuation_by_scope when a scope has partial coverage", async () => {
+    axiosGetMock.mockResolvedValueOnce(mockApi([
+      nestedRow({ charge_info: { detail_id: "a", detail_amount: 10 } })
+    ], "page-1-last", 10)).mockRejectedValueOnce(new Error("Network error"));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const metadata = payload.metadata;
+    expect(metadata.coverage_complete).toBe(false);
+    expect(metadata.pages_succeeded).toBe(1);
+    expect(metadata.pages_failed).toBe(1);
+    expect(metadata.coverage_by_scope).toBeDefined();
+    const covByScope = metadata.coverage_by_scope;
+    expect(covByScope.ml.coverage_complete).toBe(false);
+    expect(covByScope.ml.last_id_seen).toBe("page-1-last");
+    expect(metadata.continuation_by_scope).toBeDefined();
+    const continuation = metadata.continuation_by_scope;
+    expect(continuation.ml.last_id).toBe("page-1-last");
+    expect(typeof continuation.ml.hint).toBe("string");
+    expect(continuation.ml.hint).toContain("fromIdByScope");
+    expect(continuation.ml.hint).toContain("page-1-last");
+  });
+  it("multi-currency: totals_by_concept is absent \u2014 only currency_totals with four fields", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "d1", detail_amount: 1e3, detail_sub_type: "CVFV", transaction_detail: "Cargo por vender" } }),
+      nestedRow({ charge_info: { detail_id: "d2", detail_amount: 200, detail_sub_type: "CFF", transaction_detail: "Cargo por env\xEDos de Mercado Libre" } }),
+      nestedRow({
+        charge_info: { detail_id: "d3", detail_amount: 50, detail_sub_type: "CVFV", transaction_detail: "Cargo por vender" },
+        currency_info: { currency_id: "USD" }
+      }),
+      nestedRow({
+        charge_info: { detail_id: "d4", detail_amount: 10, detail_sub_type: "CVFN", transaction_detail: "Costo por ofrecer cuotas" },
+        currency_info: { currency_id: "USD" }
+      }),
+      nestedRow({
+        charge_info: { detail_id: "d5", detail_amount: -5, detail_sub_type: "BVFV", transaction_detail: "Anulaci\xF3n del cargo por vender" },
+        currency_info: { currency_id: "USD" }
+      })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const summary = payload.summary;
+    expect(summary.totals_by_concept).toBeUndefined();
+    expect(summary.totals_by_concept_by_currency).toBeUndefined();
+    const currTotals = summary.currency_totals;
+    expect(currTotals.ARS.charge_amount_total).toBe(1200);
+    expect(currTotals.ARS.bonus_amount_total).toBe(0);
+    expect(currTotals.ARS.net_effect_total).toBe(1200);
+    expect(currTotals.USD.charge_amount_total).toBe(60);
+    expect(currTotals.USD.bonus_amount_total).toBe(-5);
+    expect(currTotals.USD.net_effect_total).toBe(55);
+    expect(currTotals.ARS.by_concept).toBeUndefined();
+    expect(currTotals.USD.by_concept).toBeUndefined();
+  });
+  it("details rows are reversible with compact schema", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({
+        charge_info: {
+          detail_id: "rev-1",
+          detail_amount: 500,
+          detail_sub_type: "CVFV",
+          transaction_detail: "Cargo por vender",
+          detail_type: "CHARGE",
+          concept_type: "sale",
+          creation_date_time: "2026-06-15T10:30:00Z"
+        },
+        currency_info: { currency_id: "ARS" },
+        marketplace_info: { marketplace: "MCLICS" },
+        sales_info: [{ order_id: "ORD-100", operation_id: "OP-200", shipping_id: "SH-300", pack_id: "PK-400" }],
+        items_info: [{ item_id: "MLB-500", item_title: "Zapatillas Nike" }],
+        document_id: "DOC-999"
+      })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const schema = payload.details_schema;
+    const details = payload.details;
+    const row = details[0];
+    const reconstructed = {};
+    schema.forEach((key, i) => {
+      reconstructed[key] = row[i];
+    });
+    expect(reconstructed.detail_id).toBe("rev-1");
+    expect(reconstructed.detail_type).toBe("CHARGE");
+    expect(reconstructed.detail_sub_type).toBe("CVFV");
+    expect(reconstructed.transaction_detail).toBe("Cargo por vender");
+    expect(reconstructed.detail_amount).toBe(500);
+    expect(reconstructed.currency_id).toBe("ARS");
+    expect(reconstructed.marketplace).toBe("MCLICS");
+    expect(reconstructed.concept_type).toBe("sale");
+    expect(reconstructed.order_id).toBe("ORD-100");
+    expect(reconstructed.operation_id).toBe("OP-200");
+    expect(reconstructed.item_id).toBe("MLB-500");
+    expect(reconstructed.item_title).toBe("Zapatillas Nike");
+    expect(reconstructed.shipping_id).toBe("SH-300");
+    expect(reconstructed.pack_id).toBe("PK-400");
+    expect(reconstructed.document_id).toBe("DOC-999");
+    expect(reconstructed.creation_date_time).toBe("2026-06-15T10:30:00Z");
+    expect(reconstructed.sales_info_count).toBe(1);
+    expect(reconstructed.items_info_count).toBe(1);
+  });
+  it("returns profile selection when profileId is missing", async () => {
+    vi.mocked(resolveProfileMock).mockResolvedValue({
+      ok: false,
+      response: { selection_required: true }
+    });
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    expect(result).toEqual({ selection_required: true });
+  });
+  it("defaults documentType to BILL when omitted", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "d1", detail_amount: 10 } })
+    ]));
+    await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml"
+    });
+    const call = axiosGetMock.mock.calls[0];
+    expect(call[1].params.document_type).toBe("BILL");
+  });
+  it("passes fromIdByScope cursor to the service layer", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "d1", detail_amount: 10 } })
+    ]));
+    await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL",
+      fromIdByScope: { ml: "cursor-ml-99" }
+    });
+    const call = axiosGetMock.mock.calls[0];
+    expect(call[1].params.from_id).toBe("cursor-ml-99");
+  });
+  it("passes fromIdByScope for scope=all with per-scope cursors", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "d1", detail_amount: 10 } })
+    ]));
+    await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "all",
+      documentType: "BILL",
+      fromIdByScope: {
+        ml: "ml-cursor-1",
+        mp: "mp-cursor-2"
+      }
+    });
+    const allCalls = axiosGetMock.mock.calls;
+    expect(allCalls[0][1].params.from_id).toBe("ml-cursor-1");
+    expect(allCalls[1][1].params.from_id).toBe("mp-cursor-2");
+    expect(allCalls[2][1].params.from_id).toBeUndefined();
+    expect(allCalls[3][1].params.from_id).toBeUndefined();
+  });
+  it("diagnostics reports observed detail_sub_types", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "1", detail_amount: 100, detail_sub_type: "CVFV" } }),
+      nestedRow({ charge_info: { detail_id: "2", detail_amount: 50, detail_sub_type: "CFF" } }),
+      nestedRow({ charge_info: { detail_id: "3", detail_amount: 30, detail_sub_type: "PADS" } })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const diag = payload.diagnostics;
+    expect(diag.detail_sub_types_observed).toContain("CVFV");
+    expect(diag.detail_sub_types_observed).toContain("CFF");
+    expect(diag.detail_sub_types_observed).toContain("PADS");
+    expect(diag.detail_sub_types_observed).toHaveLength(3);
+  });
+  it("diagnostics reports observed marketplaces", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({
+        charge_info: { detail_id: "1", detail_amount: 100, detail_sub_type: "CVFV" },
+        marketplace_info: { marketplace: "MCLICS" }
+      }),
+      nestedRow({
+        charge_info: { detail_id: "2", detail_amount: 50, detail_sub_type: "CFF" },
+        marketplace_info: { marketplace: "TAXES" }
+      })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "mp",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const diag = payload.diagnostics;
+    expect(diag.marketplaces_observed).toContain("MCLICS");
+    expect(diag.marketplaces_observed).toContain("TAXES");
+    expect(diag.marketplaces_observed).toHaveLength(2);
+  });
+  it("diagnostics reports observed concept_types", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "1", detail_amount: 100, detail_sub_type: "CVFV", concept_type: "sale" } }),
+      nestedRow({ charge_info: { detail_id: "2", detail_amount: 50, detail_sub_type: "CFF", concept_type: "shipping" } })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const diag = payload.diagnostics;
+    expect(diag.concept_types_observed).toContain("sale");
+    expect(diag.concept_types_observed).toContain("shipping");
+    expect(diag.concept_types_observed).toHaveLength(2);
+  });
+  it("details_schema is exact and in correct order", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({ charge_info: { detail_id: "d1", detail_amount: 10 } })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    expect(payload.details_schema).toEqual([
+      "detail_id",
+      "detail_type",
+      "detail_sub_type",
+      "transaction_detail",
+      "detail_amount",
+      "currency_id",
+      "marketplace",
+      "concept_type",
+      "order_id",
+      "operation_id",
+      "item_id",
+      "item_title",
+      "shipping_id",
+      "pack_id",
+      "document_id",
+      "creation_date_time",
+      "sales_info_count",
+      "items_info_count"
+    ]);
+  });
+  it("empty details produces empty details array and zero summary with currency_totals and secondary blocks", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([], null, 0));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const details = payload.details;
+    expect(details).toHaveLength(0);
+    const summary = payload.summary;
+    expect(summary.detail_count).toBe(0);
+    expect(summary.order_count_detected).toBe(0);
+    expect(summary.item_count_detected).toBe(0);
+    expect(summary.currency_totals).toBeDefined();
+    expect(summary.currency_totals).toEqual({});
+    expect(payload.details_sales).toEqual([]);
+    expect(payload.details_items).toEqual([]);
+    expect(payload.details_sales_schema).toEqual(detailsSalesSchema);
+    expect(payload.details_items_schema).toEqual(detailsItemsSchema);
+    const diag = payload.diagnostics;
+    expect(diag.detail_sub_types_observed).toHaveLength(0);
+    expect(diag.marketplaces_observed).toHaveLength(0);
+    expect(diag.concept_types_observed).toHaveLength(0);
+  });
+  it("details_schema includes sales_info_count and items_info_count", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({
+        charge_info: { detail_id: "d1", detail_amount: 10 },
+        sales_info: [{ order_id: "O1" }, { order_id: "O2" }, { order_id: "O3" }],
+        items_info: [{ item_id: "I1" }, { item_id: "I2" }]
+      })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const details = payload.details;
+    const row = details[0];
+    expect(row[16]).toBe(3);
+    expect(row[17]).toBe(2);
+    expect(row[8]).toBe("O1");
+    expect(row[10]).toBe("I1");
+  });
+  it("multiple sales_info produces secondary details_sales block with all entries", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({
+        charge_info: { detail_id: "multi-sale", detail_amount: 100, detail_sub_type: "CVFV" },
+        sales_info: [
+          { order_id: "ORD-A", operation_id: "OP-A" },
+          { order_id: "ORD-B", operation_id: "OP-B" },
+          { order_id: "ORD-C" }
+        ]
+      })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    expect(payload.details_sales_schema).toEqual(detailsSalesSchema);
+    const salesRows = payload.details_sales;
+    expect(salesRows).toHaveLength(3);
+    for (const sr of salesRows) {
+      expect(sr[0]).toBe("multi-sale");
+    }
+    expect(salesRows[0][1]).toBe("ORD-A");
+    expect(salesRows[0][2]).toBe("OP-A");
+    expect(salesRows[1][1]).toBe("ORD-B");
+    expect(salesRows[1][2]).toBe("OP-B");
+    expect(salesRows[2][1]).toBe("ORD-C");
+    expect(salesRows[2][2]).toBeNull();
+    const summary = payload.summary;
+    expect(summary.order_count_detected).toBe(3);
+  });
+  it("multiple items_info produces secondary details_items block with all entries", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({
+        charge_info: { detail_id: "multi-item", detail_amount: 200, detail_sub_type: "CVFV" },
+        items_info: [
+          { item_id: "ITEM-1", item_title: "Producto A" },
+          { item_id: "ITEM-2", item_title: "Producto B" },
+          { item_id: "ITEM-3", item_title: "Producto C" },
+          { item_id: "ITEM-4" }
+        ]
+      })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    expect(payload.details_items_schema).toEqual(detailsItemsSchema);
+    const itemsRows = payload.details_items;
+    expect(itemsRows).toHaveLength(4);
+    for (const ir of itemsRows) {
+      expect(ir[0]).toBe("multi-item");
+    }
+    expect(itemsRows[0][1]).toBe("ITEM-1");
+    expect(itemsRows[0][2]).toBe("Producto A");
+    expect(itemsRows[3][1]).toBe("ITEM-4");
+    expect(itemsRows[3][2]).toBeNull();
+    const summary = payload.summary;
+    expect(summary.item_count_detected).toBe(4);
+  });
+  it("preserves null values at correct positions without column shift", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({
+        charge_info: {
+          detail_id: "null-test",
+          detail_amount: 0
+          // detail_type, detail_sub_type, transaction_detail, concept_type, creation_date_time all missing
+        },
+        currency_info: {},
+        // no currency_id
+        marketplace_info: {},
+        // no marketplace
+        sales_info: [],
+        // no sales
+        items_info: []
+        // no items
+        // document_id missing
+      })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const details = payload.details;
+    const row = details[0];
+    expect(row[0]).toBe("null-test");
+    expect(row[1]).toBeNull();
+    expect(row[2]).toBeNull();
+    expect(row[3]).toBeNull();
+    expect(row[4]).toBe(0);
+    expect(row[5]).toBeNull();
+    expect(row[6]).toBeNull();
+    expect(row[7]).toBeNull();
+    expect(row[8]).toBeNull();
+    expect(row[9]).toBeNull();
+    expect(row[10]).toBeNull();
+    expect(row[11]).toBeNull();
+    expect(row[12]).toBeNull();
+    expect(row[13]).toBeNull();
+    expect(row[14]).toBeNull();
+    expect(row[15]).toBeNull();
+    expect(row[16]).toBe(0);
+    expect(row[17]).toBe(0);
+    expect(row).toHaveLength(detailsSchema.length);
+    const salesRows = payload.details_sales;
+    const itemsRows = payload.details_items;
+    expect(salesRows).toHaveLength(0);
+    expect(itemsRows).toHaveLength(0);
+  });
+  it("secondary blocks populated even with single sale/item (contract stability)", async () => {
+    axiosGetMock.mockResolvedValue(mockApi([
+      nestedRow({
+        charge_info: { detail_id: "single-1", detail_amount: 50, detail_sub_type: "CVFV" },
+        sales_info: [{ order_id: "O-SINGLE" }],
+        items_info: [{ item_id: "I-SINGLE", item_title: "Solo" }]
+      })
+    ]));
+    const result = await meliGetBillingProvisionsSummaryHandler({
+      periodKey: "2026-06-01",
+      scope: "ml",
+      documentType: "BILL"
+    });
+    const payload = result.payload;
+    const salesRows = payload.details_sales;
+    const itemsRows = payload.details_items;
+    expect(salesRows).toHaveLength(1);
+    expect(itemsRows).toHaveLength(1);
+    expect(salesRows[0][0]).toBe("single-1");
+    expect(salesRows[0][1]).toBe("O-SINGLE");
+    expect(itemsRows[0][0]).toBe("single-1");
+    expect(itemsRows[0][1]).toBe("I-SINGLE");
+    expect(itemsRows[0][2]).toBe("Solo");
+  });
+});
+describe("meliGetBillingProvisionsSummarySchema validation", () => {
+  it("requires profileId and periodKey and scope", () => {
+    const result = meliGetBillingProvisionsSummarySchema.safeParse({});
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.length).toBeGreaterThanOrEqual(2);
+  });
+  it("accepts full valid payload including fromIdByScope", () => {
+    const result = meliGetBillingProvisionsSummarySchema.safeParse({
+      profileId: "my-profile",
+      periodKey: "2025-01-01",
+      scope: "all",
+      documentType: "CREDIT_NOTE",
+      detailType: "sale",
+      detailSubTypes: ["commission"],
+      orderIds: ["O123"],
+      itemIds: ["I456"],
+      fromIdByScope: { ml: "abc-123", mp: "def-456" }
+    });
+    expect(result.success).toBe(true);
+  });
+  it("rejects non-string values in fromIdByScope keys", () => {
+    const result = meliGetBillingProvisionsSummarySchema.safeParse({
+      profileId: "my-profile",
+      periodKey: "2025-01-01",
+      scope: "ml",
+      fromIdByScope: { ml: 123 }
+    });
+    expect(result.success).toBe(false);
+  });
+  it("accepts empty fromIdByScope", () => {
+    const result = meliGetBillingProvisionsSummarySchema.safeParse({
+      profileId: "my-profile",
+      periodKey: "2025-01-01",
+      scope: "ml",
+      fromIdByScope: {}
+    });
+    expect(result.success).toBe(true);
+  });
+});
+//# sourceMappingURL=mercadolibre-billing-provisions.test.js.map