feat: collection projects endpoint

[epipav]

Summary

Adds GET /v1-alpha/collections/{slug}/projects (IN-1407, epic IN-1146), stacked on #2337. It lists a collection's projects and repositories with the shared CollectionProject schema.

• Data flow: the shared findCollectionMembers supplies the project ids and repository URLs, then the Tinybird project_repo_insights pipe returns the rows through fetchCountedPipe and the isCollectionProjectRow guard.
• Params:
  • sort: contributorCount, organizationCount or name, each with _asc or _desc. The default is contributorCount_desc.
  • isLF: a boolean.
  • type: project or repo.
  • cursor and pageSize.
• Type filter: the pipe takes no type param, so the route sends only the ids for project or only the URLs for repo. That filters before paging, so pages stay exact.
• Empty results: a collection with no members of the requested type answers an empty page without calling Tinybird.
• Errors: unknown and private slugs answer 404. An upstream failure answers 503.

Notes

• The pipe rejects orderByField=score, so the website's score_desc is left out of the enum.
• A repo entry carries the name, slug and logo of the project that holds it. The OpenAPI description says so.
• The page fan-out and total handling mirror leaderboards/leaderboard.ts. A shared helper for both is a follow-up.

Tests

• tests/collections-projects.test.ts covers:
  • the pipe params, the sort and type mapping, and the empty-collection shortcut
  • 404, 503, validation errors and paging
  • the fallback for a missing or under-reported row total
  • the OpenAPI entry

• main
  • feat: collections groundwork #2337
    • feat: collection projects endpoint 👈

[cursor]

PR Summary

Medium Risk
New read-only public API with multi-request pagination and Tinybird/DB dependencies; no auth or write-path changes, but incorrect paging or pipe params could affect clients listing collection data.

Overview
Adds GET /v1-alpha/collections/{slug}/projects, a paginated list of a collection’s projects and standalone repositories with Insights metrics. The handler loads member ids/URLs via findCollectionMembers, applies type (project / repo) and isLF filters, sorts (default contributorCount_desc), and maps rows through the shared CollectionProject schema. Unknown or private collections return 404; empty member sets skip Tinybird.

Because member lists can be large, the Tinybird client gains postCountedPipe, which POSTs pipe params in the body (via an extended fetchGuarded) so ids/URLs are not limited by URL length. The route calls the project_repo_insights pipe with the same multi-page fetch and nextCursor logic used elsewhere when totals are missing or inconsistent.

Tests cover lookup errors, validation, POST body params, type filtering, response mapping, paging edge cases, and OpenAPI metadata; Tinybird test helpers now expose postedParams for POST assertions.

^{Reviewed by Cursor Bugbot for commit fdebf08. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Copilot review overview

🟡 Changes recommended

Unbounded collection-member arrays are sent in a GET URL, which can fail for larger collections.

Review effort: Balanced
Findings: 1

Open (1)

• Use guarded POST for large fetchCountedPipe requests · New

What changed in this PR

Adds the v1-alpha endpoint for listing a collection’s projects and repositories with filtering, sorting, and cursor pagination.

Changes:

• Adds the collection-projects route backed by PostgreSQL membership lookup and Tinybird metrics.
• Adds integration coverage for validation, errors, mapping, pagination, and OpenAPI registration.

File	Description
api/​src/​versions/​v1-alpha/​collections/​projects.ts	Implements the endpoint and response mapping.
api/​tests/​collections-projects.test.ts	Tests endpoint behavior and schema registration.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The sort documentation omits the required cursor-reuse warning, risking skipped or duplicated results.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Use guarded POST for large fetchCountedPipe requests

Previously missed (1)

In code that hasn't changed since last review

Document that cursors are tied to sort order

api/​src/​versions/​v1-alpha/​collections/​projects.ts:33

ADR-0011 requires every endpoint's OpenAPI sort description to explain that cursors are tied to the selected sort. Without that warning, a caller can reuse this offset cursor under another order and skip or duplicate entries; tell callers to restart pagination after changing sort (api/docs/arch/adr/0011-pagination-cursor-based.md:46).

[gaspergrom]

Checked the type filter against project_repo_insights.pipe: ids only match type = 'project' rows and repoUrls only match type = 'repo' rows, so leaving one list out filters correctly before paging. The route also posts the arrays in the body. LGTM.

[themarolt]

lgtm