feat(core): add start_time and end_time query params on audit log routes

[simeng-li]

Summary

Closes LOG-13418. Stacked on #8802.

Adds optional start_time and end_time unix-ms query parameters to GET /api/logs and GET /api/hooks/:id/recent-logs, letting callers narrow the time window so the count scan is cheaper and so the Console can build a time-range picker on top.

What changed

• packages/core/src/queries/log.ts — LogCondition gains startTime / endTime (exclusive, in unix-ms). buildLogConditionSql emits a symmetric to_timestamp(value::double precision / 1000) clause for each bound.
• packages/core/src/utils/time-window.ts (new) — shared parseTimestampParam (throws 400 guard.invalid_input on non-finite input) and validateTimeWindow (throws 400 log.invalid_time_window when both bounds are present and start >= end).
• packages/core/src/routes/log.ts — accepts both params, declares 400 in koaGuard.status.
• packages/core/src/routes/hook.ts — same wiring, preserving the historical 24-hour lower bound only when neither param is supplied (hasExplicitWindow flag). Any explicit bound replaces the default, so callers stay in control.
• New error code log.invalid_time_window added to all 17 locales (the route declares 400 explicitly because koaGuard only auto-bypasses status assertion for guard.* codes).
• OpenAPI: both endpoints document the new params, exclusive-bound semantics, and the new 400 response. The hooks endpoint notes that supplying either bound replaces the 24h default.

Expected behavior

• No params → existing behavior unchanged (audit logs unbounded; webhook recent-logs uses the 24h default).
• Either param supplied → createdAt strictly between the bounds (> / <); webhook endpoint drops its 24h default.
• start_time >= end_time (including equal) or non-finite values → 400 with log.invalid_time_window / guard.invalid_input.

Reviewer notes

• The 24h backward-compat on /hooks/:id/recent-logs is intentional and exhaustively covered by unit tests across all four combinations (none / start-only / end-only / both).
• Integration test captures timestamps around an interaction-driven log (no DB seeding available), then asserts inclusion in a matching window and exclusion from non-overlapping windows.

Testing

Unit tests, integration tests

Checklist

• .changeset
• unit tests
• integration tests
• necessary TSDoc comments

[github-actions]

COMPARE TO master

Total Size Diff ⚠️ 📈 +16.67 KB

Diff by File

Name	Diff
.changeset/logs-time-window.md	📈 +731 Bytes
packages/core/src/queries/log.ts	📈 +443 Bytes
packages/core/src/routes/hook.test.ts	📈 +2.55 KB
packages/core/src/routes/hook.ts	📈 +751 Bytes
packages/core/src/routes/hooks.openapi.json	📈 +820 Bytes
packages/core/src/routes/log.openapi.json	📈 +789 Bytes
packages/core/src/routes/log.test.ts	📈 +2.24 KB
packages/core/src/routes/log.ts	📈 +461 Bytes
packages/core/src/utils/time-window.ts	📈 +968 Bytes
packages/integration-tests/src/tests/api/audit-logs/time-window.test.ts	📈 +5.78 KB
packages/phrases/src/locales/ar/errors/log.ts	📈 +79 Bytes
packages/phrases/src/locales/de/errors/log.ts	📈 +68 Bytes
packages/phrases/src/locales/en/errors/log.ts	📈 +65 Bytes
packages/phrases/src/locales/es/errors/log.ts	📈 +72 Bytes
packages/phrases/src/locales/fr/errors/log.ts	📈 +77 Bytes
packages/phrases/src/locales/it/errors/log.ts	📈 +76 Bytes
packages/phrases/src/locales/ja/errors/log.ts	📈 +97 Bytes
packages/phrases/src/locales/ko/errors/log.ts	📈 +74 Bytes
packages/phrases/src/locales/pl-pl/errors/log.ts	📈 +79 Bytes
packages/phrases/src/locales/pt-br/errors/log.ts	📈 +72 Bytes
packages/phrases/src/locales/pt-pt/errors/log.ts	📈 +72 Bytes
packages/phrases/src/locales/ru/errors/log.ts	📈 +92 Bytes
packages/phrases/src/locales/th/errors/log.ts	📈 +87 Bytes
packages/phrases/src/locales/tr-tr/errors/log.ts	📈 +74 Bytes
packages/phrases/src/locales/zh-cn/errors/log.ts	📈 +66 Bytes
packages/phrases/src/locales/zh-hk/errors/log.ts	📈 +66 Bytes
packages/phrases/src/locales/zh-tw/errors/log.ts	📈 +66 Bytes

[Copilot]

Pull request overview

This PR adds optional start_time and end_time (unix-ms) query parameters to the audit log list endpoints to allow callers to restrict the queried time window, reducing scan cost and enabling Console time-range filtering.

Changes:

• Extend log query building to support exclusive createdAt bounds (startTime / endTime) and wire these through /api/logs and /api/hooks/{id}/recent-logs.
• Add shared parsing/validation helpers (parseTimestampParam, validateTimeWindow) and surface 400 responses for invalid windows / non-finite timestamps.
• Update OpenAPI docs, add the new log.invalid_time_window i18n key across locales, and add unit + integration coverage for the new params.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/core/src/queries/log.ts	Adds startTime/endTime to LogCondition and emits SQL predicates for the bounds.
packages/core/src/utils/time-window.ts	New shared query-param parsing + time-window validation utilities.
packages/core/src/routes/log.ts	Accepts start_time/end_time on GET /logs and forwards parsed bounds to queries.
packages/core/src/routes/hook.ts	Accepts start_time/end_time on GET /hooks/:id/recent-logs, preserving 24h default only when no bounds provided.
packages/core/src/routes/log.test.ts	Unit tests covering param pass-through and 400 validation cases for /logs.
packages/core/src/routes/hook.test.ts	Unit tests covering default-vs-explicit-window behavior and validation for /recent-logs.
packages/integration-tests/src/tests/api/audit-logs/time-window.test.ts	Integration coverage for filtering behavior and validation responses on GET /api/logs.
packages/core/src/routes/log.openapi.json	Documents new query params and 400 response for /api/logs.
packages/core/src/routes/hooks.openapi.json	Documents new query params, 400 response, and the “replaces 24h default” behavior for /recent-logs.
packages/phrases/src/locales/*/errors/log.ts	Adds localized log.invalid_time_window error message.
.changeset/logs-time-window.md	Announces the new query params and semantics in release notes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.