@byline/host-tanstack-start 4.14.1 → 4.16.0

package/src/integrations/analytics-agent.tsx

@@ -0,0 +1,91 @@
+'use client'
+
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type React from 'react'
+import { useEffect, useRef } from 'react'
+import { useRouterState } from '@tanstack/react-router'
+
+import { ANALYTICS_NAVIGATION_EVENT, ANALYTICS_STOP_EVENT } from '@byline/analytics-agent'
+
+let pendingStopTimer: number | undefined
+
+export interface AnalyticsAgentProps {
+  /** Application-owned same-origin route that receives browser events. */
+  endpoint: string
+  src?: string
+  cdnHosts?: readonly string[]
+  downloadExtensions?: readonly string[]
+  ignoredPathPrefixes?: readonly string[]
+  countSearchChanges?: boolean
+  countHashChanges?: boolean
+}
+
+/** Render the standalone script and bridge only committed router locations into it. */
+export function AnalyticsAgent({
+  endpoint,
+  src = '/b.js',
+  cdnHosts,
+  downloadExtensions,
+  ignoredPathPrefixes,
+  countSearchChanges = false,
+  countHashChanges = false,
+}: AnalyticsAgentProps): React.JSX.Element {
+  return (
+    <>
+      <script
+        defer
+        src={src}
+        data-endpoint={endpoint}
+        data-cdn-hosts={boundedAttribute(cdnHosts)}
+        data-download-extensions={boundedAttribute(downloadExtensions)}
+        data-ignore-prefixes={boundedAttribute(ignoredPathPrefixes)}
+        data-count-search={countSearchChanges ? 'true' : undefined}
+        data-count-hash={countHashChanges ? 'true' : undefined}
+      />
+      <AnalyticsNavigationBridge />
+    </>
+  )
+}
+
+function AnalyticsNavigationBridge(): null {
+  const href = useRouterState({ select: (state) => state.location.href })
+  const previousHref = useRef<string | undefined>(undefined)
+
+  useEffect(() => {
+    const previous = previousHref.current
+    previousHref.current = href
+    if (previous == null || previous === href) return
+    document.dispatchEvent(new CustomEvent(ANALYTICS_NAVIGATION_EVENT, { detail: href }))
+  }, [href])
+
+  useEffect(() => {
+    if (pendingStopTimer !== undefined) {
+      window.clearTimeout(pendingStopTimer)
+      pendingStopTimer = undefined
+    }
+
+    return () => {
+      // React Strict Mode immediately re-runs this effect after its simulated
+      // cleanup. Deferring the stop lets that setup cancel it, while a real
+      // consent-driven unmount leaves the timer in place.
+      pendingStopTimer = window.setTimeout(() => {
+        pendingStopTimer = undefined
+        document.dispatchEvent(new Event(ANALYTICS_STOP_EVENT))
+      }, 0)
+    }
+  }, [])
+
+  return null
+}
+
+function boundedAttribute(values: readonly string[] | undefined): string | undefined {
+  if (values == null || values.length === 0) return undefined
+  return values.slice(0, 64).join(',').slice(0, 2_048)
+}

package/src/integrations/analytics-events.test.node.ts

@@ -0,0 +1,245 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  createAnalyticsEventHandler,
+  localAnalyticsRequestContext,
+  trustedAnalyticsHeaders,
+} from './analytics-events.js'
+
+describe('createAnalyticsEventHandler', () => {
+  it('passes only explicit trusted request facts and emits no CORS response header', async () => {
+    const ingest = vi.fn().mockResolvedValue({ status: 202, accepted: true })
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext: trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+        countryHeader: 'x-byline-client-country',
+      }),
+      analytics: () => ({ ingest }),
+    })
+    const body = JSON.stringify({ v: 1, kind: 'page', path: '/', ref: '' })
+    const response = await handler(
+      new Request('https://www.example.com/api/events', {
+        method: 'POST',
+        body,
+        headers: {
+          origin: 'https://www.example.com',
+          'user-agent': 'Mozilla/5.0',
+          'x-byline-client-country': 'TH',
+          'x-byline-client-ip': '203.0.113.10',
+          'x-forwarded-for': '198.51.100.99',
+        },
+      })
+    )
+
+    expect(response.status).toBe(202)
+    expect(response.headers.has('access-control-allow-origin')).toBe(false)
+    expect(ingest).toHaveBeenCalledOnce()
+    expect(ingest.mock.calls[0]?.[0]).toMatchObject({
+      clientIp: '203.0.113.10',
+      country: 'TH',
+      origin: 'https://www.example.com',
+    })
+    expect(ingest.mock.calls[0]?.[0]).not.toHaveProperty('xForwardedFor')
+  })
+
+  it('stops reading an oversized stream and reports the contract body-size rejection', async () => {
+    const ingest = vi.fn().mockResolvedValue({ status: 400, accepted: false, reason: 'body-size' })
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext: trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+      }),
+      analytics: () => ({ ingest }),
+    })
+
+    const response = await handler(
+      new Request('https://www.example.com/api/events', {
+        method: 'POST',
+        body: 'x'.repeat(1_025),
+        headers: { 'x-byline-client-ip': '203.0.113.10' },
+      })
+    )
+
+    expect(response.status).toBe(400)
+    const received = ingest.mock.calls.at(0)?.at(0)
+    expect(received).toBeDefined()
+    expect((received?.body as Uint8Array | undefined)?.byteLength).toBe(1_025)
+  })
+
+  it('uses an explicit development identity only when the trusted header is absent', async () => {
+    const ingest = vi.fn().mockResolvedValue({ status: 202, accepted: true })
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext: trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+        fallback: { clientIp: 'vite-development' },
+      }),
+      analytics: () => ({ ingest }),
+    })
+    const body = JSON.stringify({ v: 1, kind: 'page', path: '/', ref: '' })
+
+    await handler(
+      new Request('http://localhost:5173/api/events', {
+        method: 'POST',
+        body,
+      })
+    )
+    await handler(
+      new Request('http://localhost:5173/api/events', {
+        method: 'POST',
+        body,
+        headers: { 'x-byline-client-ip': '203.0.113.10' },
+      })
+    )
+
+    expect(ingest.mock.calls[0]?.[0].clientIp).toBe('vite-development')
+    expect(ingest.mock.calls[1]?.[0].clientIp).toBe('203.0.113.10')
+  })
+
+  it.each(['127.0.0.1', '::1', '::ffff:127.0.0.1'])(
+    'accepts direct loopback identity %s for a localhost production preview',
+    async (clientIp) => {
+      const resolver = localAnalyticsRequestContext({ resolveClientIp: () => clientIp })
+
+      await expect(resolver(new Request('http://localhost:5173/api/events'))).resolves.toEqual({
+        clientIp,
+      })
+    }
+  )
+
+  it('requires both a loopback URL and a loopback direct peer', async () => {
+    const loopbackPeer = localAnalyticsRequestContext({ resolveClientIp: () => '127.0.0.1' })
+    const publicPeer = localAnalyticsRequestContext({ resolveClientIp: () => '203.0.113.10' })
+
+    await expect(loopbackPeer(new Request('https://www.example.com/api/events'))).resolves.toEqual(
+      {}
+    )
+    await expect(publicPeer(new Request('http://localhost:5173/api/events'))).resolves.toEqual({})
+  })
+
+  it('prefers the trusted proxy header over a local fallback resolver', async () => {
+    const resolver = trustedAnalyticsHeaders({
+      clientIpHeader: 'x-byline-client-ip',
+      fallback: localAnalyticsRequestContext({ resolveClientIp: () => '127.0.0.1' }),
+    })
+
+    await expect(
+      resolver(
+        new Request('http://localhost:5173/api/events', {
+          headers: { 'x-byline-client-ip': '203.0.113.10' },
+        })
+      )
+    ).resolves.toEqual({ clientIp: '203.0.113.10', country: undefined })
+  })
+
+  it('rejects an empty development identity', () => {
+    expect(() =>
+      trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+        fallback: { clientIp: ' ' },
+      })
+    ).toThrow('fallback.clientIp must contain 1 to 255 characters')
+  })
+
+  it('rejects an invalid configured trust header before serving requests', () => {
+    expect(() =>
+      trustedAnalyticsHeaders({
+        clientIpHeader: 'not a header:',
+      })
+    ).toThrow('valid HTTP header name')
+  })
+
+  it('accepts deployment facts from a host resolver without assuming a proxy', async () => {
+    const ingest = vi.fn().mockResolvedValue({ status: 202, accepted: true })
+    const resolveRequestContext = vi.fn().mockReturnValue({
+      clientIp: 'direct-platform-client',
+      country: 'NZ',
+    })
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext,
+      analytics: () => ({ ingest }),
+    })
+    const request = new Request('https://www.example.com/telemetry/events', {
+      method: 'POST',
+      body: JSON.stringify({ v: 1, kind: 'page', path: '/', ref: '' }),
+    })
+
+    expect((await handler(request)).status).toBe(202)
+    expect(resolveRequestContext).toHaveBeenCalledWith(request)
+    expect(ingest.mock.calls[0]?.[0]).toMatchObject({
+      clientIp: 'direct-platform-client',
+      country: 'NZ',
+    })
+  })
+
+  it('contains persistence failures as an empty 503 and logs no request facts', async () => {
+    const visitorHash = 'a'.repeat(64)
+    const error = Object.assign(new Error('new row violates analytics constraint'), {
+      code: '23514',
+      detail: `Failing row contains visitor ${visitorHash}`,
+    })
+    const ingest = vi.fn().mockRejectedValue(error)
+    const logError = vi.fn()
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext: trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+      }),
+      analytics: () => ({ ingest }),
+      logger: () => ({ error: logError }),
+    })
+
+    const response = await handler(
+      new Request('https://www.example.com/api/events', {
+        method: 'POST',
+        body: JSON.stringify({ v: 1, kind: 'page', path: '/', ref: '' }),
+        headers: {
+          origin: 'https://www.example.com',
+          'user-agent': 'Mozilla/5.0',
+          'x-byline-client-ip': '203.0.113.10',
+        },
+      })
+    )
+
+    expect(response.status).toBe(503)
+    expect(await response.text()).toBe('')
+    expect(logError).toHaveBeenCalledWith(
+      { errorCode: '23514' },
+      '[analytics] event persistence failed'
+    )
+    const logged = JSON.stringify(logError.mock.calls)
+    expect(logged).not.toContain('203.0.113.10')
+    expect(logged).not.toContain(visitorHash)
+    expect(logged).not.toContain(error.message)
+    expect(logged).not.toContain(error.detail)
+  })
+
+  it('does not trust arbitrary persistence error codes', async () => {
+    const ingest = vi.fn().mockRejectedValue({ code: 'unsafe value: 203.0.113.10' })
+    const logError = vi.fn()
+    const handler = createAnalyticsEventHandler({
+      resolveRequestContext: trustedAnalyticsHeaders({
+        clientIpHeader: 'x-byline-client-ip',
+      }),
+      analytics: () => ({ ingest }),
+      logger: () => ({ error: logError }),
+    })
+
+    await handler(
+      new Request('https://www.example.com/api/events', {
+        method: 'POST',
+        body: JSON.stringify({ v: 1, kind: 'page', path: '/', ref: '' }),
+      })
+    )
+
+    expect(logError).toHaveBeenCalledWith(
+      { errorCode: 'UNKNOWN' },
+      '[analytics] event persistence failed'
+    )
+  })
+})

package/src/integrations/analytics-events.ts

@@ -0,0 +1,224 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { ANALYTICS_MAX_BODY_BYTES, type Analytics, getAnalytics } from '@byline/analytics'
+import { type BylineLogger, getLogger } from '@byline/core'
+
+export interface AnalyticsEventHandlerOptions {
+  /** Host-owned resolver for deployment-specific, request-scoped network facts. */
+  resolveRequestContext: AnalyticsRequestContextResolver
+  /** Test/embedding seam; production resolves the registered installation runtime. */
+  analytics?: () => Pick<Analytics, 'ingest'>
+  /** Test/embedding seam; production resolves the initialized application logger. */
+  logger?: () => Pick<BylineLogger, 'error'>
+}
+
+export interface AnalyticsRequestContext {
+  clientIp?: string | null
+  country?: string | null
+}
+
+export type AnalyticsRequestContextResolver = (
+  request: Request
+) => AnalyticsRequestContext | Promise<AnalyticsRequestContext>
+
+export interface LocalAnalyticsRequestContextOptions {
+  /** Resolve the direct peer address from the host runtime, without forwarded headers. */
+  resolveClientIp: (
+    request: Request
+  ) => string | null | undefined | Promise<string | null | undefined>
+  /** Explicit development-only identity for runtimes that expose no peer address. */
+  developmentFallbackClientIp?: string
+}
+
+export interface TrustedAnalyticsHeadersOptions {
+  /** Header overwritten by the trusted reverse proxy with the normalized client address. */
+  clientIpHeader: string
+  /** Optional header overwritten by the trusted edge with an ISO country code. */
+  countryHeader?: string
+  /** Explicit context or resolver used only when a trusted header is absent. */
+  fallback?: AnalyticsRequestContext | AnalyticsRequestContextResolver
+}
+
+/**
+ * Resolve an identity for a server reached directly through a loopback URL.
+ * Both the URL and the direct peer address must be loopback. This is safe for
+ * a directly reached local server. A same-host reverse proxy also appears as
+ * a loopback peer, however, so do not expose this fallback through a public
+ * proxy where a client can select the Host header.
+ */
+export function localAnalyticsRequestContext(
+  options: LocalAnalyticsRequestContextOptions
+): AnalyticsRequestContextResolver {
+  const developmentFallbackClientIp =
+    options.developmentFallbackClientIp == null
+      ? undefined
+      : validateFact(options.developmentFallbackClientIp, 'developmentFallbackClientIp', 255)
+
+  return async (request) => {
+    const clientIp = await options.resolveClientIp(request)
+    if (isLoopbackHostname(new URL(request.url).hostname) && isLoopbackAddress(clientIp)) {
+      return { clientIp: validateFact(clientIp, 'resolved clientIp', 255) }
+    }
+    return developmentFallbackClientIp == null ? {} : { clientIp: developmentFallbackClientIp }
+  }
+}
+
+/**
+ * Resolve network facts from headers owned and overwritten by a trusted proxy.
+ * This helper does not establish that trust: the deployment must prevent a
+ * client from selecting the configured header values or bypassing the proxy.
+ */
+export function trustedAnalyticsHeaders(
+  options: TrustedAnalyticsHeadersOptions
+): AnalyticsRequestContextResolver {
+  const clientIpHeader = validateHeaderName(options.clientIpHeader, 'clientIpHeader')
+  const countryHeader =
+    options.countryHeader == null
+      ? undefined
+      : validateHeaderName(options.countryHeader, 'countryHeader')
+  const fallback =
+    typeof options.fallback === 'function' ? options.fallback : validateFallback(options.fallback)
+
+  return async (request) => {
+    const fallbackContext =
+      typeof fallback === 'function' ? validateFallback(await fallback(request)) : fallback
+    return {
+      clientIp: request.headers.get(clientIpHeader)?.trim() || fallbackContext?.clientIp,
+      country:
+        (countryHeader == null ? null : request.headers.get(countryHeader)?.trim()) ||
+        fallbackContext?.country,
+    }
+  }
+}
+
+export function createAnalyticsEventHandler(
+  options: AnalyticsEventHandlerOptions
+): (request: Request) => Promise<Response> {
+  const resolveAnalytics = options.analytics ?? getAnalytics
+
+  return async (request) => {
+    const body = await readBoundedBody(request, ANALYTICS_MAX_BODY_BYTES)
+    try {
+      const requestContext = await options.resolveRequestContext(request)
+      const result = await resolveAnalytics().ingest({
+        method: request.method,
+        body: body ?? new Uint8Array(ANALYTICS_MAX_BODY_BYTES + 1),
+        origin: request.headers.get('origin'),
+        referer: request.headers.get('referer'),
+        userAgent: request.headers.get('user-agent'),
+        secPurpose: request.headers.get('sec-purpose'),
+        xPurpose: request.headers.get('x-purpose'),
+        clientIp: requestContext.clientIp,
+        country: requestContext.country,
+      })
+
+      return analyticsResponse(result.status)
+    } catch (error) {
+      const logger = options.logger?.() ?? getLogger()
+      logger.error({ errorCode: safeErrorCode(error) }, '[analytics] event persistence failed')
+      return analyticsResponse(503)
+    }
+  }
+}
+
+function safeErrorCode(error: unknown): string {
+  if (error == null || typeof error !== 'object' || !('code' in error)) return 'UNKNOWN'
+  const code = error.code
+  return typeof code === 'string' && /^[a-z0-9_-]{1,64}$/iu.test(code) ? code : 'UNKNOWN'
+}
+
+function analyticsResponse(status: number): Response {
+  return new Response(null, {
+    status,
+    headers: { 'cache-control': 'no-store' },
+  })
+}
+
+async function readBoundedBody(request: Request, limit: number): Promise<Uint8Array | null> {
+  const declaredLength = Number(request.headers.get('content-length'))
+  if (Number.isFinite(declaredLength) && declaredLength > limit) return null
+  if (request.body == null) return new Uint8Array()
+
+  const reader = request.body.getReader()
+  const chunks: Uint8Array[] = []
+  let length = 0
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      length += value.byteLength
+      if (length > limit) {
+        await reader.cancel()
+        return null
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+
+  const body = new Uint8Array(length)
+  let offset = 0
+  for (const chunk of chunks) {
+    body.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return body
+}
+
+function validateHeaderName(value: string, label: string): string {
+  const normalized = value.trim().toLowerCase()
+  if (!/^[!#$%&'*+.^_`|~0-9a-z-]+$/u.test(normalized)) {
+    throw new Error(`analytics ${label} must be a valid HTTP header name`)
+  }
+  return normalized
+}
+
+function validateFallback(
+  value: AnalyticsRequestContext | undefined
+): AnalyticsRequestContext | undefined {
+  if (value == null) return undefined
+  return {
+    ...(value.clientIp == null
+      ? {}
+      : { clientIp: validateFact(value.clientIp, 'fallback.clientIp', 255) }),
+    ...(value.country == null
+      ? {}
+      : { country: validateFact(value.country, 'fallback.country', 16) }),
+  }
+}
+
+function validateFact(value: string, label: string, maxLength: number): string {
+  const normalized = value.trim()
+  if (normalized.length === 0 || normalized.length > maxLength) {
+    throw new Error(`analytics ${label} must contain 1 to ${maxLength} characters`)
+  }
+  return normalized
+}
+
+function isLoopbackHostname(value: string): boolean {
+  const normalized = stripIpv6Brackets(value.toLowerCase())
+  return (
+    normalized === 'localhost' || normalized.endsWith('.localhost') || isLoopbackAddress(normalized)
+  )
+}
+
+function isLoopbackAddress(value: string | null | undefined): value is string {
+  if (value == null) return false
+  const normalized = stripIpv6Brackets(value.trim().toLowerCase())
+  return (
+    normalized === '::1' ||
+    /^127(?:\.\d{1,3}){3}$/u.test(normalized) ||
+    /^::ffff:127(?:\.\d{1,3}){3}$/u.test(normalized)
+  )
+}
+
+function stripIpv6Brackets(value: string): string {
+  return value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value
+}

package/src/integrations/serve-analytics-agent.test.node.ts

@@ -0,0 +1,20 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { serveAnalyticsAgent } from './serve-analytics-agent.js'
+
+describe('serveAnalyticsAgent', () => {
+  it('serves the bundled standalone collector with bounded first-party caching', async () => {
+    const response = serveAnalyticsAgent()
+    expect(response.headers.get('content-type')).toBe('text/javascript; charset=utf-8')
+    expect(response.headers.get('cache-control')).toBe('public, max-age=3600, must-revalidate')
+    expect(await response.text()).toContain('text/plain')
+  })
+})

package/src/integrations/serve-analytics-agent.ts

@@ -0,0 +1,19 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { ANALYTICS_AGENT_SOURCE } from '@byline/analytics-agent/source'
+
+export function serveAnalyticsAgent(): Response {
+  return new Response(ANALYTICS_AGENT_SOURCE, {
+    headers: {
+      'cache-control': 'public, max-age=3600, must-revalidate',
+      'content-type': 'text/javascript; charset=utf-8',
+      'x-content-type-options': 'nosniff',
+    },
+  })
+}

package/src/routes/analytics-range.ts

@@ -0,0 +1,55 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { AnalyticsDashboardPeriod } from '@byline/admin/analytics'
+
+const UTC_DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/u
+
+export function buildAnalyticsDashboardRange(
+  period: AnalyticsDashboardPeriod,
+  now = new Date(),
+  earliestReportDay: string | null = null
+): { from: string; to: string } {
+  const to = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()))
+
+  if (period === 'ytd') {
+    return {
+      from: formatUtcDay(new Date(Date.UTC(to.getUTCFullYear(), 0, 1))),
+      to: formatUtcDay(to),
+    }
+  }
+
+  if (period === 'all') {
+    const toDay = formatUtcDay(to)
+    const earliest = earliestReportDay == null ? toDay : assertUtcDay(earliestReportDay)
+    return {
+      from: earliest <= toDay ? earliest : toDay,
+      to: toDay,
+    }
+  }
+
+  const from = new Date(to)
+  from.setUTCDate(from.getUTCDate() - (period - 1))
+  return { from: formatUtcDay(from), to: formatUtcDay(to) }
+}
+
+function formatUtcDay(value: Date): string {
+  const year = value.getUTCFullYear().toString().padStart(4, '0')
+  const month = (value.getUTCMonth() + 1).toString().padStart(2, '0')
+  const day = value.getUTCDate().toString().padStart(2, '0')
+  return `${year}-${month}-${day}`
+}
+
+function assertUtcDay(value: string): string {
+  if (!UTC_DAY_PATTERN.test(value)) throw new Error('analytics report day must use YYYY-MM-DD')
+  const date = new Date(`${value}T00:00:00.000Z`)
+  if (!Number.isFinite(date.valueOf()) || formatUtcDay(date) !== value) {
+    throw new Error('analytics report day must be a real UTC calendar day')
+  }
+  return value
+}