@yoryoboy/bi-mcp 1.16.0 → 1.19.0

package/dist/src/tools/mercadolibre/search-product-ads-campaigns.js

@@ -0,0 +1,116 @@
+import { error, object } from "mcp-use/server";
+import { z } from "zod";
+import { formatMercadoLibreError, normalizeMercadoLibrePaging } from "../../services/mercadolibre/mercadolibre-api.js";
+import {
+  searchMercadoLibreProductAdsCampaigns
+} from "../../services/mercadolibre/mercadolibre-product-ads.js";
+import { stripNulls } from "../../utils/strip-payload.js";
+import {
+  mercadolibreProductAdsAdvertiserIdSchemaField,
+  mercadolibreProductAdsProfileIdSchemaField,
+  mercadolibreProductAdsSiteIdSchemaField,
+  resolveMercadoLibreProductAdsContext
+} from "./product-ads-helpers.js";
+import { mercadoLibreDateRegex } from "./helpers.js";
+import { resolveMercadoLibreProfileOrSelection } from "./profile-resolution.js";
+const CAMPAIGNS_PAGE_LIMIT = 50;
+function isValidCalendarDate(value) {
+  const [year, month, day] = value.split("-").map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+const meliSearchProductAdsCampaignsSchema = z.object({
+  profileId: mercadolibreProductAdsProfileIdSchemaField,
+  siteId: mercadolibreProductAdsSiteIdSchemaField,
+  advertiserId: mercadolibreProductAdsAdvertiserIdSchemaField,
+  dateFrom: z.string().regex(mercadoLibreDateRegex).describe("Start date in YYYY-MM-DD format for the Product Ads window."),
+  dateTo: z.string().regex(mercadoLibreDateRegex).describe("End date in YYYY-MM-DD format for the Product Ads window."),
+  mode: z.literal("page").default("page").describe("Page-only search mode."),
+  limit: z.number().int().min(1).max(100).optional().describe("Requested page size."),
+  offset: z.number().int().min(0).optional().describe("Requested page offset.")
+}).superRefine((value, ctx) => {
+  for (const field of ["dateFrom", "dateTo"]) {
+    if (!isValidCalendarDate(value[field])) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: [field], message: `${field} must be a valid calendar date.` });
+    }
+  }
+  if (value.dateFrom > value.dateTo) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["dateTo"], message: "dateTo must be on or after dateFrom." });
+  }
+});
+async function meliSearchProductAdsCampaignsHandler(params) {
+  try {
+    const validation = meliSearchProductAdsCampaignsSchema.safeParse(params);
+    if (!validation.success) {
+      return error(validation.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+    }
+    params = validation.data;
+    const profileResolution = await resolveMercadoLibreProfileOrSelection(params.profileId);
+    if (!profileResolution.ok) return profileResolution.response;
+    const profileId = profileResolution.value.profileId;
+    const siteId = params.siteId?.trim();
+    const advertiserId = params.advertiserId?.trim();
+    const directContext = siteId && advertiserId ? { siteId, advertiserId, resolutionMode: "explicit" } : await resolveMercadoLibreProductAdsContext({ profileId, siteId, advertiserId });
+    if ("ok" in directContext && !directContext.ok) return directContext.response;
+    const context = "ok" in directContext ? directContext.value : directContext;
+    const requestedLimit = params.limit ?? CAMPAIGNS_PAGE_LIMIT;
+    const requestedOffset = params.offset ?? 0;
+    const logObservation = (observation) => {
+      console.info(JSON.stringify({
+        profile_id: profileId,
+        site_id: context.siteId,
+        advertiser_id: context.advertiserId,
+        ...observation,
+        event: "mercadolibre.product_ads.campaigns.discovery"
+      }));
+    };
+    const page = await searchMercadoLibreProductAdsCampaigns(
+      profileId,
+      {
+        siteId: context.siteId,
+        advertiserId: context.advertiserId,
+        dateFrom: params.dateFrom,
+        dateTo: params.dateTo,
+        limit: requestedLimit,
+        offset: requestedOffset
+      },
+      { onObservation: logObservation }
+    );
+    const paging = normalizeMercadoLibrePaging(page.paging);
+    const nextOffset = paging.offset + paging.limit;
+    const hasMore = paging.limit > 0 && nextOffset < paging.total;
+    return object({
+      ...stripNulls({
+        profile_id: profileId,
+        site_id: context.siteId,
+        advertiser_id: context.advertiserId,
+        product: "PADS",
+        mode: "page",
+        paging: page.paging,
+        metadata: {
+          entity: "campaigns",
+          fetch_mode: "page",
+          total: paging.total,
+          requested_limit: params.limit,
+          effective_limit: paging.limit,
+          requested_offset: requestedOffset,
+          effective_offset: paging.offset,
+          returned: page.results.length,
+          has_more: hasMore,
+          next_offset: hasMore ? nextOffset : void 0,
+          continuation: hasMore ? `Re-run meli_search_product_ads_campaigns with mode=page and offset=${nextOffset}, limit=${paging.limit} to continue.` : "No more Product Ads campaign pages remain for this query.",
+          ad_groups_hint: "Use each returned campaign id as campaign context for meli_search_product_ads_ad_groups by passing filters=[{ field: 'campaigns', value: '<campaign id>' }]."
+        },
+        context_resolution: { mode: context.resolutionMode, advertiser_id: context.advertiserId, advertiser_site_id: context.siteId }
+      }),
+      results: page.results.map((row) => stripNulls(row))
+    });
+  } catch (err) {
+    return error(formatMercadoLibreError(err, "Failed to search MercadoLibre Product Ads campaigns"));
+  }
+}
+export {
+  meliSearchProductAdsCampaignsHandler,
+  meliSearchProductAdsCampaignsSchema
+};
+//# sourceMappingURL=search-product-ads-campaigns.js.map

package/dist/src/tools/mercadolibre/search-product-ads-campaigns.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/tools/mercadolibre/search-product-ads-campaigns.ts"],
+  "sourcesContent": ["import { error, object } from \"mcp-use/server\";\nimport { z } from \"zod\";\n\nimport { formatMercadoLibreError, normalizeMercadoLibrePaging } from \"../../services/mercadolibre/mercadolibre-api.js\";\nimport {\n  searchMercadoLibreProductAdsCampaigns,\n  type MercadoLibreProductAdsCampaignsObservation,\n} from \"../../services/mercadolibre/mercadolibre-product-ads.js\";\nimport { stripNulls } from \"../../utils/strip-payload.js\";\nimport {\n  mercadolibreProductAdsAdvertiserIdSchemaField,\n  mercadolibreProductAdsProfileIdSchemaField,\n  mercadolibreProductAdsSiteIdSchemaField,\n  resolveMercadoLibreProductAdsContext,\n} from \"./product-ads-helpers.js\";\nimport { mercadoLibreDateRegex } from \"./helpers.js\";\nimport { resolveMercadoLibreProfileOrSelection } from \"./profile-resolution.js\";\n\nconst CAMPAIGNS_PAGE_LIMIT = 50;\n\nfunction isValidCalendarDate(value: string) {\n  const [year, month, day] = value.split(\"-\").map(Number);\n  const date = new Date(Date.UTC(year, month - 1, day));\n  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;\n}\n\nexport const meliSearchProductAdsCampaignsSchema = z\n  .object({\n    profileId: mercadolibreProductAdsProfileIdSchemaField,\n    siteId: mercadolibreProductAdsSiteIdSchemaField,\n    advertiserId: mercadolibreProductAdsAdvertiserIdSchemaField,\n    dateFrom: z.string().regex(mercadoLibreDateRegex).describe(\"Start date in YYYY-MM-DD format for the Product Ads window.\"),\n    dateTo: z.string().regex(mercadoLibreDateRegex).describe(\"End date in YYYY-MM-DD format for the Product Ads window.\"),\n    mode: z.literal(\"page\").default(\"page\").describe(\"Page-only search mode.\"),\n    limit: z.number().int().min(1).max(100).optional().describe(\"Requested page size.\"),\n    offset: z.number().int().min(0).optional().describe(\"Requested page offset.\"),\n  })\n  .superRefine((value, ctx) => {\n    for (const field of [\"dateFrom\", \"dateTo\"] as const) {\n      if (!isValidCalendarDate(value[field])) {\n        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [field], message: `${field} must be a valid calendar date.` });\n      }\n    }\n    if (value.dateFrom > value.dateTo) {\n      ctx.addIssue({ code: z.ZodIssueCode.custom, path: [\"dateTo\"], message: \"dateTo must be on or after dateFrom.\" });\n    }\n  });\n\nexport async function meliSearchProductAdsCampaignsHandler(\n  params: z.infer<typeof meliSearchProductAdsCampaignsSchema>\n) {\n  try {\n    const validation = meliSearchProductAdsCampaignsSchema.safeParse(params);\n    if (!validation.success) {\n      return error(validation.error.issues.map((issue) => `${issue.path.join(\".\")}: ${issue.message}`).join(\"; \"));\n    }\n    params = validation.data;\n    const profileResolution = await resolveMercadoLibreProfileOrSelection(params.profileId);\n    if (!profileResolution.ok) return profileResolution.response;\n    const profileId = profileResolution.value.profileId;\n    const siteId = params.siteId?.trim();\n    const advertiserId = params.advertiserId?.trim();\n    const directContext = siteId && advertiserId ? { siteId, advertiserId, resolutionMode: \"explicit\" as const } : await resolveMercadoLibreProductAdsContext({ profileId, siteId, advertiserId });\n    if (\"ok\" in directContext && !directContext.ok) return directContext.response;\n    const context = \"ok\" in directContext ? directContext.value : directContext;\n    const requestedLimit = params.limit ?? CAMPAIGNS_PAGE_LIMIT;\n    const requestedOffset = params.offset ?? 0;\n    const logObservation = (observation: MercadoLibreProductAdsCampaignsObservation) => {\n      console.info(JSON.stringify({\n        profile_id: profileId,\n        site_id: context.siteId,\n        advertiser_id: context.advertiserId,\n        ...observation,\n        event: \"mercadolibre.product_ads.campaigns.discovery\",\n      }));\n    };\n    const page = await searchMercadoLibreProductAdsCampaigns(\n      profileId,\n      {\n        siteId: context.siteId, advertiserId: context.advertiserId, dateFrom: params.dateFrom, dateTo: params.dateTo,\n        limit: requestedLimit, offset: requestedOffset,\n      },\n      { onObservation: logObservation }\n    );\n    const paging = normalizeMercadoLibrePaging(page.paging);\n    const nextOffset = paging.offset + paging.limit;\n    const hasMore = paging.limit > 0 && nextOffset < paging.total;\n    return object({\n      ...stripNulls({\n        profile_id: profileId, site_id: context.siteId, advertiser_id: context.advertiserId, product: \"PADS\", mode: \"page\", paging: page.paging,\n        metadata: {\n          entity: \"campaigns\", fetch_mode: \"page\", total: paging.total, requested_limit: params.limit, effective_limit: paging.limit,\n          requested_offset: requestedOffset, effective_offset: paging.offset, returned: page.results.length, has_more: hasMore,\n          next_offset: hasMore ? nextOffset : undefined,\n          continuation: hasMore\n            ? `Re-run meli_search_product_ads_campaigns with mode=page and offset=${nextOffset}, limit=${paging.limit} to continue.`\n            : \"No more Product Ads campaign pages remain for this query.\",\n          ad_groups_hint: \"Use each returned campaign id as campaign context for meli_search_product_ads_ad_groups by passing filters=[{ field: 'campaigns', value: '<campaign id>' }].\",\n        },\n        context_resolution: { mode: context.resolutionMode, advertiser_id: context.advertiserId, advertiser_site_id: context.siteId },\n      }),\n      results: page.results.map((row) => stripNulls(row)),\n    });\n  } catch (err) {\n    return error(formatMercadoLibreError(err, \"Failed to search MercadoLibre Product Ads campaigns\"));\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/src/tools/mercadolibre/validate-connection.js

@@ -1,14 +1,29 @@
 import { error, object } from "mcp-use/server";
 import { z } from "zod";
 import { getMercadoLibreConnectionRow } from "../../config/mercadolibre-profile-store.js";
-import { getMercadoLibreAccessForProfile } from "../../config/mercadolibre.js";
-import { getMercadoLibreUsersMe, formatMercadoLibreError } from "../../services/mercadolibre/mercadolibre-api.js";
+import { decryptSecret } from "../../config/vtex-crypto.js";
+import {
+  formatMercadoLibreError,
+  getMercadoLibreUsersMeWithAccessToken
+} from "../../services/mercadolibre/mercadolibre-api.js";
 import { stripNulls } from "../../utils/strip-payload.js";
 import { resolveMercadoLibreProfileOrSelection } from "./profile-resolution.js";
 import { mercadolibreProfileIdSchemaField } from "./write-helpers.js";
 const meliValidateConnectionSchema = z.object({
   profileId: mercadolibreProfileIdSchemaField
 });
+function credentialMaintenanceRequired(profileId, reason, expiresAt) {
+  return object(
+    stripNulls({
+      profile_id: profileId,
+      observation_only: true,
+      validation_status: "credential_maintenance_required",
+      credential_status: reason,
+      expires_at: expiresAt?.toISOString(),
+      message: "No usable unexpired stored access token is available. Credential maintenance or refresh is required; this observation-only validation did not refresh tokens or update connection state."
+    })
+  );
+}
 async function meliValidateConnectionHandler(params) {
   try {
     const profileResolution = await resolveMercadoLibreProfileOrSelection(params.profileId);
@@ -16,21 +31,34 @@ async function meliValidateConnectionHandler(params) {
       return profileResolution.response;
     }
     const profileId = profileResolution.value.profileId;
-    const before = await getMercadoLibreConnectionRow(profileId);
-    const access = await getMercadoLibreAccessForProfile(profileId);
-    const account = await getMercadoLibreUsersMe(profileId);
-    const after = await getMercadoLibreConnectionRow(profileId);
-    const refreshed = before?.expiresAt?.toISOString() !== after?.expiresAt?.toISOString() || before?.encryptedAccessToken !== after?.encryptedAccessToken;
+    const connection = await getMercadoLibreConnectionRow(profileId);
+    if (!connection) {
+      return credentialMaintenanceRequired(profileId, "connection_not_found");
+    }
+    if (connection.status === "disabled") {
+      return credentialMaintenanceRequired(profileId, "connection_disabled", connection.expiresAt);
+    }
+    if (!connection.encryptedAccessToken) {
+      return credentialMaintenanceRequired(profileId, "token_missing", connection.expiresAt);
+    }
+    if (!connection.expiresAt) {
+      return credentialMaintenanceRequired(profileId, "expiry_unknown");
+    }
+    if (connection.expiresAt.getTime() <= Date.now()) {
+      return credentialMaintenanceRequired(profileId, "token_expired", connection.expiresAt);
+    }
+    const accessToken = decryptSecret(connection.encryptedAccessToken);
+    const account = await getMercadoLibreUsersMeWithAccessToken(accessToken);
     return object(
       stripNulls({
         profile_id: profileId,
-        validation_status: after?.status ?? "active",
-        refreshed,
-        seller_id: access.sellerId,
+        observation_only: true,
+        validation_status: "valid",
+        seller_id: connection.sellerId,
         account_id: account.id,
         nickname: account.nickname,
-        expires_at: access.expiresAt,
-        scopes: access.scopes
+        expires_at: connection.expiresAt.toISOString(),
+        scopes: connection.scopes
       })
     );
   } catch (err) {

package/dist/src/tools/mercadolibre/validate-connection.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/tools/mercadolibre/validate-connection.ts"],
-  "sourcesContent": ["import { error, object } from \"mcp-use/server\";\nimport { z } from \"zod\";\n\nimport { getMercadoLibreConnectionRow } from \"../../config/mercadolibre-profile-store.js\";\nimport { getMercadoLibreAccessForProfile } from \"../../config/mercadolibre.js\";\nimport { getMercadoLibreUsersMe, formatMercadoLibreError } from \"../../services/mercadolibre/mercadolibre-api.js\";\nimport { stripNulls } from \"../../utils/strip-payload.js\";\nimport { resolveMercadoLibreProfileOrSelection } from \"./profile-resolution.js\";\nimport { mercadolibreProfileIdSchemaField } from \"./write-helpers.js\";\n\nexport const meliValidateConnectionSchema = z.object({\n  profileId: mercadolibreProfileIdSchemaField,\n});\n\nexport async function meliValidateConnectionHandler(\n  params: z.infer<typeof meliValidateConnectionSchema>\n) {\n  try {\n    const profileResolution = await resolveMercadoLibreProfileOrSelection(params.profileId);\n    if (!profileResolution.ok) {\n      return profileResolution.response;\n    }\n\n    const profileId = profileResolution.value.profileId;\n    const before = await getMercadoLibreConnectionRow(profileId);\n    const access = await getMercadoLibreAccessForProfile(profileId);\n    const account = await getMercadoLibreUsersMe(profileId);\n    const after = await getMercadoLibreConnectionRow(profileId);\n\n    const refreshed =\n      before?.expiresAt?.toISOString() !== after?.expiresAt?.toISOString() ||\n      before?.encryptedAccessToken !== after?.encryptedAccessToken;\n\n    return object(\n      stripNulls({\n        profile_id: profileId,\n        validation_status: after?.status ?? \"active\",\n        refreshed,\n        seller_id: access.sellerId,\n        account_id: account.id,\n        nickname: account.nickname,\n        expires_at: access.expiresAt,\n        scopes: access.scopes,\n      })\n    );\n  } catch (err) {\n    return error(formatMercadoLibreError(err, \"Failed to validate MercadoLibre connection\"));\n  }\n}\n"],
-  "mappings": "AAAA,SAAS,OAAO,cAAc;AAC9B,SAAS,SAAS;AAElB,SAAS,oCAAoC;AAC7C,SAAS,uCAAuC;AAChD,SAAS,wBAAwB,+BAA+B;AAChE,SAAS,kBAAkB;AAC3B,SAAS,6CAA6C;AACtD,SAAS,wCAAwC;AAE1C,MAAM,+BAA+B,EAAE,OAAO;AAAA,EACnD,WAAW;AACb,CAAC;AAED,eAAsB,8BACpB,QACA;AACA,MAAI;AACF,UAAM,oBAAoB,MAAM,sCAAsC,OAAO,SAAS;AACtF,QAAI,CAAC,kBAAkB,IAAI;AACzB,aAAO,kBAAkB;AAAA,IAC3B;AAEA,UAAM,YAAY,kBAAkB,MAAM;AAC1C,UAAM,SAAS,MAAM,6BAA6B,SAAS;AAC3D,UAAM,SAAS,MAAM,gCAAgC,SAAS;AAC9D,UAAM,UAAU,MAAM,uBAAuB,SAAS;AACtD,UAAM,QAAQ,MAAM,6BAA6B,SAAS;AAE1D,UAAM,YACJ,QAAQ,WAAW,YAAY,MAAM,OAAO,WAAW,YAAY,KACnE,QAAQ,yBAAyB,OAAO;AAE1C,WAAO;AAAA,MACL,WAAW;AAAA,QACT,YAAY;AAAA,QACZ,mBAAmB,OAAO,UAAU;AAAA,QACpC;AAAA,QACA,WAAW,OAAO;AAAA,QAClB,YAAY,QAAQ;AAAA,QACpB,UAAU,QAAQ;AAAA,QAClB,YAAY,OAAO;AAAA,QACnB,QAAQ,OAAO;AAAA,MACjB,CAAC;AAAA,IACH;AAAA,EACF,SAAS,KAAK;AACZ,WAAO,MAAM,wBAAwB,KAAK,4CAA4C,CAAC;AAAA,EACzF;AACF;",
+  "sourcesContent": ["import { error, object } from \"mcp-use/server\";\nimport { z } from \"zod\";\n\nimport { getMercadoLibreConnectionRow } from \"../../config/mercadolibre-profile-store.js\";\nimport { decryptSecret } from \"../../config/vtex-crypto.js\";\nimport {\n  formatMercadoLibreError,\n  getMercadoLibreUsersMeWithAccessToken,\n} from \"../../services/mercadolibre/mercadolibre-api.js\";\nimport { stripNulls } from \"../../utils/strip-payload.js\";\nimport { resolveMercadoLibreProfileOrSelection } from \"./profile-resolution.js\";\nimport { mercadolibreProfileIdSchemaField } from \"./write-helpers.js\";\n\nexport const meliValidateConnectionSchema = z.object({\n  profileId: mercadolibreProfileIdSchemaField,\n});\n\nfunction credentialMaintenanceRequired(\n  profileId: string,\n  reason: \"connection_not_found\" | \"connection_disabled\" | \"token_missing\" | \"token_expired\" | \"expiry_unknown\",\n  expiresAt?: Date | null\n) {\n  return object(\n    stripNulls({\n      profile_id: profileId,\n      observation_only: true,\n      validation_status: \"credential_maintenance_required\",\n      credential_status: reason,\n      expires_at: expiresAt?.toISOString(),\n      message:\n        \"No usable unexpired stored access token is available. Credential maintenance or refresh is required; this observation-only validation did not refresh tokens or update connection state.\",\n    })\n  );\n}\n\nexport async function meliValidateConnectionHandler(\n  params: z.infer<typeof meliValidateConnectionSchema>\n) {\n  try {\n    const profileResolution = await resolveMercadoLibreProfileOrSelection(params.profileId);\n    if (!profileResolution.ok) {\n      return profileResolution.response;\n    }\n\n    const profileId = profileResolution.value.profileId;\n    const connection = await getMercadoLibreConnectionRow(profileId);\n\n    if (!connection) {\n      return credentialMaintenanceRequired(profileId, \"connection_not_found\");\n    }\n\n    if (connection.status === \"disabled\") {\n      return credentialMaintenanceRequired(profileId, \"connection_disabled\", connection.expiresAt);\n    }\n\n    if (!connection.encryptedAccessToken) {\n      return credentialMaintenanceRequired(profileId, \"token_missing\", connection.expiresAt);\n    }\n\n    if (!connection.expiresAt) {\n      return credentialMaintenanceRequired(profileId, \"expiry_unknown\");\n    }\n\n    if (connection.expiresAt.getTime() <= Date.now()) {\n      return credentialMaintenanceRequired(profileId, \"token_expired\", connection.expiresAt);\n    }\n\n    const accessToken = decryptSecret(connection.encryptedAccessToken);\n    const account = await getMercadoLibreUsersMeWithAccessToken(accessToken);\n\n    return object(\n      stripNulls({\n        profile_id: profileId,\n        observation_only: true,\n        validation_status: \"valid\",\n        seller_id: connection.sellerId,\n        account_id: account.id,\n        nickname: account.nickname,\n        expires_at: connection.expiresAt.toISOString(),\n        scopes: connection.scopes,\n      })\n    );\n  } catch (err) {\n    return error(formatMercadoLibreError(err, \"Failed to validate MercadoLibre connection\"));\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,OAAO,cAAc;AAC9B,SAAS,SAAS;AAElB,SAAS,oCAAoC;AAC7C,SAAS,qBAAqB;AAC9B;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP,SAAS,kBAAkB;AAC3B,SAAS,6CAA6C;AACtD,SAAS,wCAAwC;AAE1C,MAAM,+BAA+B,EAAE,OAAO;AAAA,EACnD,WAAW;AACb,CAAC;AAED,SAAS,8BACP,WACA,QACA,WACA;AACA,SAAO;AAAA,IACL,WAAW;AAAA,MACT,YAAY;AAAA,MACZ,kBAAkB;AAAA,MAClB,mBAAmB;AAAA,MACnB,mBAAmB;AAAA,MACnB,YAAY,WAAW,YAAY;AAAA,MACnC,SACE;AAAA,IACJ,CAAC;AAAA,EACH;AACF;AAEA,eAAsB,8BACpB,QACA;AACA,MAAI;AACF,UAAM,oBAAoB,MAAM,sCAAsC,OAAO,SAAS;AACtF,QAAI,CAAC,kBAAkB,IAAI;AACzB,aAAO,kBAAkB;AAAA,IAC3B;AAEA,UAAM,YAAY,kBAAkB,MAAM;AAC1C,UAAM,aAAa,MAAM,6BAA6B,SAAS;AAE/D,QAAI,CAAC,YAAY;AACf,aAAO,8BAA8B,WAAW,sBAAsB;AAAA,IACxE;AAEA,QAAI,WAAW,WAAW,YAAY;AACpC,aAAO,8BAA8B,WAAW,uBAAuB,WAAW,SAAS;AAAA,IAC7F;AAEA,QAAI,CAAC,WAAW,sBAAsB;AACpC,aAAO,8BAA8B,WAAW,iBAAiB,WAAW,SAAS;AAAA,IACvF;AAEA,QAAI,CAAC,WAAW,WAAW;AACzB,aAAO,8BAA8B,WAAW,gBAAgB;AAAA,IAClE;AAEA,QAAI,WAAW,UAAU,QAAQ,KAAK,KAAK,IAAI,GAAG;AAChD,aAAO,8BAA8B,WAAW,iBAAiB,WAAW,SAAS;AAAA,IACvF;AAEA,UAAM,cAAc,cAAc,WAAW,oBAAoB;AACjE,UAAM,UAAU,MAAM,sCAAsC,WAAW;AAEvE,WAAO;AAAA,MACL,WAAW;AAAA,QACT,YAAY;AAAA,QACZ,kBAAkB;AAAA,QAClB,mBAAmB;AAAA,QACnB,WAAW,WAAW;AAAA,QACtB,YAAY,QAAQ;AAAA,QACpB,UAAU,QAAQ;AAAA,QAClB,YAAY,WAAW,UAAU,YAAY;AAAA,QAC7C,QAAQ,WAAW;AAAA,MACrB,CAAC;AAAA,IACH;AAAA,EACF,SAAS,KAAK;AACZ,WAAO,MAAM,wBAAwB,KAAK,4CAA4C,CAAC;AAAA,EACzF;AACF;",
   "names": []
 }

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

@@ -28,10 +28,22 @@ vi.mock("../../src/tools/mercadolibre/profile-resolution.js", () => ({
   resolveMercadoLibreProfileOrSelection: resolveProfileMock
 }));
 import {
+  buildMercadoLibreBillingOrderDetailsPath,
+  clampMercadoLibreBillingOrderIdsBatchSize,
   getMercadoLibreBillingProvisionPage,
   getMercadoLibreBillingProvisions,
+  getMercadoLibreBillingProvisionsByOrder,
   scopeToGroupPath
 } from "../../src/services/mercadolibre/mercadolibre-billing.js";
+import {
+  meliGetBillingProvisionsByOrderHandler,
+  meliGetBillingProvisionsByOrderSchema,
+  ordersSchema,
+  paymentInfoSchema,
+  detailsSchema as byOrderDetailsSchema,
+  detailsSalesSchema as byOrderDetailsSalesSchema,
+  detailsItemsSchema as byOrderDetailsItemsSchema
+} from "../../src/tools/mercadolibre/get-billing-provisions-by-order.js";
 import {
   meliGetBillingProvisionsSummaryHandler,
   meliGetBillingProvisionsSummarySchema,
@@ -80,6 +92,16 @@ describe("scopeToGroupPath", () => {
     expect(scopeToGroupPath("full")).toBe("ML/full");
   });
 });
+describe("Mercado Libre billing path helpers", () => {
+  it("keeps the by-order route fixed to the official ML path", () => {
+    expect(buildMercadoLibreBillingOrderDetailsPath()).toBe("/billing/integration/group/ML/order/details");
+  });
+  it("caps by-order batches at 60 order IDs per request", () => {
+    expect(clampMercadoLibreBillingOrderIdsBatchSize(61)).toBe(60);
+    expect(clampMercadoLibreBillingOrderIdsBatchSize(60)).toBe(60);
+    expect(clampMercadoLibreBillingOrderIdsBatchSize(0)).toBe(1);
+  });
+});
 describe("getMercadoLibreBillingProvisionPage", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -145,6 +167,7 @@ describe("getMercadoLibreBillingProvisionPage", () => {
     expect(p.marketplace_type).toBe("classic");
     expect(p.order_ids).toBe("O1");
     expect(p.item_ids).toBe("I1");
+    expect(p.site_id).toBeUndefined();
   });
   it("reads flat total/limit from real MELI envelope (no paging nesting)", async () => {
     axiosGetMock.mockResolvedValue({
@@ -235,6 +258,361 @@ describe("getMercadoLibreBillingProvisions", () => {
     expect(result.coverage_complete).toBe(true);
   });
 });
+describe("meliGetBillingProvisionsByOrderHandler", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(resolveProfileMock).mockResolvedValue({
+      ok: true,
+      value: { profileId: "meli-profile-1" }
+    });
+  });
+  it("requires profileId and at least one orderId", () => {
+    expect(
+      () => meliGetBillingProvisionsByOrderSchema.parse({ orderIds: ["O1"] })
+    ).toThrow();
+    expect(
+      () => meliGetBillingProvisionsByOrderSchema.parse({ profileId: "profile-1", orderIds: ["O1"] })
+    ).not.toThrow();
+  });
+  function officialOrderRow(overrides = {}) {
+    const paymentInfo = overrides.payment_info ?? {};
+    const details = overrides.details;
+    return {
+      order_id: overrides.order_id ?? `ORD-${Math.random().toString(36).slice(2, 8)}`,
+      sale_fee: overrides.sale_fee ?? 12.34,
+      document_id: overrides.document_id ?? "DOC-1",
+      currency_id: overrides.currency_id ?? "ARS",
+      marketplace: overrides.marketplace ?? "MELI",
+      payment_info: {
+        payment_id: paymentInfo.payment_id ?? "PAY-1",
+        payment_type: paymentInfo.payment_type ?? "credit_card",
+        payment_method_id: paymentInfo.payment_method_id ?? "visa",
+        installments: Object.hasOwn(paymentInfo, "installments") ? paymentInfo.installments : 1,
+        transaction_amount: Object.hasOwn(paymentInfo, "transaction_amount") ? paymentInfo.transaction_amount : 100,
+        total_paid_amount: Object.hasOwn(paymentInfo, "total_paid_amount") ? paymentInfo.total_paid_amount : 100,
+        shipping_cost: Object.hasOwn(paymentInfo, "shipping_cost") ? paymentInfo.shipping_cost : 0,
+        coupon_amount: Object.hasOwn(paymentInfo, "coupon_amount") ? paymentInfo.coupon_amount : 0,
+        status: paymentInfo.status ?? "approved",
+        status_detail: paymentInfo.status_detail ?? "accredited",
+        ...paymentInfo
+      },
+      details: details ?? [
+        {
+          charge_info: {
+            detail_id: "detail-1",
+            detail_type: "CHARGE",
+            detail_sub_type: "CVFF",
+            transaction_detail: "Costo por unidad vendida",
+            detail_amount: 12.34,
+            concept_type: "SALE_FEE",
+            operation_id: "OP-1",
+            shipping_id: "SHIP-1",
+            pack_id: "PACK-1",
+            inventory_id: "INV-1"
+          },
+          currency_info: { currency_id: "ARS" },
+          sales_info: [
+            {
+              order_id: overrides.order_id ?? "ORD-1",
+              operation_id: "OP-1",
+              sale_date_time: "2026-06-01T10:00:00Z",
+              payer_nickname: "buyer-1",
+              transaction_amount: 100
+            }
+          ],
+          items_info: [
+            {
+              item_id: "ITEM-1",
+              item_title: "Producto 1",
+              item_amount: 1,
+              item_price: 100,
+              item_kit_id: null,
+              store_id: "STORE-1",
+              order_id: overrides.order_id ?? "ORD-1",
+              fees_added_in_publication: "No"
+            }
+          ]
+        }
+      ],
+      ...overrides
+    };
+  }
+  it("uses the official order details endpoint without site_id and chunks at 60 IDs", async () => {
+    axiosGetMock.mockResolvedValueOnce({ data: { results: [officialOrderRow({ order_id: "O1" })], total: 1, limit: 60 } }).mockResolvedValueOnce({ data: { results: [officialOrderRow({ order_id: "O61" })], total: 1, limit: 1 } });
+    const orderIds = Array.from({ length: 61 }, (_, index) => `O${index + 1}`);
+    const result = await getMercadoLibreBillingProvisionsByOrder("profile-1", {
+      orderIds
+    });
+    expect(axiosGetMock).toHaveBeenCalledTimes(2);
+    expect(axiosGetMock.mock.calls[0][0]).toBe("/billing/integration/group/ML/order/details");
+    expect(axiosGetMock.mock.calls[0][1]).toEqual({ params: { order_ids: orderIds.slice(0, 60).join(",") } });
+    expect(axiosGetMock.mock.calls[1][1]).toEqual({ params: { order_ids: ["O61"].join(",") } });
+    expect(result.chunks_total).toBe(2);
+    expect(result.chunks_succeeded).toBe(2);
+    expect(result.chunks_failed).toBe(0);
+    expect(result.order_ids_found).toEqual(["O1", "O61"]);
+    expect(result.order_ids_not_found).toEqual(orderIds.filter((id) => !["O1", "O61"].includes(id)));
+  });
+  it("handles 600 order IDs by chunking internally into 60-ID requests", async () => {
+    axiosGetMock.mockResolvedValue({
+      data: {
+        results: [],
+        total: 0,
+        limit: 60
+      }
+    });
+    const orderIds = Array.from({ length: 600 }, (_, index) => `O${index + 1}`);
+    const result = await getMercadoLibreBillingProvisionsByOrder("profile-1", {
+      orderIds
+    });
+    expect(axiosGetMock).toHaveBeenCalledTimes(10);
+    expect(result.chunks_total).toBe(10);
+    expect(result.chunks_succeeded).toBe(10);
+    expect(result.chunks_failed).toBe(0);
+    expect(result.order_ids_requested).toEqual(orderIds);
+    expect(result.order_ids_not_found).toEqual(orderIds);
+  });
+  it("deduplicates found order ids from the official per-order payload", async () => {
+    axiosGetMock.mockResolvedValue({
+      data: {
+        results: [
+          officialOrderRow({
+            order_id: "O1",
+            details: [
+              {
+                detail_id: "detail-1",
+                sales_info: [
+                  { order_id: "O1", operation_id: "OP-1", sale_date_time: "2026-06-01T10:00:00Z", payer_nickname: "buyer-1", transaction_amount: 100 }
+                ],
+                items_info: [
+                  { item_id: "ITEM-1", item_title: "Producto 1", item_amount: 1, item_price: 100, order_id: "O1" }
+                ]
+              }
+            ]
+          })
+        ],
+        total: 1,
+        limit: 60
+      }
+    });
+    const result = await getMercadoLibreBillingProvisionsByOrder("profile-1", {
+      orderIds: ["O1", "O2"]
+    });
+    expect(result.results).toHaveLength(1);
+    expect(result.order_ids_found).toEqual(["O1"]);
+    expect(result.order_ids_not_found).toEqual(["O2"]);
+    expect(result.coverage_complete).toBe(true);
+  });
+  it("returns the compact order, payment and detail blocks from the official payload", async () => {
+    axiosGetMock.mockResolvedValue({
+      data: {
+        results: [officialOrderRow({ order_id: "O1", sale_fee: null })],
+        total: 1,
+        limit: 60
+      }
+    });
+    const result = await meliGetBillingProvisionsByOrderHandler({
+      profileId: "profile-1",
+      orderIds: ["O1"]
+    });
+    expect(result).toHaveProperty("kind", "object");
+    const payload = result.payload;
+    expect(payload.profile_id).toBe("meli-profile-1");
+    expect(payload.endpoint).toBe("/billing/integration/group/ML/order/details");
+    expect(payload.orders_schema).toEqual(ordersSchema);
+    expect(payload.payment_info_schema).toEqual(paymentInfoSchema);
+    expect(payload.details_schema).toEqual(byOrderDetailsSchema);
+    expect(payload.details_sales_schema).toEqual(byOrderDetailsSalesSchema);
+    expect(payload.details_items_schema).toEqual(byOrderDetailsItemsSchema);
+    const orders = payload.orders;
+    const paymentInfo = payload.payment_info;
+    const details = payload.details;
+    const detailsSales = payload.details_sales;
+    const detailsItems = payload.details_items;
+    expect(orders).toHaveLength(1);
+    expect(orders[0][0]).toBe("O1");
+    expect(orders[0][1]).toBeNull();
+    expect(paymentInfo).toHaveLength(1);
+    expect(paymentInfo[0][0]).toBe("O1");
+    expect(details).toHaveLength(1);
+    expect(details[0][0]).toBe("O1");
+    expect(details[0]).toEqual([
+      "O1",
+      "detail-1",
+      "CHARGE",
+      "CVFF",
+      "Costo por unidad vendida",
+      12.34,
+      "ARS",
+      "SALE_FEE",
+      "OP-1",
+      "SHIP-1",
+      "PACK-1",
+      "INV-1"
+    ]);
+    expect(detailsSales).toHaveLength(1);
+    expect(detailsSales[0][4]).toBeNull();
+    expect(detailsItems).toHaveLength(1);
+    expect(detailsItems[0]).toHaveLength(byOrderDetailsItemsSchema.length);
+    expect(detailsItems[0][8]).toBe("No");
+    const metadata = payload.metadata;
+    expect(metadata.order_ids_requested).toEqual(["O1"]);
+    expect(metadata.order_ids_found).toEqual(["O1"]);
+    expect(metadata.order_ids_not_found).toEqual([]);
+    expect(metadata.coverage_complete).toBe(true);
+  });
+  it("projects CVFN from nested charge_info with amount, currency and sales order join", async () => {
+    axiosGetMock.mockResolvedValue({
+      data: {
+        results: [officialOrderRow({
+          order_id: null,
+          currency_id: null,
+          details: [{
+            charge_info: {
+              detail_id: "detail-cvfn",
+              detail_type: "CHARGE",
+              detail_sub_type: "CVFN",
+              transaction_detail: "Costo por ofrecer cuotas",
+              detail_amount: -321.45,
+              concept_type: "FINANCING_FEE"
+            },
+            currency_info: { currency_id: "ARS" },
+            sales_info: [{ order_id: "O-CVFN", payer_nickname: "must-not-leak" }]
+          }]
+        })]
+      }
+    });
+    const result = await meliGetBillingProvisionsByOrderHandler({
+      profileId: "profile-1",
+      orderIds: ["O-CVFN"]
+    });
+    const payload = result.payload;
+    const details = payload.details;
+    const sales = payload.details_sales;
+    expect(details[0].slice(0, 8)).toEqual([
+      "O-CVFN",
+      "detail-cvfn",
+      "CHARGE",
+      "CVFN",
+      "Costo por ofrecer cuotas",
+      -321.45,
+      "ARS",
+      "FINANCING_FEE"
+    ]);
+    expect(sales[0][0]).toBe("detail-cvfn");
+    expect(sales[0][1]).toBe("O-CVFN");
+    expect(sales[0][4]).toBeNull();
+  });
+  it("keeps missing nested structures nullable without inventing charge data", async () => {
+    axiosGetMock.mockResolvedValue({
+      data: { results: [officialOrderRow({ order_id: "O-PARTIAL", details: [{}] })] }
+    });
+    const result = await meliGetBillingProvisionsByOrderHandler({
+      profileId: "profile-1",
+      orderIds: ["O-PARTIAL"]
+    });
+    const payload = result.payload;
+    const details = payload.details;
+    expect(details).toEqual([["O-PARTIAL", null, null, null, null, null, "ARS", null, null, null, null, null]]);
+    expect(payload.metadata.coverage_complete).toBe(true);
+  });
+  it("preserves fees_added_in_publication per item as the final reversible column", async () => {
+    axiosGetMock.mockResolvedValue({
+      data: {
+        results: [officialOrderRow({
+          order_id: "O-FEES",
+          details: [{
+            charge_info: { detail_id: "detail-fees" },
+            sales_info: [{ order_id: "O-FEES" }],
+            items_info: [
+              { item_id: "ITEM-SI", item_amount: 0, item_price: 0, fees_added_in_publication: "Si" },
+              { item_id: "ITEM-NO", item_amount: 2, item_price: 10, fees_added_in_publication: "No" },
+              { item_id: "ITEM-UNKNOWN", fees_added_in_publication: "YES" },
+              { item_id: "ITEM-MISSING" }
+            ]
+          }]
+        })]
+      }
+    });
+    const result = await meliGetBillingProvisionsByOrderHandler({
+      profileId: "profile-1",
+      orderIds: ["O-FEES"]
+    });
+    const payload = result.payload;
+    const schema = payload.details_items_schema;
+    const items = payload.details_items;
+    expect(schema.at(-1)).toBe("fees_added_in_publication");
+    expect(items).toHaveLength(4);
+    expect(items.map((row) => [row[0], row[1], row[7], row[8]])).toEqual([
+      ["detail-fees", "ITEM-SI", "O-FEES", "Si"],
+      ["detail-fees", "ITEM-NO", "O-FEES", "No"],
+      ["detail-fees", "ITEM-UNKNOWN", "O-FEES", null],
+      ["detail-fees", "ITEM-MISSING", "O-FEES", null]
+    ]);
+    expect(items[0][3]).toBe(0);
+    expect(items[0][4]).toBe(0);
+    expect(items[2][3]).toBeNull();
+    expect(items[2][4]).toBeNull();
+    for (const row of items) expect(row).toHaveLength(schema.length);
+  });
+  it("keeps optional payment and sales numbers nullable while preserving real zero", async () => {
+    axiosGetMock.mockResolvedValue({
+      data: {
+        results: [officialOrderRow({
+          order_id: "O-NUMBERS",
+          payment_info: {
+            installments: void 0,
+            transaction_amount: "invalid",
+            total_paid_amount: 0,
+            shipping_cost: "0",
+            coupon_amount: void 0
+          },
+          details: [{
+            charge_info: { detail_id: "detail-numbers", detail_amount: 0 },
+            sales_info: [
+              { order_id: "O-NUMBERS" },
+              { order_id: "O-NUMBERS", transaction_amount: 0 }
+            ],
+            items_info: []
+          }]
+        })]
+      }
+    });
+    const result = await meliGetBillingProvisionsByOrderHandler({
+      profileId: "profile-1",
+      orderIds: ["O-NUMBERS"]
+    });
+    const payload = result.payload;
+    const payment = payload.payment_info[0];
+    const sales = payload.details_sales;
+    expect(payment.slice(4, 9)).toEqual([null, null, 0, 0, null]);
+    expect(sales.map((row) => row[5])).toEqual([null, 0]);
+    expect(payload.details[0][5]).toBe(0);
+  });
+  it("falls back orders.order_id to nested sales_info", async () => {
+    axiosGetMock.mockResolvedValue({
+      data: {
+        results: [officialOrderRow({
+          order_id: null,
+          payment_info: { order_id: void 0 },
+          details: [{
+            charge_info: { detail_id: "detail-nested-order" },
+            sales_info: [{ order_id: "O-NESTED" }],
+            items_info: [{ item_id: "ITEM-NESTED", fees_added_in_publication: "Si" }]
+          }]
+        })]
+      }
+    });
+    const result = await meliGetBillingProvisionsByOrderHandler({
+      profileId: "profile-1",
+      orderIds: ["O-NESTED"]
+    });
+    const payload = result.payload;
+    expect(payload.orders[0][0]).toBe("O-NESTED");
+    expect(payload.details_items[0][7]).toBe("O-NESTED");
+    expect(payload.metadata.order_ids_found).toEqual(["O-NESTED"]);
+  });
+});
 describe("meliGetBillingProvisionsSummaryHandler", () => {
   beforeEach(() => {
     vi.clearAllMocks();