@yoryoboy/bi-mcp 1.5.3 → 1.7.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,922 @@ 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 = 15;
+const PAGE_FETCH_MAX_RETRIES = 2;
+const ORDER_DETAIL_MAX_PAGES_PER_CALL = 15;
+const DEFAULT_ORDER_DETAIL_PAGE_LIMIT = 50;
+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 createCurrencyMetricBucket() {
+  return {
+    orders: 0,
+    units: 0,
+    revenue: 0,
+    paidRevenue: 0,
+    paymentTotalPaid: 0,
+    transactionAmount: 0,
+    refundedAmount: 0,
+    cancelledGmv: 0,
+    saleFee: 0,
+    shippingCost: 0,
+    couponAmount: 0,
+    paymentCouponAmount: 0,
+    discountedGmv: 0,
+    notDeliveredGmv: 0,
+    cancelledOrders: 0,
+    refundedOrders: 0,
+    ordersWithShippingCost: 0,
+    ordersWithCoupon: 0,
+    discountedOrders: 0,
+    notDeliveredOrders: 0
+  };
+}
+function incrementCurrencyMetric(map, currencyId, updater) {
+  map[currencyId] = map[currencyId] ?? createCurrencyMetricBucket();
+  updater(map[currencyId]);
+}
+function sortedCurrencyMetrics(input, mapper) {
+  return Object.fromEntries(
+    Object.entries(input).sort(([left], [right]) => left.localeCompare(right)).map(([currencyId, bucket]) => [currencyId, stripNulls(mapper(bucket))])
+  );
+}
+function topAmountBreakdownFromMap(counts, amounts, 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),
+    amount_by_currency: sortedCurrencyTotals(amounts.get(key) ?? {})
+  }));
+  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 revenueSum(input) {
+  return Object.values(input).reduce((sum, value) => sum + value, 0);
+}
+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();
+  const dailyMetrics = /* @__PURE__ */ new Map();
+  const flowMetrics = /* @__PURE__ */ new Map();
+  const skuEconomics = /* @__PURE__ */ new Map();
+  const cancelGroupCounts = /* @__PURE__ */ new Map();
+  const cancelCodeCounts = /* @__PURE__ */ new Map();
+  const cancelRequestedByCounts = /* @__PURE__ */ new Map();
+  const cancelReasonCounts = /* @__PURE__ */ new Map();
+  const cancelReasonAmounts = /* @__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;
+  let ordersWithRefundedAmount = 0;
+  let ordersWithShippingCostAmount = 0;
+  let ordersWithCouponAmount = 0;
+  let notDeliveredOrders = 0;
+  let multiUnitItemLines = 0;
+  let multiUnitSaleFeeObservations = 0;
+  const itemsSeen = /* @__PURE__ */ new Set();
+  const buyerSeen = /* @__PURE__ */ new Set();
+  const financialRaw = {};
+  const currencyMetrics = {};
+  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 cancelDetail = asRecord(order.cancel_detail);
+    const isCancelled = normalizeString(order.status) === "cancelled";
+    const refundedAmount = toNumber(payment.transaction_amount_refunded);
+    const shippingCost = toNumber(payment.shipping_cost);
+    const paymentCouponAmount = toNumber(payment.coupon_amount);
+    const dayKey = compactDateTime(order.date_created)?.slice(0, 10) || "UNKNOWN_DATE";
+    const flows = asArray(context.flows).map((flow) => normalizeScalarString(flow)).filter(Boolean);
+    const effectiveFlows = flows.length > 0 ? flows : ["NO_FLOW"];
+    const isDiscounted = tags.includes("order_has_discount") || couponAmount > 0 || paymentCouponAmount > 0;
+    const isNotDelivered = tags.includes("not_delivered") || normalizeString(cancelDetail.group) === "shipment";
+    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;
+    const dailyCurrencyMetrics = dailyMetrics.get(dayKey) ?? {};
+    dailyMetrics.set(dayKey, dailyCurrencyMetrics);
+    const updateOrderCurrencyMetrics = (bucket) => {
+      bucket.orders += 1;
+      bucket.revenue += totalAmount;
+      bucket.paidRevenue += paidAmount;
+      bucket.paymentTotalPaid += toNumber(payment.total_paid_amount);
+      bucket.transactionAmount += toNumber(payment.transaction_amount);
+      bucket.refundedAmount += refundedAmount;
+      bucket.shippingCost += shippingCost;
+      bucket.couponAmount += couponAmount;
+      bucket.paymentCouponAmount += paymentCouponAmount;
+      if (isCancelled) {
+        bucket.cancelledOrders += 1;
+        bucket.cancelledGmv += totalAmount;
+      }
+      if (refundedAmount > 0) {
+        bucket.refundedOrders += 1;
+      }
+      if (shippingCost > 0) {
+        bucket.ordersWithShippingCost += 1;
+      }
+      if (couponAmount > 0 || paymentCouponAmount > 0) {
+        bucket.ordersWithCoupon += 1;
+      }
+      if (isDiscounted) {
+        bucket.discountedOrders += 1;
+      }
+      if (isNotDelivered) {
+        bucket.notDeliveredOrders += 1;
+      }
+    };
+    incrementCurrencyMetric(currencyMetrics, currencyId, updateOrderCurrencyMetrics);
+    incrementCurrencyMetric(dailyCurrencyMetrics, currencyId, updateOrderCurrencyMetrics);
+    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;
+    }
+    if (refundedAmount > 0) {
+      ordersWithRefundedAmount += 1;
+    }
+    if (shippingCost > 0) {
+      ordersWithShippingCostAmount += 1;
+    }
+    if (couponAmount > 0 || paymentCouponAmount > 0) {
+      ordersWithCouponAmount += 1;
+    }
+    if (isNotDelivered) {
+      notDeliveredOrders += 1;
+    }
+    if (isCancelled) {
+      const cancelGroup = normalizeString(cancelDetail.group, "UNKNOWN_GROUP");
+      const cancelCode = normalizeString(cancelDetail.code, "UNKNOWN_CODE");
+      const requestedBy = normalizeString(cancelDetail.requested_by, "UNKNOWN_REQUESTER");
+      const reasonKey = `${cancelGroup}:${cancelCode}:${requestedBy}`;
+      incrementCount(cancelGroupCounts, cancelGroup);
+      incrementCount(cancelCodeCounts, cancelCode);
+      incrementCount(cancelRequestedByCounts, requestedBy);
+      incrementCount(cancelReasonCounts, reasonKey);
+      const reasonAmount = cancelReasonAmounts.get(reasonKey) ?? {};
+      incrementCurrency(reasonAmount, currencyId, totalAmount);
+      cancelReasonAmounts.set(reasonKey, reasonAmount);
+    }
+    for (const flow of effectiveFlows) {
+      const flowAggregate = flowMetrics.get(flow) ?? {
+        flow,
+        orders: 0,
+        units: 0,
+        cancelled_orders: 0,
+        revenue_by_currency: {},
+        paid_revenue_by_currency: {},
+        sale_fee_by_currency: {}
+      };
+      flowAggregate.orders += 1;
+      if (isCancelled) {
+        flowAggregate.cancelled_orders += 1;
+      }
+      incrementCurrency(flowAggregate.revenue_by_currency, currencyId, totalAmount);
+      incrementCurrency(flowAggregate.paid_revenue_by_currency, currencyId, paidAmount);
+      flowMetrics.set(flow, flowAggregate);
+    }
+    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 || "UNKNOWN_SKU";
+      const variationKey = variationSummary || "NO_VARIATION";
+      const itemRevenue = unitPrice * quantity;
+      const paidRevenueApprox = totalAmount > 0 ? paidAmount * (itemRevenue / totalAmount) : itemRevenue;
+      const refundedAmountApprox = totalAmount > 0 ? refundedAmount * (itemRevenue / totalAmount) : refundedAmount;
+      if (quantity > 1) {
+        multiUnitItemLines += 1;
+        if (saleFee > 0) {
+          multiUnitSaleFeeObservations += 1;
+        }
+      }
+      unitsTotal += quantity;
+      financialRaw[currencyId].units += quantity;
+      financialRaw[currencyId].saleFee += saleFee;
+      const updateItemCurrencyMetrics = (bucket) => {
+        bucket.units += quantity;
+        bucket.saleFee += saleFee;
+        if (isDiscounted) {
+          bucket.discountedGmv += itemRevenue;
+        }
+        if (isNotDelivered) {
+          bucket.notDeliveredGmv += itemRevenue;
+        }
+      };
+      incrementCurrencyMetric(currencyMetrics, currencyId, updateItemCurrencyMetrics);
+      incrementCurrencyMetric(dailyCurrencyMetrics, currencyId, updateItemCurrencyMetrics);
+      for (const flow of effectiveFlows) {
+        const flowAggregate = flowMetrics.get(flow);
+        if (flowAggregate) {
+          flowAggregate.units += quantity;
+          incrementCurrency(flowAggregate.sale_fee_by_currency, currencyId, 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);
+      const skuEconomicsAggregate = skuEconomics.get(skuKey) ?? {
+        seller_sku: sellerSku,
+        item_id: itemId,
+        title,
+        orders: 0,
+        units: 0,
+        cancelled_orders: 0,
+        refunded_orders: 0,
+        revenue_by_currency: {},
+        paid_revenue_by_currency: {},
+        sale_fee_by_currency: {},
+        refunded_amount_by_currency: {}
+      };
+      skuEconomicsAggregate.orders += 1;
+      skuEconomicsAggregate.units += quantity;
+      if (isCancelled) {
+        skuEconomicsAggregate.cancelled_orders += 1;
+      }
+      if (refundedAmount > 0) {
+        skuEconomicsAggregate.refunded_orders += 1;
+      }
+      incrementCurrency(skuEconomicsAggregate.revenue_by_currency, currencyId, itemRevenue);
+      incrementCurrency(skuEconomicsAggregate.paid_revenue_by_currency, currencyId, paidRevenueApprox);
+      incrementCurrency(skuEconomicsAggregate.sale_fee_by_currency, currencyId, saleFee);
+      incrementCurrency(skuEconomicsAggregate.refunded_amount_by_currency, currencyId, refundedAmountApprox);
+      skuEconomics.set(skuKey, skuEconomicsAggregate);
+    }
+    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] ?? "";
+  const revenueQuality = {
+    by_currency: sortedCurrencyMetrics(currencyMetrics, (bucket) => ({
+      gross_gmv: roundMoney(bucket.revenue),
+      paid_gmv: roundMoney(bucket.paidRevenue),
+      payment_total_paid_amount: roundMoney(bucket.paymentTotalPaid),
+      transaction_amount_total: roundMoney(bucket.transactionAmount),
+      refunded_amount_total: roundMoney(bucket.refundedAmount),
+      net_after_refunds: roundMoney(bucket.transactionAmount - bucket.refundedAmount),
+      cancelled_gmv: roundMoney(bucket.cancelledGmv),
+      cancelled_rate_by_orders: safeRate(bucket.cancelledOrders, bucket.orders),
+      cancelled_rate_by_gmv: safeRate(bucket.cancelledGmv, bucket.revenue),
+      paid_rate_by_gmv: safeRate(bucket.paidRevenue, bucket.revenue)
+    }))
+  };
+  const refundsCancellations = {
+    by_currency: sortedCurrencyMetrics(currencyMetrics, (bucket) => ({
+      refunded_amount_total: roundMoney(bucket.refundedAmount),
+      refunded_orders: bucket.refundedOrders,
+      refund_rate_by_orders: safeRate(bucket.refundedOrders, bucket.orders),
+      refund_rate_by_transaction_amount: safeRate(bucket.refundedAmount, bucket.transactionAmount),
+      cancelled_orders: bucket.cancelledOrders,
+      cancelled_gmv: roundMoney(bucket.cancelledGmv),
+      cancelled_rate_by_orders: safeRate(bucket.cancelledOrders, bucket.orders),
+      cancelled_rate_by_gmv: safeRate(bucket.cancelledGmv, bucket.revenue)
+    })),
+    cancel_group_breakdown: topBreakdownFromMap(cancelGroupCounts, ordersTotal),
+    cancel_code_breakdown: topBreakdownFromMap(cancelCodeCounts, ordersTotal),
+    cancel_requested_by_breakdown: topBreakdownFromMap(cancelRequestedByCounts, ordersTotal),
+    top_cancel_reasons: topAmountBreakdownFromMap(cancelReasonCounts, cancelReasonAmounts, ordersTotal)
+  };
+  const shippingAndDiscounts = {
+    by_currency: sortedCurrencyMetrics(currencyMetrics, (bucket) => ({
+      buyer_shipping_paid_total: roundMoney(bucket.shippingCost),
+      orders_with_shipping_cost: bucket.ordersWithShippingCost,
+      avg_shipping_paid_by_order_with_cost: roundMoney(bucket.shippingCost / Math.max(1, bucket.ordersWithShippingCost)),
+      shipping_cost_rate_on_paid_gmv: safeRate(bucket.shippingCost, bucket.paidRevenue),
+      coupon_amount_total: roundMoney(bucket.couponAmount),
+      payment_coupon_amount_total: roundMoney(bucket.paymentCouponAmount),
+      orders_with_coupon: bucket.ordersWithCoupon,
+      coupon_rate_by_orders: safeRate(bucket.ordersWithCoupon, bucket.orders),
+      coupon_rate_on_gmv: safeRate(bucket.couponAmount + bucket.paymentCouponAmount, bucket.revenue),
+      discounted_orders: bucket.discountedOrders,
+      discounted_order_rate: safeRate(bucket.discountedOrders, bucket.orders),
+      discounted_gmv: roundMoney(bucket.discountedGmv),
+      not_delivered_orders: bucket.notDeliveredOrders,
+      not_delivered_gmv: roundMoney(bucket.notDeliveredGmv),
+      not_delivered_rate_by_orders: safeRate(bucket.notDeliveredOrders, bucket.orders),
+      not_delivered_rate_by_gmv: safeRate(bucket.notDeliveredGmv, bucket.revenue)
+    }))
+  };
+  const dailyTrend = Array.from(dailyMetrics.entries()).sort(([left], [right]) => left.localeCompare(right)).map(([date, byCurrency]) => ({
+    date,
+    by_currency: sortedCurrencyMetrics(byCurrency, (bucket) => ({
+      orders: bucket.orders,
+      units: bucket.units,
+      revenue: roundMoney(bucket.revenue),
+      paid_revenue: roundMoney(bucket.paidRevenue),
+      cancelled_orders: bucket.cancelledOrders,
+      refunded_amount: roundMoney(bucket.refundedAmount),
+      avg_order_value: roundMoney(bucket.revenue / Math.max(1, bucket.orders))
+    }))
+  }));
+  const flowPerformance = Array.from(flowMetrics.values()).sort((left, right) => revenueSum(right.revenue_by_currency) - revenueSum(left.revenue_by_currency) || left.flow.localeCompare(right.flow)).slice(0, TOP_LIMIT).map((flow) => ({
+    flow: flow.flow,
+    orders: flow.orders,
+    units: flow.units,
+    revenue_by_currency: sortedCurrencyTotals(flow.revenue_by_currency),
+    paid_revenue_by_currency: sortedCurrencyTotals(flow.paid_revenue_by_currency),
+    sale_fee_by_currency: sortedCurrencyTotals(flow.sale_fee_by_currency),
+    cancelled_orders: flow.cancelled_orders,
+    cancelled_rate: safeRate(flow.cancelled_orders, flow.orders),
+    fee_rate_by_currency: Object.fromEntries(
+      Object.keys(flow.revenue_by_currency).sort((left, right) => left.localeCompare(right)).map((currencyId) => [currencyId, safeRate(flow.sale_fee_by_currency[currencyId] ?? 0, flow.revenue_by_currency[currencyId] ?? 0)])
+    )
+  }));
+  const skuUnitEconomics = Array.from(skuEconomics.values()).sort((left, right) => revenueSum(right.revenue_by_currency) - revenueSum(left.revenue_by_currency) || left.seller_sku.localeCompare(right.seller_sku)).slice(0, TOP_LIMIT).map((sku) => ({
+    seller_sku: sku.seller_sku,
+    item_id: sku.item_id,
+    title: sku.title,
+    orders: sku.orders,
+    units: sku.units,
+    revenue_by_currency: sortedCurrencyTotals(sku.revenue_by_currency),
+    paid_revenue_by_currency: sortedCurrencyTotals(sku.paid_revenue_by_currency),
+    sale_fee_by_currency: sortedCurrencyTotals(sku.sale_fee_by_currency),
+    refunded_amount_by_currency: sortedCurrencyTotals(sku.refunded_amount_by_currency),
+    avg_unit_price_by_currency: Object.fromEntries(
+      Object.keys(sku.revenue_by_currency).sort((left, right) => left.localeCompare(right)).map((currencyId) => [currencyId, roundMoney((sku.revenue_by_currency[currencyId] ?? 0) / Math.max(1, sku.units))])
+    ),
+    fee_rate_by_currency: Object.fromEntries(
+      Object.keys(sku.revenue_by_currency).sort((left, right) => left.localeCompare(right)).map((currencyId) => [currencyId, safeRate(sku.sale_fee_by_currency[currencyId] ?? 0, sku.revenue_by_currency[currencyId] ?? 0)])
+    ),
+    cancelled_orders: sku.cancelled_orders,
+    cancelled_rate: safeRate(sku.cancelled_orders, sku.orders),
+    refunded_orders: sku.refunded_orders,
+    refund_rate: safeRate(sku.refunded_orders, sku.orders)
+  }));
+  const feeDiagnostics = {
+    sale_fee_assumption: "order_items.sale_fee is used as returned by MercadoLibre and is not multiplied by quantity yet.",
+    multi_unit_item_lines: multiUnitItemLines,
+    multi_unit_sale_fee_observations: multiUnitSaleFeeObservations,
+    needs_sale_fee_granularity_validation: true
+  };
+  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,
+    revenue_quality: revenueQuality,
+    refunds_cancellations: refundsCancellations,
+    shipping_and_discounts: shippingAndDiscounts,
+    daily_trend: dailyTrend,
+    flow_performance: flowPerformance,
+    sku_unit_economics: skuUnitEconomics,
+    fee_diagnostics: feeDiagnostics,
+    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 requestedWindowEndOffset = params.effectiveOffset + params.effectiveLimit * params.pagesRequested;
+  const nextOffset = params.responseMode === "orders_chunk" ? requestedWindowEndOffset : params.effectiveOffset + params.returned;
+  const hasMoreOrders = nextOffset < params.total;
+  const universeFullyFetched = params.responseMode === "calculations" && params.pagesFailed === 0 && params.returned >= params.total;
+  let continuation = "No more pages for this query.";
+  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 = params.responseMode === "orders_chunk" ? `Se recuperaron paginas parciales. Reintentar primero la misma tool con responseMode="orders_chunk", offset=${params.failedOffsets[0]} y limit=${params.effectiveLimit}. Offsets fallidos: ${offsets}${moreOffsets}. Luego continuar con offset=${nextOffset} si hace falta.` : `Calculos parciales por paginas fallidas. Reintentar la misma tool con responseMode="calculations". Offsets fallidos: ${offsets}${moreOffsets}.`;
+  } else if (params.responseMode === "orders_chunk" && hasMoreOrders) {
+    continuation = `Para continuar trayendo ordenes, volver a invocar meli_get_orders_summary con los mismos filtros, responseMode="orders_chunk", offset=${nextOffset} y limit=${params.effectiveLimit}. Repetir hasta has_more=false.`;
+  } else if (params.responseMode === "calculations") {
+    continuation = 'Calculos completos. Si el usuario pide detalle de ordenes, invocar la misma tool con responseMode="orders_chunk", offset=0 y limit=50.';
+  }
+  return {
+    total: params.total,
+    limit: params.effectiveLimit,
+    offset: params.effectiveOffset,
+    returned: params.returned,
+    has_more: params.responseMode === "orders_chunk" ? hasMoreOrders || params.pagesFailed > 0 : params.pagesFailed > 0,
+    next_offset: params.responseMode === "orders_chunk" && hasMoreOrders ? nextOffset : void 0,
+    continuation,
+    fetch_mode: params.responseMode === "orders_chunk" ? "orders_chunk" : "full_calculations",
+    pages_per_call_limit: params.responseMode === "orders_chunk" ? ORDER_DETAIL_MAX_PAGES_PER_CALL : void 0,
+    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 +939,9 @@ 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).")
+  responseMode: z.enum(["calculations", "orders_chunk"]).optional().default("calculations").describe("Response mode. calculations (default) fetches all matching orders internally and returns only aggregate KPIs. orders_chunk returns compact order rows for up to 15 MercadoLibre pages and includes continuation metadata."),
+  offset: z.number().int().min(0).max(5e3).optional().describe("Starting offset for responseMode=orders_chunk. Use metadata.next_offset to continue."),
+  limit: z.number().int().min(1).max(50).optional().describe("MercadoLibre page size for responseMode=orders_chunk (1-50). Defaults to 50.")
 });
 async function meliGetOrdersSummaryHandler(params) {
   try {
@@ -37,6 +950,9 @@ async function meliGetOrdersSummaryHandler(params) {
       return profileResolution.response;
     }
     const profileId = profileResolution.value.profileId;
+    const responseMode = params.responseMode ?? "calculations";
+    const requestedLimit = responseMode === "orders_chunk" ? params.limit ?? DEFAULT_ORDER_DETAIL_PAGE_LIMIT : DEFAULT_ORDER_DETAIL_PAGE_LIMIT;
+    const requestedOffset = responseMode === "orders_chunk" ? params.offset ?? 0 : 0;
     const response = await searchMercadoLibreOrders(profileId, {
       seller: "",
       from: params.startDate,
@@ -44,54 +960,108 @@ async function meliGetOrdersSummaryHandler(params) {
       status: params.status,
       q: params.q,
       sort: params.sort,
-      offset: params.offset,
-      limit: params.limit
+      offset: requestedOffset,
+      limit: requestedLimit
     });
-    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 effectiveLimit = paging.limit || requestedLimit || baseOrders.length;
+    const effectiveOffset = paging.offset || requestedOffset || 0;
+    const maxPagesForResponse = responseMode === "orders_chunk" ? ORDER_DETAIL_MAX_PAGES_PER_CALL : Infinity;
+    const allOrders = [...baseOrders];
+    const failedPages = [];
+    let pagesRequested = 1;
+    let pagesSucceeded = 1;
+    if (effectiveLimit > 0 && paging.total > baseOrders.length) {
+      const nextOffsets = [];
+      const maxPagesRemaining = Math.max(0, maxPagesForResponse - 1);
+      let pagesAdded = 0;
+      for (let nextOffset = effectiveOffset + effectiveLimit; nextOffset < paging.total; nextOffset += effectiveLimit) {
+        if (responseMode === "orders_chunk" && pagesAdded >= maxPagesRemaining) {
+          break;
+        }
+        nextOffsets.push(nextOffset);
+        pagesAdded += 1;
+      }
+      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 = responseMode === "orders_chunk" ? allOrders.map((order) => formatCompactOrder(order, metricsByCurrency)) : [];
+    if (responseMode === "calculations") {
+      for (const order of allOrders) {
+        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 returned = responseMode === "orders_chunk" ? compactOrders.length : allOrders.length;
+    const metadata = buildOrdersSummaryMetadata({
+      total: paging.total,
+      effectiveLimit,
+      effectiveOffset,
+      returned,
+      responseMode,
+      pagesRequested,
+      pagesSucceeded,
+      pagesFailed: failedPages.length,
+      failedOffsets: failedPages.map((failure) => failure.offset)
+    });
+    const calculations = responseMode === "calculations" ? buildCalculations(allOrders, metadata, failedPages) : void 0;
     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: responseMode === "orders_chunk" ? {
+          ...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_schema: responseMode === "orders_chunk" ? ordersSchema : void 0,
+        orders: responseMode === "orders_chunk" ? compactOrders : void 0,
+        calculations,
+        failed_pages: failedPages.length > 0 ? failedPages : void 0
       })
     );
   } catch (err) {