feat(vtex): add Sales Performance analytics tools (cards, trend, table)

[guitavano]

What

Adds three read-only MCP tools that wrap the VTEX admin "Performance de vendas" (Sales Performance) dashboard, under /api/analytics/consumption/:

Tool	Endpoint	Returns
VTEX_GET_SALES_PERFORMANCE_SUMMARY	sp-cards	KPI summary cards (reference vs compare window)
VTEX_GET_SALES_PERFORMANCE_TREND	sp-graphic	single-metric time series (hour/day/week/month)
VTEX_GET_SALES_PERFORMANCE_TABLE	sp-item-detail-table	metrics broken down & ranked by a dimension

sp-item-detail-table is the endpoint originally requested. The other two round out the same dashboard and reuse the same helpers.

How

Follows the existing custom/home-analytics.ts pattern and reuses fetchAnalyticsConsumption / resolveAnalyticsDateRange (VtexId session-token auth, literal query strings so ISO colons aren't encoded). Registered in server/tools/index.ts.

Payload possibilities (reverse-engineered live from the dashboard)

• 20 metric values (metric1..metric5): capturedRevenue, approvedRevenue, invoicedRevenue, canceledRevenue, captured/approved/invoiced/canceledOrders, …Items, …AverageTicket, itemsPerOrder, packagesPerOrder, averageSellingPrice, averageShippingPrice.
• 17 groupByDim dimensions: productName (default), category, brand, marketplaceName, deliveryMethod, shippingOption, destinationCity, destinationState, sellerName, paymentMethod, ownershipProduct, campaign, coupon, tradePolicy, promotion, utmCampaign, utmSource.
• sortType: percentage | variation (the UI "Representativa" toggle is client-side only, not an API value).
• sortOrientation: DESC | ASC; plus itemsPerPage / startIndex pagination.
• The dashboard's three "%" metrics (approved-orders %, invoiced-orders %, order breakage %) are computed client-side and are not valid API params (return 500) — deliberately excluded from the enum.

Full spec captured in .context/sales-performance-api-spec.md (gitignored).

Test

• bun test server/tools/custom/sales-performance.test.ts → 4 pass (URL-shape assertions, incl. no %3A encoding).
• bun test server/tools/custom/ → 35 pass.
• bun run check → no new type errors from these files (pre-existing errors are inside the @decocms/runtime dependency).

🤖 Generated with Claude Code

---

Summary by cubic

Adds three read-only VTEX analytics tools that expose the admin Sales Performance dashboard (KPI cards, single-metric trend, ranked breakdown table). This enables programmatic access via the existing analytics session flow without changing existing tools.

• Review notes
  • Tools → endpoints: VTEX_GET_SALES_PERFORMANCE_SUMMARY → sp-cards, VTEX_GET_SALES_PERFORMANCE_TREND → sp-graphic, VTEX_GET_SALES_PERFORMANCE_TABLE → sp-item-detail-table.
  • Reuses fetchAnalyticsConsumption, resolveAnalyticsDateRange, and the shared URL builder; timestamps stay literal (no encoded colons). Auth uses VtexId session from App Key/Token.
  • Input schemas enumerate 20 metrics and 17 groupBy dimensions; trend supports hour|day|week|month; table supports sortType (percentage|variation), sortOrientation, and pagination.
  • Registered in vtex/server/tools/index.ts. Tests assert URL shape and metric mapping (bun test passes).
  • No breaking changes or migrations. Consumers can call the new tool IDs directly.

^{Written for commit 7194419. Summary will update on new commits.}