PM-6364 Sales report date range filters and snapshot-wide summary

[jmgasper]

Server-side half of PM-6364. Pairs with platform-ui#2319, which adds the Sales Portal controls.

Both GET /v6/reports/sales and GET /v6/reports/win/sales get the new parameters and response field; authorization is unchanged.

Why this is server-side

The endpoint paginates over the Salesforce snapshot, so a client only ever holds one page of rows. Filtering by date in the browser would make the record count and every total describe the visible page rather than the result. The range and the aggregates are applied over the whole received snapshot before pagination, exactly like the existing search and column filters.

Date range

Parameter	Meaning
dateColumn	ID of a date/datetime column, such as Created Date or Close Date
dateFrom, dateTo	Inclusive YYYY-MM-DD bounds; either or both, and both require dateColumn

Comparison uses each cell's underlying Salesforce value, never its localized label: a datetime keeps the report's own offset, so its day matches the day the report displays. A row whose date cell is null or unparseable cannot satisfy a range and is excluded rather than counted. dateColumn alone is a no-op, which lets a client keep the field selected while the range is empty.

400 covers a bound without dateColumn, dateFrom after dateTo, a dateColumn that is not a date column, and any bound that is not a real calendar day — 2026-02-30 and non-leap 2027-02-29 are rejected, and datetimes are not accepted as bounds.

summary

Describes every matching row, not the returned page:

• recordCount — always equal to total
• amounts[] — per currency/double column: total, contributing count, mixedCurrency, and currencyCode when contributing rows agree
• groups[] — up to three category columns broken into buckets of {label, count, total}, ordered by total then count, capped at 25 with the remainder in otherBuckets

mixedCurrency separates a genuine cross-currency sum, which clients must not present as one currency, from a single-currency org where Salesforce returns bare numbers. Totals round to cents so repeated floating-point addition cannot leak artifacts such as 0.30000000000000004 into displayed currency.

Aggregates cover received rows only, so allData: false limits them exactly as it limits total.

Compatibility

Additive. Existing callers, including WIN, see identical rows, total and pagination; summary is a new field and the date parameters are optional.

Verification

• npx jest src/reports/sales — 38 passed, including new coverage for inclusive and open-ended ranges, underlying-value comparison with a datetime offset, rows excluded for want of a date, combination with search and column filters, every 400 case, and aggregates under pagination and mixed currencies
• npx eslint src/reports/sales/**/*.ts and npx tsc --noEmit — clean

🤖 Generated with Claude Code