@salesforce/b2c-tooling-sdk / operations/metrics / resolveMetricsWindow

Function: resolveMetricsWindow()

resolveMetricsWindow(input, now): ResolvedMetricsWindow

Defined in: packages/b2c-tooling-sdk/src/operations/metrics/index.ts:330

Resolves from/to/window inputs into the concrete bounds to send to the Metrics API. This is the shared resolver for the CLI metrics get command and the MCP metrics_get tool, so both share identical, tested semantics.

The resolver always produces an explicit from+to pair. The Metrics API pairs a request that omits to with its own now and enforces a 24-hour maximum window, so an open-ended from older than 24 hours always fails; to make the behavior predictable, any bound the caller leaves open is filled from the 24-hour default window (see METRICS_DEFAULT_WINDOW_MS) rather than relying on the server's implicit end.

The window duration makes fixed-width lookbacks easy without hand-computing a second timestamp — e.g. "a 1-hour window starting 7 days ago" is {from: '7d', window: '1h'}. Resolution rules:

• from + to — used as given; window must NOT also be set. An explicit range wider than the 24-hour maximum is still sent as-is, leaving the API to return its own error.
• from + window — to = from + window.
• to + window — from = to - window.
• window only — the last window: to = now, from = now - window.
• from only — a 24-hour window forward from from: to = min(from + 24h, now).
• to only — a 24-hour window back from to: from = to - 24h.
• nothing — the last 24 hours: to = now, from = now - 24h.

Bounds filled from the 24-hour default (the last three rules) set ResolvedMetricsWindow.defaultedWindow. Validation is structural (over-specification and from after to). Additionally, a from that lands at or beyond the 30-day retention floor is clamped forward to now - 30 days + margin (see METRICS_RETENTION_SAFETY_MARGIN_MS) so requests like --from 30d are not rejected by the server's own slightly-later clock; the clamp is applied before deriving the companion bound so the window width is preserved, only ever moves from toward now, and is reported via ResolvedMetricsWindow.clampedFrom.

Parameters

input

MetricsWindowInput = {}

The raw from/to/window inputs

now

Date = ...

Reference time for relative bounds, default/window modes, and the retention clamp (defaults to the current time; injectable for deterministic tests)

Returns

ResolvedMetricsWindow

The resolved bounds plus ISO/epoch-second echoes and clamp/default flags

Throws

TypeError if a bound or the window string is unparseable

Throws

RangeError if all three are supplied, or the resolved from is after to

Example

// A 1-hour window starting 7 days ago:
const w = resolveMetricsWindow({from: '7d', window: '1h'});
await getScapiMetrics(client, tenantId, {from: w.from, to: w.to});