@yoryoboy/bi-mcp 1.5.2 → 1.6.0

package/dist/src/tools/mercadolibre/get-orders-summary.js

@@ -5,7 +5,10 @@ import {
   formatMercadoLibreError,
   normalizeMercadoLibrePaging
 } from "../../services/mercadolibre/mercadolibre-api.js";
-import { searchMercadoLibreOrders } from "../../services/mercadolibre/mercadolibre-orders.js";
+import {
+  searchMercadoLibreOrders,
+  searchMercadoLibreOrdersBatch
+} from "../../services/mercadolibre/mercadolibre-orders.js";
 import { stripNulls } from "../../utils/strip-payload.js";
 import {
   asArray,
@@ -13,13 +16,600 @@ import {
   compactDateTime,
   currencyBucket,
   mercadoLibreDateRegex,
+  normalizeScalarString,
   normalizeString,
   roundMoney,
   toNumber
 } from "./helpers.js";
 import { resolveMercadoLibreProfileOrSelection } from "./profile-resolution.js";
 import { mercadolibreProfileIdSchemaField } from "./write-helpers.js";
-const ordersSchema = ["id", "date", "status", "total", "currency", "buyer", "shipping", "items"];
+const PAGE_FETCH_CONCURRENCY = 4;
+const PAGE_FETCH_MAX_RETRIES = 2;
+const TOP_LIMIT = 10;
+const ordersSchema = [
+  "id",
+  "date_created",
+  "status",
+  "total_amount",
+  "currency",
+  "buyer",
+  "shipping_status",
+  "items",
+  "date_closed",
+  "last_updated",
+  "paid_amount",
+  "buyer_id",
+  "seller",
+  "seller_id",
+  "shipping_id",
+  "pack_id",
+  "fulfilled",
+  "tags",
+  "channel",
+  "site",
+  "payment_id",
+  "payment_status",
+  "payment_status_detail",
+  "payment_method",
+  "payment_type",
+  "payment_total_paid",
+  "payment_transaction_amount",
+  "installments",
+  "coupon_amount",
+  "available_actions",
+  "feedback_buyer",
+  "feedback_seller",
+  "order_request_change",
+  "order_request_return",
+  "first_item_id",
+  "first_item_title",
+  "first_item_sku",
+  "first_item_quantity",
+  "first_item_unit_price",
+  "first_item_sale_fee",
+  "first_item_listing_type",
+  "variation_attributes",
+  "stock_node_id"
+];
+function compactStringList(values, separator = " | ") {
+  return asArray(values).map((value) => normalizeScalarString(value).trim()).filter(Boolean).join(separator);
+}
+function compactNestedValue(value) {
+  if (value == null) {
+    return "";
+  }
+  const scalar = normalizeScalarString(value);
+  if (scalar) {
+    return scalar;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => compactNestedValue(entry)).filter(Boolean).join(" | ");
+  }
+  const record = asRecord(value);
+  return Object.entries(record).map(([key, entryValue]) => {
+    const normalized = compactNestedValue(entryValue);
+    return normalized ? `${key}:${normalized}` : "";
+  }).filter(Boolean).join(" | ");
+}
+function compactVariationAttributes(value) {
+  return asArray(value).map((attribute) => {
+    const name = normalizeString(attribute.name) || normalizeString(attribute.id);
+    const normalizedValue = normalizeString(attribute.value_name) || normalizeString(attribute.value_id) || normalizeScalarString(attribute.value);
+    if (!name || !normalizedValue) {
+      return "";
+    }
+    return `${name}: ${normalizedValue}`;
+  }).filter(Boolean).join(" | ");
+}
+function createMetricsBucket() {
+  return {
+    orders: 0,
+    revenue: 0,
+    avg_order_value: 0
+  };
+}
+function safeRate(numerator, denominator) {
+  if (!Number.isFinite(denominator) || denominator <= 0) {
+    return 0;
+  }
+  return Number((numerator / denominator).toFixed(4));
+}
+function topBreakdownFromMap(counts, totalOrders, limit = TOP_LIMIT) {
+  const sorted = Array.from(counts.entries()).filter(([, count]) => count > 0).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+  const entries = sorted.slice(0, limit).map(([key, orders]) => ({
+    key,
+    orders,
+    rate: safeRate(orders, totalOrders)
+  }));
+  const otherOrders = sorted.slice(limit).reduce((sum, [, count]) => sum + count, 0);
+  return stripNulls({
+    entries,
+    other_orders: otherOrders > 0 ? otherOrders : void 0,
+    other_rate: otherOrders > 0 ? safeRate(otherOrders, totalOrders) : void 0
+  });
+}
+function incrementCount(map, key) {
+  if (!key) {
+    return;
+  }
+  map.set(key, (map.get(key) ?? 0) + 1);
+}
+function incrementCurrency(map, currencyId, amount) {
+  map[currencyId] = roundMoney((map[currencyId] ?? 0) + amount);
+}
+function sortedCurrencyTotals(input) {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, amount]) => amount !== 0).sort(([left], [right]) => left.localeCompare(right)).map(([currency, amount]) => [currency, roundMoney(amount)])
+  );
+}
+function compactFeedbackValue(value) {
+  const compact = compactNestedValue(value);
+  return compact.trim();
+}
+function getFirstPayment(order) {
+  return asRecord(asArray(order.payments)[0]);
+}
+function getOrderCurrency(order) {
+  return normalizeString(order.currency_id, "UNKNOWN");
+}
+function buildCalculations(orders, metadata, failedPages) {
+  const ordersTotal = orders.length;
+  const statusCounts = /* @__PURE__ */ new Map();
+  const tagCounts = /* @__PURE__ */ new Map();
+  const channelCounts = /* @__PURE__ */ new Map();
+  const siteCounts = /* @__PURE__ */ new Map();
+  const paymentStatusCounts = /* @__PURE__ */ new Map();
+  const paymentStatusDetailCounts = /* @__PURE__ */ new Map();
+  const paymentMethodCounts = /* @__PURE__ */ new Map();
+  const paymentTypeCounts = /* @__PURE__ */ new Map();
+  const installmentsCounts = /* @__PURE__ */ new Map();
+  const stockNodeCounts = /* @__PURE__ */ new Map();
+  const listingTypeCounts = /* @__PURE__ */ new Map();
+  const variationValueCounts = /* @__PURE__ */ new Map();
+  const buyers = /* @__PURE__ */ new Map();
+  const items = /* @__PURE__ */ new Map();
+  const variations = /* @__PURE__ */ new Map();
+  const skus = /* @__PURE__ */ new Map();
+  let unitsTotal = 0;
+  let fulfilledOrders = 0;
+  let deliveredOrders = 0;
+  let packOrders = 0;
+  let discountedOrders = 0;
+  let catalogOrders = 0;
+  let ordersWithFeedback = 0;
+  let ordersWithChangeRequest = 0;
+  let ordersWithReturnRequest = 0;
+  let feedbackBuyerCount = 0;
+  let feedbackSellerCount = 0;
+  let ordersWithShipping = 0;
+  let singleItemOrders = 0;
+  let multiItemOrders = 0;
+  let ordersWithoutPaymentData = 0;
+  let paymentApprovedOrders = 0;
+  let itemLineCount = 0;
+  let ordersWithAnyPostSaleIssue = 0;
+  const itemsSeen = /* @__PURE__ */ new Set();
+  const buyerSeen = /* @__PURE__ */ new Set();
+  const financialRaw = {};
+  for (const order of orders) {
+    const currencyId = getOrderCurrency(order);
+    const totalAmount = toNumber(order.total_amount);
+    const paidAmount = toNumber(order.paid_amount);
+    const couponAmount = toNumber(asRecord(order.coupon).amount);
+    const payment = getFirstPayment(order);
+    const orderItems = asArray(order.order_items);
+    const buyer = asRecord(order.buyer);
+    const seller = asRecord(order.seller);
+    const feedback = asRecord(order.feedback);
+    const orderRequest = asRecord(order.order_request);
+    const shipping = asRecord(order.shipping);
+    const context = asRecord(order.context);
+    const paymentStatus = normalizeString(payment.status);
+    const paymentStatusDetail = normalizeString(payment.status_detail);
+    const paymentMethod = normalizeString(payment.payment_method_id);
+    const paymentType = normalizeString(payment.payment_type);
+    const installments = normalizeScalarString(payment.installments);
+    const tags = asArray(order.tags).map((tag) => normalizeScalarString(tag)).filter(Boolean);
+    const orderItemDistinctIds = /* @__PURE__ */ new Set();
+    financialRaw[currencyId] = financialRaw[currencyId] ?? {
+      orders: 0,
+      units: 0,
+      distinctItems: 0,
+      revenue: 0,
+      paidAmount: 0,
+      paymentTotalPaidAmount: 0,
+      transactionAmount: 0,
+      couponAmount: 0,
+      saleFee: 0
+    };
+    financialRaw[currencyId].orders += 1;
+    financialRaw[currencyId].revenue += totalAmount;
+    financialRaw[currencyId].paidAmount += paidAmount;
+    financialRaw[currencyId].paymentTotalPaidAmount += toNumber(payment.total_paid_amount);
+    financialRaw[currencyId].transactionAmount += toNumber(payment.transaction_amount);
+    financialRaw[currencyId].couponAmount += couponAmount;
+    incrementCount(statusCounts, normalizeString(order.status));
+    incrementCount(channelCounts, normalizeString(context.channel));
+    incrementCount(siteCounts, normalizeString(context.site));
+    if (paymentStatus) {
+      incrementCount(paymentStatusCounts, paymentStatus);
+    } else {
+      ordersWithoutPaymentData += 1;
+    }
+    incrementCount(paymentStatusDetailCounts, paymentStatusDetail);
+    incrementCount(paymentMethodCounts, paymentMethod);
+    incrementCount(paymentTypeCounts, paymentType);
+    incrementCount(installmentsCounts, installments);
+    if (paymentStatus === "approved") {
+      paymentApprovedOrders += 1;
+    }
+    if (order.fulfilled === true) {
+      fulfilledOrders += 1;
+    }
+    if (normalizeScalarString(shipping.id)) {
+      ordersWithShipping += 1;
+    }
+    if (orderItems.length === 1) {
+      singleItemOrders += 1;
+    } else if (orderItems.length > 1) {
+      multiItemOrders += 1;
+    }
+    for (const tag of tags) {
+      incrementCount(tagCounts, tag);
+    }
+    if (tags.includes("delivered")) {
+      deliveredOrders += 1;
+    }
+    if (tags.includes("pack_order")) {
+      packOrders += 1;
+    }
+    if (tags.includes("order_has_discount")) {
+      discountedOrders += 1;
+    }
+    if (tags.includes("catalog")) {
+      catalogOrders += 1;
+    }
+    const feedbackBuyer = compactFeedbackValue(feedback.buyer);
+    const feedbackSeller = compactFeedbackValue(feedback.seller);
+    const hasFeedback = Boolean(feedbackBuyer || feedbackSeller);
+    if (hasFeedback) {
+      ordersWithFeedback += 1;
+    }
+    if (feedbackBuyer) {
+      feedbackBuyerCount += 1;
+    }
+    if (feedbackSeller) {
+      feedbackSellerCount += 1;
+    }
+    const hasChangeRequest = Boolean(compactFeedbackValue(orderRequest.change));
+    const hasReturnRequest = Boolean(compactFeedbackValue(orderRequest.return));
+    if (hasChangeRequest) {
+      ordersWithChangeRequest += 1;
+    }
+    if (hasReturnRequest) {
+      ordersWithReturnRequest += 1;
+    }
+    if (hasFeedback || hasChangeRequest || hasReturnRequest) {
+      ordersWithAnyPostSaleIssue += 1;
+    }
+    const buyerId = normalizeScalarString(buyer.id);
+    const buyerNickname = normalizeString(buyer.nickname);
+    if (buyerId || buyerNickname) {
+      const buyerKey = buyerId || buyerNickname;
+      buyerSeen.add(buyerKey);
+      const currentBuyer = buyers.get(buyerKey) ?? {
+        buyer_id: buyerId,
+        nickname: buyerNickname,
+        orders: 0,
+        revenue_by_currency: {}
+      };
+      currentBuyer.orders += 1;
+      incrementCurrency(currentBuyer.revenue_by_currency, currencyId, totalAmount);
+      buyers.set(buyerKey, currentBuyer);
+    }
+    for (const orderItem of orderItems) {
+      itemLineCount += 1;
+      const item = asRecord(orderItem.item);
+      const stock = asRecord(orderItem.stock);
+      const itemId = normalizeString(item.id);
+      const title = normalizeString(item.title);
+      const sellerSku = normalizeString(item.seller_sku);
+      const quantity = toNumber(orderItem.quantity);
+      const unitPrice = toNumber(orderItem.unit_price);
+      const saleFee = toNumber(orderItem.sale_fee);
+      const listingType = normalizeString(orderItem.listing_type_id);
+      const stockNode = normalizeString(stock.node_id);
+      const variationSummary = compactVariationAttributes(item.variation_attributes);
+      const itemKey = `${itemId}::${variationSummary}::${sellerSku}`;
+      const skuKey = sellerSku || itemId || title;
+      const variationKey = variationSummary || "NO_VARIATION";
+      unitsTotal += quantity;
+      financialRaw[currencyId].units += quantity;
+      financialRaw[currencyId].saleFee += saleFee;
+      if (itemId) {
+        itemsSeen.add(itemId);
+        orderItemDistinctIds.add(itemId);
+      }
+      incrementCount(listingTypeCounts, listingType);
+      incrementCount(stockNodeCounts, stockNode);
+      incrementCount(variationValueCounts, variationKey);
+      const itemAggregate = items.get(itemKey) ?? {
+        item_id: itemId,
+        title,
+        seller_sku: sellerSku,
+        variation_summary: variationSummary,
+        orders: 0,
+        units: 0,
+        revenue_by_currency: {},
+        sale_fee_by_currency: {}
+      };
+      itemAggregate.orders += 1;
+      itemAggregate.units += quantity;
+      incrementCurrency(itemAggregate.revenue_by_currency, currencyId, unitPrice * quantity);
+      incrementCurrency(itemAggregate.sale_fee_by_currency, currencyId, saleFee);
+      items.set(itemKey, itemAggregate);
+      const variationAggregate = variations.get(variationKey) ?? {
+        variation_summary: variationSummary,
+        orders: 0,
+        units: 0,
+        revenue_by_currency: {}
+      };
+      variationAggregate.orders += 1;
+      variationAggregate.units += quantity;
+      incrementCurrency(variationAggregate.revenue_by_currency, currencyId, unitPrice * quantity);
+      variations.set(variationKey, variationAggregate);
+      const skuAggregate = skus.get(skuKey) ?? {
+        seller_sku: sellerSku,
+        orders: 0,
+        units: 0,
+        revenue_by_currency: {}
+      };
+      skuAggregate.orders += 1;
+      skuAggregate.units += quantity;
+      incrementCurrency(skuAggregate.revenue_by_currency, currencyId, unitPrice * quantity);
+      skus.set(skuKey, skuAggregate);
+    }
+    financialRaw[currencyId].distinctItems += orderItemDistinctIds.size;
+  }
+  const financialByCurrency = {};
+  for (const [currencyId, raw] of Object.entries(financialRaw)) {
+    financialByCurrency[currencyId] = {
+      revenue_total: roundMoney(raw.revenue),
+      paid_amount_total: roundMoney(raw.paidAmount),
+      payment_total_paid_amount: roundMoney(raw.paymentTotalPaidAmount),
+      transaction_amount_total: roundMoney(raw.transactionAmount),
+      coupon_amount_total: roundMoney(raw.couponAmount),
+      sale_fee_total: roundMoney(raw.saleFee),
+      avg_order_value: roundMoney(raw.revenue / Math.max(1, raw.orders)),
+      avg_paid_amount_per_order: roundMoney(raw.paidAmount / Math.max(1, raw.orders)),
+      avg_units_per_order: roundMoney(raw.units / Math.max(1, raw.orders)),
+      avg_distinct_items_per_order: roundMoney(raw.distinctItems / Math.max(1, raw.orders)),
+      avg_sale_fee_per_order: roundMoney(raw.saleFee / Math.max(1, raw.orders)),
+      sale_fee_rate: safeRate(raw.saleFee, raw.revenue)
+    };
+  }
+  const topItemsByRevenue = Array.from(items.values()).sort((left, right) => {
+    const leftRevenue = Object.values(left.revenue_by_currency).reduce((sum, value) => sum + value, 0);
+    const rightRevenue = Object.values(right.revenue_by_currency).reduce((sum, value) => sum + value, 0);
+    return rightRevenue - leftRevenue || left.item_id.localeCompare(right.item_id);
+  }).slice(0, TOP_LIMIT).map((item) => ({
+    ...item,
+    revenue_by_currency: sortedCurrencyTotals(item.revenue_by_currency),
+    sale_fee_by_currency: sortedCurrencyTotals(item.sale_fee_by_currency)
+  }));
+  const topItemsByUnits = Array.from(items.values()).sort((left, right) => right.units - left.units || left.item_id.localeCompare(right.item_id)).slice(0, TOP_LIMIT).map((item) => ({
+    ...item,
+    revenue_by_currency: sortedCurrencyTotals(item.revenue_by_currency),
+    sale_fee_by_currency: sortedCurrencyTotals(item.sale_fee_by_currency)
+  }));
+  const topItemsByOrders = Array.from(items.values()).sort((left, right) => right.orders - left.orders || left.item_id.localeCompare(right.item_id)).slice(0, TOP_LIMIT).map((item) => ({
+    ...item,
+    revenue_by_currency: sortedCurrencyTotals(item.revenue_by_currency),
+    sale_fee_by_currency: sortedCurrencyTotals(item.sale_fee_by_currency)
+  }));
+  const topVariations = Array.from(variations.values()).filter((variation) => variation.variation_summary).sort((left, right) => right.units - left.units || left.variation_summary.localeCompare(right.variation_summary)).slice(0, TOP_LIMIT).map((variation) => ({
+    ...variation,
+    revenue_by_currency: sortedCurrencyTotals(variation.revenue_by_currency)
+  }));
+  const topSkus = Array.from(skus.values()).filter((sku) => sku.seller_sku).sort((left, right) => right.units - left.units || left.seller_sku.localeCompare(right.seller_sku)).slice(0, TOP_LIMIT).map((sku) => ({
+    ...sku,
+    revenue_by_currency: sortedCurrencyTotals(sku.revenue_by_currency)
+  }));
+  const topBuyersByRevenue = Array.from(buyers.values()).sort((left, right) => {
+    const leftRevenue = Object.values(left.revenue_by_currency).reduce((sum, value) => sum + value, 0);
+    const rightRevenue = Object.values(right.revenue_by_currency).reduce((sum, value) => sum + value, 0);
+    return rightRevenue - leftRevenue || left.buyer_id.localeCompare(right.buyer_id);
+  }).slice(0, TOP_LIMIT).map((buyer) => ({
+    ...buyer,
+    revenue_by_currency: sortedCurrencyTotals(buyer.revenue_by_currency)
+  }));
+  const topBuyersByOrders = Array.from(buyers.values()).sort((left, right) => right.orders - left.orders || left.buyer_id.localeCompare(right.buyer_id)).slice(0, TOP_LIMIT).map((buyer) => ({
+    ...buyer,
+    revenue_by_currency: sortedCurrencyTotals(buyer.revenue_by_currency)
+  }));
+  const buyersWithMultipleOrders = Array.from(buyers.values()).filter((buyer) => buyer.orders > 1).length;
+  const topVariationValues = Array.from(variationValueCounts.entries()).filter(([key]) => key && key !== "NO_VARIATION").sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).slice(0, TOP_LIMIT).map(([key, occurrences]) => ({ key, occurrences }));
+  const topSingleValue = (counts) => Array.from(counts.entries()).filter(([key]) => key).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))[0]?.[0] ?? "";
+  return {
+    overview: {
+      orders_total: ordersTotal,
+      units_total: unitsTotal,
+      distinct_items_total: itemsSeen.size,
+      distinct_buyers_total: buyerSeen.size,
+      fulfilled_orders: fulfilledOrders,
+      delivered_orders: deliveredOrders,
+      pack_orders: packOrders,
+      orders_with_discount: discountedOrders,
+      orders_with_feedback: ordersWithFeedback,
+      orders_with_change_request: ordersWithChangeRequest,
+      orders_with_return_request: ordersWithReturnRequest
+    },
+    financial_by_currency: financialByCurrency,
+    order_mix: {
+      status_breakdown: topBreakdownFromMap(statusCounts, ordersTotal),
+      tags_breakdown: topBreakdownFromMap(tagCounts, ordersTotal),
+      channel_breakdown: topBreakdownFromMap(channelCounts, ordersTotal),
+      site_breakdown: topBreakdownFromMap(siteCounts, ordersTotal),
+      single_item_order_rate: safeRate(singleItemOrders, ordersTotal),
+      multi_item_order_rate: safeRate(multiItemOrders, ordersTotal),
+      fulfilled_rate: safeRate(fulfilledOrders, ordersTotal),
+      delivered_rate: safeRate(deliveredOrders, ordersTotal),
+      pack_order_rate: safeRate(packOrders, ordersTotal),
+      discounted_order_rate: safeRate(discountedOrders, ordersTotal),
+      catalog_order_rate: safeRate(catalogOrders, ordersTotal)
+    },
+    payment_mix: {
+      payment_status_breakdown: topBreakdownFromMap(paymentStatusCounts, ordersTotal),
+      payment_status_detail_breakdown: topBreakdownFromMap(paymentStatusDetailCounts, ordersTotal),
+      payment_method_breakdown: topBreakdownFromMap(paymentMethodCounts, ordersTotal),
+      payment_type_breakdown: topBreakdownFromMap(paymentTypeCounts, ordersTotal),
+      installments_breakdown: topBreakdownFromMap(installmentsCounts, ordersTotal),
+      payment_approved_rate: safeRate(paymentApprovedOrders, ordersTotal),
+      orders_without_payment_data: ordersWithoutPaymentData
+    },
+    fulfillment: {
+      orders_with_shipping: ordersWithShipping,
+      shipping_attached_rate: safeRate(ordersWithShipping, ordersTotal),
+      shipping_id_coverage: ordersWithShipping,
+      stock_node_breakdown: topBreakdownFromMap(stockNodeCounts, Math.max(1, itemLineCount)),
+      listing_type_breakdown: topBreakdownFromMap(listingTypeCounts, Math.max(1, itemLineCount))
+    },
+    post_sale_friction: {
+      orders_with_feedback_rate: safeRate(ordersWithFeedback, ordersTotal),
+      feedback_buyer_count: feedbackBuyerCount,
+      feedback_seller_count: feedbackSellerCount,
+      change_request_rate: safeRate(ordersWithChangeRequest, ordersTotal),
+      return_request_rate: safeRate(ordersWithReturnRequest, ordersTotal),
+      orders_with_any_post_sale_issue_rate: safeRate(ordersWithAnyPostSaleIssue, ordersTotal)
+    },
+    product_insights: {
+      top_items_by_revenue: topItemsByRevenue,
+      top_items_by_units: topItemsByUnits,
+      top_items_by_orders: topItemsByOrders,
+      top_variations: topVariations,
+      top_skus: topSkus,
+      top_listing_types: topBreakdownFromMap(listingTypeCounts, Math.max(1, itemLineCount)),
+      top_stock_nodes: topBreakdownFromMap(stockNodeCounts, Math.max(1, itemLineCount))
+    },
+    customer_insights: {
+      top_buyers_by_revenue: topBuyersByRevenue,
+      top_buyers_by_orders: topBuyersByOrders,
+      repeat_buyer_rate: safeRate(buyersWithMultipleOrders, buyerSeen.size),
+      buyers_with_multiple_orders: buyersWithMultipleOrders
+    },
+    operational_context: {
+      most_used_payment_method: topSingleValue(paymentMethodCounts),
+      most_used_listing_type: topSingleValue(listingTypeCounts),
+      most_used_stock_node: topSingleValue(stockNodeCounts),
+      most_used_channel: topSingleValue(channelCounts),
+      most_common_tag: topSingleValue(tagCounts),
+      most_common_variation_values: topVariationValues
+    },
+    coverage: {
+      fetch_mode: metadata.fetch_mode,
+      universe_fully_fetched: metadata.universe_fully_fetched,
+      orders_returned: metadata.returned,
+      pages_requested: metadata.pages_requested,
+      pages_succeeded: metadata.pages_succeeded,
+      pages_failed: metadata.pages_failed,
+      failed_pages_count: failedPages.length,
+      failed_pages: failedPages
+    }
+  };
+}
+function buildOrdersSummaryMetadata(params) {
+  const hasMoreForPage = params.effectiveOffset + params.returned < params.total;
+  const universeFullyFetched = !params.paginated && params.pagesFailed === 0 && params.returned >= params.total;
+  let continuation = "No more pages for this query.";
+  if (params.paginated && hasMoreForPage) {
+    continuation = `Reenviar la misma tool con offset=${params.effectiveOffset + params.effectiveLimit} para continuar.`;
+  } else if (params.pagesFailed > 0) {
+    const offsets = params.failedOffsets.slice(0, 5).join(", ");
+    const moreOffsets = params.failedOffsets.length > 5 ? ` y ${params.failedOffsets.length - 5} offsets adicionales` : "";
+    continuation = `Se recuperaron paginas parciales. Reintentar la misma tool con los offsets fallidos (${offsets}${moreOffsets}) y limit=${params.effectiveLimit}.`;
+  } else if (!params.paginated) {
+    continuation = "Universe fetched successfully.";
+  }
+  return {
+    total: params.total,
+    limit: params.effectiveLimit,
+    offset: params.effectiveOffset,
+    returned: params.returned,
+    has_more: params.paginated ? hasMoreForPage : params.pagesFailed > 0,
+    continuation,
+    fetch_mode: params.paginated ? "page" : "full",
+    pages_requested: params.pagesRequested,
+    pages_succeeded: params.pagesSucceeded,
+    pages_failed: params.pagesFailed,
+    universe_fully_fetched: universeFullyFetched
+  };
+}
+function formatCompactOrder(order, metricsByCurrency) {
+  const currencyId = normalizeString(order.currency_id, "UNKNOWN");
+  const totalAmount = toNumber(order.total_amount);
+  const paidAmount = toNumber(order.paid_amount);
+  const bucket = currencyBucket(metricsByCurrency, currencyId, createMetricsBucket);
+  bucket.orders += 1;
+  bucket.revenue += totalAmount;
+  bucket.avg_order_value = bucket.orders > 0 ? bucket.revenue / bucket.orders : 0;
+  const orderItems = asArray(order.order_items);
+  const firstOrderItem = asRecord(orderItems[0]);
+  const firstItem = asRecord(firstOrderItem.item);
+  const firstPayment = asRecord(asArray(order.payments)[0]);
+  const shipping = asRecord(order.shipping);
+  const buyer = asRecord(order.buyer);
+  const seller = asRecord(order.seller);
+  const context = asRecord(order.context);
+  const feedback = asRecord(order.feedback);
+  const orderRequest = asRecord(order.order_request);
+  const coupon = asRecord(order.coupon);
+  const stock = asRecord(firstOrderItem.stock);
+  return [
+    normalizeScalarString(order.id),
+    compactDateTime(order.date_created),
+    normalizeString(order.status),
+    totalAmount,
+    currencyId,
+    normalizeString(buyer.nickname) || normalizeScalarString(buyer.id),
+    normalizeString(shipping.status),
+    orderItems.length,
+    compactDateTime(order.date_closed),
+    compactDateTime(order.date_last_updated) || compactDateTime(order.last_updated),
+    paidAmount,
+    normalizeScalarString(buyer.id),
+    normalizeString(seller.nickname) || normalizeScalarString(seller.id),
+    normalizeScalarString(seller.id),
+    normalizeScalarString(shipping.id),
+    normalizeScalarString(order.pack_id),
+    Boolean(order.fulfilled),
+    compactStringList(order.tags),
+    normalizeString(context.channel),
+    normalizeString(context.site),
+    normalizeScalarString(firstPayment.id),
+    normalizeString(firstPayment.status),
+    normalizeString(firstPayment.status_detail),
+    normalizeString(firstPayment.payment_method_id),
+    normalizeString(firstPayment.payment_type),
+    toNumber(firstPayment.total_paid_amount),
+    toNumber(firstPayment.transaction_amount),
+    toNumber(firstPayment.installments),
+    toNumber(coupon.amount),
+    compactStringList(firstPayment.available_actions),
+    compactNestedValue(feedback.buyer),
+    compactNestedValue(feedback.seller),
+    compactNestedValue(orderRequest.change),
+    compactNestedValue(orderRequest.return),
+    normalizeString(firstItem.id),
+    normalizeString(firstItem.title),
+    normalizeString(firstItem.seller_sku),
+    toNumber(firstOrderItem.quantity),
+    toNumber(firstOrderItem.unit_price),
+    toNumber(firstOrderItem.sale_fee),
+    normalizeString(firstOrderItem.listing_type_id),
+    compactVariationAttributes(firstItem.variation_attributes),
+    normalizeString(stock.node_id)
+  ];
+}
 const meliGetOrdersSummarySchema = z.object({
   profileId: mercadolibreProfileIdSchemaField,
   startDate: z.string().regex(mercadoLibreDateRegex).describe("Start date in YYYY-MM-DD format."),
@@ -27,8 +617,8 @@ const meliGetOrdersSummarySchema = z.object({
   status: z.string().trim().min(1).optional().describe("Optional MercadoLibre order status filter."),
   q: z.string().trim().min(1).optional().describe("Optional free-text search query supported by MercadoLibre orders search."),
   sort: z.string().trim().min(1).optional().describe("Optional MercadoLibre sort expression."),
-  offset: z.number().int().min(0).max(5e3).optional().describe("Pagination offset."),
-  limit: z.number().int().min(1).max(50).optional().describe("Results per page (1-50).")
+  offset: z.number().int().min(0).max(5e3).optional().describe("Optional pagination offset. If provided, the tool returns only that page instead of trying to fetch the full universe."),
+  limit: z.number().int().min(1).max(50).optional().describe("Optional page size (1-50). If provided, the tool returns only that page instead of trying to fetch the full universe.")
 });
 async function meliGetOrdersSummaryHandler(params) {
   try {
@@ -47,51 +637,93 @@ async function meliGetOrdersSummaryHandler(params) {
       offset: params.offset,
       limit: params.limit
     });
-    const orders = asArray(response.results);
     const paging = normalizeMercadoLibrePaging(asRecord(response.paging));
+    const baseOrders = asArray(response.results);
     const metricsByCurrency = {};
-    const compactOrders = orders.map((order) => {
-      const currencyId = normalizeString(order.currency_id, "UNKNOWN");
-      const totalAmount = toNumber(order.total_amount);
-      const bucket = currencyBucket(metricsByCurrency, currencyId, () => ({
-        orders: 0,
-        revenue: 0,
-        avg_order_value: 0
-      }));
-      bucket.orders += 1;
-      bucket.revenue += totalAmount;
-      bucket.avg_order_value = bucket.orders > 0 ? bucket.revenue / bucket.orders : 0;
-      const orderItems = asArray(order.order_items);
-      const shipping = asRecord(order.shipping);
-      const buyer = asRecord(order.buyer);
-      return [
-        normalizeString(order.id),
-        compactDateTime(order.date_created),
-        normalizeString(order.status),
-        totalAmount,
-        currencyId,
-        normalizeString(buyer.nickname) || normalizeString(buyer.id),
-        normalizeString(shipping.status),
-        orderItems.length
-      ];
-    });
+    const paginatedMode = params.offset !== void 0 || params.limit !== void 0;
+    const effectiveLimit = paging.limit || params.limit || baseOrders.length;
+    const effectiveOffset = paging.offset || params.offset || 0;
+    const allOrders = [...baseOrders];
+    const failedPages = [];
+    let pagesRequested = 1;
+    let pagesSucceeded = 1;
+    if (!paginatedMode && effectiveLimit > 0 && paging.total > baseOrders.length) {
+      const nextOffsets = [];
+      for (let nextOffset = effectiveOffset + effectiveLimit; nextOffset < paging.total; nextOffset += effectiveLimit) {
+        nextOffsets.push(nextOffset);
+      }
+      pagesRequested += nextOffsets.length;
+      if (nextOffsets.length > 0) {
+        const batch = await searchMercadoLibreOrdersBatch(
+          profileId,
+          {
+            seller: "",
+            from: params.startDate,
+            to: params.endDate,
+            status: params.status,
+            q: params.q,
+            sort: params.sort,
+            limit: effectiveLimit
+          },
+          nextOffsets,
+          {
+            maxConcurrency: PAGE_FETCH_CONCURRENCY,
+            maxRetries: PAGE_FETCH_MAX_RETRIES
+          }
+        );
+        pagesSucceeded += batch.successful.length;
+        batch.successful.forEach((entry) => {
+          allOrders.push(...asArray(entry.document.results));
+        });
+        batch.failed.forEach((failure) => {
+          const failedOffset = Number(failure.id);
+          failedPages.push({
+            offset: failedOffset,
+            limit: effectiveLimit,
+            page_number: Math.floor(failedOffset / effectiveLimit) + 1,
+            message: failure.message,
+            status_code: failure.statusCode,
+            attempts: failure.attempts,
+            retryable: failure.retryable
+          });
+        });
+      }
+    }
+    const compactOrders = allOrders.map((order) => formatCompactOrder(order, metricsByCurrency));
     for (const metrics of Object.values(metricsByCurrency)) {
       metrics.revenue = roundMoney(metrics.revenue);
       metrics.avg_order_value = roundMoney(metrics.avg_order_value);
     }
+    const metadata = buildOrdersSummaryMetadata({
+      total: paging.total,
+      effectiveLimit,
+      effectiveOffset,
+      returned: compactOrders.length,
+      paginated: paginatedMode,
+      pagesRequested,
+      pagesSucceeded,
+      pagesFailed: failedPages.length,
+      failedOffsets: failedPages.map((failure) => failure.offset)
+    });
+    const calculations = buildCalculations(allOrders, metadata, failedPages);
     return object(
       stripNulls({
         profile_id: profileId,
-        metadata: buildMercadoLibrePaginationMetadata({
-          total: paging.total,
-          limit: paging.limit || params.limit || compactOrders.length,
-          offset: paging.offset || params.offset || 0,
-          returned: compactOrders.length,
-          nextField: "offset"
-        }),
+        metadata: paginatedMode ? {
+          ...buildMercadoLibrePaginationMetadata({
+            total: paging.total,
+            limit: effectiveLimit,
+            offset: effectiveOffset,
+            returned: compactOrders.length,
+            nextField: "offset"
+          }),
+          ...metadata
+        } : metadata,
         metrics_by_currency: metricsByCurrency,
         orders_schema: ordersSchema,
-        orders: compactOrders
+        orders: compactOrders,
+        calculations,
+        failed_pages: failedPages
       })
     );
   } catch (err) {