feat: add commit activities endpoint under v1-alpha

[epipav]

What

Adds GET /v1-alpha/projects/{slug}/development/commit-activities, a port of the Nuxt commit-activities widget handler (frontend/server/api/widget/development/commit-activities.get.ts) to the public API.

Query: repos[], startDate, endDate (shared DateRangeQuery, YYYY-MM-DD UTC days), granularity (required: daily, weekly, monthly, quarterly, yearly) and countType (new by default, or cumulative).

Response:

{
  "summary": {
    "current": 120,
    "previous": 100,
    "percentageChange": 20,
    "changeValue": 20,
    "periodFrom": "2025-01-01T00:00:00Z",
    "periodTo": "2025-03-31T00:00:00Z"
  },
  "data": [
    { "startDate": "2025-01-01T00:00:00Z", "endDate": "2025-01-31T00:00:00Z", "commits": 40 }
  ]
}

Behind it: one project_buckets lookup, then the same three concurrent Tinybird calls Nuxt makes (activities_count twice for the current and previous summaries, and activities_count or activities_cumulative_count for the series), with the same fixed parameters (activity_type=authored-commit, onlyContributions=true, includeCodeContributions=true, includeCollaborations=false) and Nuxt's YYYY-MM-DD 00:00:00 date format.

Changes vs. the Nuxt handler

• type (ignored by the handler) and activityType (always authored-commit from the UI) are gone; project/collectionSlug are replaced by the path slug.
• granularity is required. Without it the series pipe falls into summary mode and returns rows without bucket dates.
• countType only selects the series pipe; it is no longer forwarded to Tinybird.
• periodFrom/periodTo and the bucket startDate/endDate are ISO-8601 UTC (2025-01-01T00:00:00Z); Nuxt returned Luxon strings and raw pipe dates.
• percentageChange is signed (Nuxt used Math.abs); a drop reads negative like changeValue.
• An unknown slug is a 200 with a zero summary and data: [] (Nuxt returned 404); the epic's definition of done for metric endpoints.
• Any Tinybird failure, bucket lookup included, is a 503 upstream_unavailable; Tinybird's own status never reaches the caller. An inverted date range is a 400 invalid_request.

Decisions

• The bucket is resolved once with client.getBucketIdForProject(slug) and passed as bucketId on the three pipe calls. api/ has no bucket cache, so letting the client resolve it per call would mean three lookups per request.
• Every pipe call gets the resolved range. getPreviousDates fills the default (2010-01-01 to today) and the previous window, and both are sent on every call, so periodFrom/periodTo match what was counted.
• The summary block keeps the PeriodSummary keys and types but describes the counts as commits, so the OpenAPI reference states the unit of every field. Bucket keys stay startDate/endDate/commits, the keys the Nuxt data layer actually emits.
• Helpers (tinybirdDay, toUtcDateTime, the described granularity/countType schemas, the summary schema) live in the route file on purpose; the five Development PRs run in parallel and a consolidation chore follows once they merge.

Tests

api/tests/development-commit-activities.test.ts: 27 integration tests against the real buildApp() and Tinybird client, with fetch stubbed per pipe path. They cover the response shape and key stripping, the exact Tinybird calls and their concurrency, countType, granularity, omitted and invalid dates, the unknown slug, every Tinybird failure class, Cache-Control, and the OpenAPI document (tag, parameters, a description on every field, /v1 exclusion).

pnpm test (189 tests, 14 files), pnpm tsc-check, pnpm lint and pnpm format:check pass in api/.

Includes the routing-test parser fix from the base branch (62b136b): version-routing.test.ts now reads nested route paths, which this is the first route to produce.

Based on main, which includes #2241 (IN-1348, directory-based route registration) as dd37a7a. Jira: IN-1332

• main
  • refactor: register v1-alpha development routes by directory #2241
    • feat: add commit activities endpoint under v1-alpha 👈

[Copilot]

Copilot review overview

🟡 Changes recommended

Malformed successful Tinybird responses can bypass error mapping and produce generic 500 responses.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Validate Tinybird response arrays before mapping · New

What changed in this PR

Adds the /v1-alpha commit-activities metric endpoint backed by Tinybird.

Changes:

• Adds schemas, date conversion, aggregation, and upstream error handling.
• Registers the route and adds comprehensive integration/OpenAPI tests.

File	Description
api/​src/​versions/​v1-alpha/​development/​commit-activities.ts	Implements the endpoint.
api/​src/​versions/​v1-alpha/​index.ts	Registers the route plugin.
api/​tests/​development-commit-activities.test.ts	Tests behavior, failures, caching, and OpenAPI.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Malformed Tinybird row fields can still bypass upstream error mapping and cause invalid responses or generic 500 errors.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Validate date syntax and numeric counts before error mapping · New

Resolved since last review (1)

• Validate Tinybird response arrays before mapping

[gaspergrom]

Checked that countType picks between activities_count and activities_cumulative_count without being forwarded to Tinybird, and the concurrency test proves the three pipe calls run in parallel rather than just counting calls. Error mapping and the unknown slug path are well covered too.

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation is complete, consistent with existing API patterns, and thoroughly tested.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Validate date syntax and numeric counts before error mapping

[themarolt]

lgtm - one question on the omitted-startDate path, rest reads clean against the Nuxt handler

[Copilot]

Copilot review overview

🟡 Changes recommended

The public API documentation incorrectly guarantees equal-length comparison periods.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Clarify previous date range is not always equal in elapsed days · New

[Copilot]

Copilot review overview

🔵 Needs a closer look

The public documentation incorrectly promises equal-length comparison periods despite calendar-based periods having different elapsed day counts.

Review effort: Balanced
Findings: 1

Open (1)

• Clarify previous date range is not always equal in elapsed days

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation and coverage are coherent; only a non-blocking PR-description inconsistency remains.

Review effort: Balanced
Findings: 1

Open (1)

• Update PR description to reflect defaulted dates sent to Tinybird · New

Resolved since last review (1)

• Clarify previous date range is not always equal in elapsed days