feat: oss index collections endpoint

[epipav]

Summary

Adds GET /v1-alpha/oss-index/collections (IN-1416, epic IN-1146). It returns a cursor-paged list of OSS Index collections with their top projects, plus the category details when a category is picked.

• categorySlug and categoryGroupId filter the collections. sort (totalContributors or softwareValue, default totalContributors) orders them. cursor and pageSize page them like the leaderboard routes.
• With categorySlug, the route reads the category from category_list first and returns it as category. An unknown slug answers 404 not_found, and the collections pipe is then skipped.
• Collections come from collections_oss_index. Their project tuples carry slug, so src/lib/oss-index.ts gains CollectionProject and its guard and mapper.
• An invalid cursor answers 400. A malformed row answers 503 upstream_unavailable.

Notes

• The pipe's total row count ignores the category filter, so the route detects the last page from a short pipe page. A full last page returns a nextCursor that leads to an empty page.
• Counts and software values must be non-negative integers, matching the groups and categories endpoints.
• Stacked on feat: oss index categories endpoint #2351.

Tests

• tests/oss-index-collections.test.ts: filter and sort forwarding, the category lookup and 404, tuple mapping, paging across pipe pages with the cursor walk, 400 for bad input, 503 for malformed rows, and the OpenAPI entry.
• tests/oss-index.test.ts: the 10-slot guard and mapper.

• main
  • feat: oss index groups endpoint #2350
    • feat: oss index categories endpoint #2351
      • feat: oss index collections endpoint 👈

[cursor]

PR Summary

Low Risk
Read-only endpoint following existing OSS Index pipe and pagination patterns; risk is mainly upstream shape mismatches, which are guarded with 503 responses.

Overview
Adds GET /v1-alpha/oss-index/collections, a cursor-paged read API for OSS Index collections (totals, project count, and leading projects).

Query params categorySlug and categoryGroupId narrow the list; sort orders by totalContributors (default) or softwareValue. Data is loaded from Tinybird pipes (collections_oss_index, and category_list when filtering by slug). Unknown categorySlug returns 404 before the collections pipe runs; when the slug is valid, the response includes a category object.

Because the collections pipe embeds projects as 10-slot tuples (slug before status), oss-index.ts adds CollectionProject, isCollectionProjectTuple, and toCollectionProject instead of reusing the 9-slot project shape. Pagination follows other OSS Index routes, with nextCursor inferred from a full last pipe page when the upstream total ignores category filters.

Tests cover mapping, filters, category lookup, paging/cursors, validation (400/503), and OpenAPI.

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

[Copilot]

Copilot review overview

🟢 Approval recommended

The endpoint contract and failure paths are well covered; only a non-blocking comment wording issue remains.

Review effort: Balanced
Findings: 1

Open (1)

• Explain upstream shape constraint for separate tuple · New

What changed in this PR

Adds the cursor-paginated OSS Index collections endpoint with filtering, category details, validation, and tuple mapping.

Changes:

• Adds GET /v1-alpha/oss-index/collections.
• Introduces collection-project schemas, guards, and mappers.
• Adds integration and pagination coverage.

File	Description
api/​src/​versions/​v1-alpha/​oss-index/​collections.ts	Implements the endpoint and schema.
api/​src/​lib/​oss-index.ts	Adds collection-project utilities.
api/​tests/​oss-index-collections.test.ts	Tests endpoint behavior and pagination.
api/​tests/​oss-index.test.ts	Tests tuple validation and mapping.

---

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

[Copilot]

Copilot review overview

🔵 Needs a closer look

The documented full-page cursor guarantee does not hold for mid-page cursors.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Explain upstream shape constraint for separate tuple

Previously missed (1)

In code that hasn't changed since last review

Incorrectly nullifies nextCursor for short cursor pages

api/​src/​versions/​v1-alpha/​oss-index/​collections.ts:135

This guarantee is too broad: with pageSize=2, cursor offset 1, and three rows total, the second pipe page is short and this handler returns nextCursor: null despite returning two rows. Document that only some full final responses produce an empty follow-up page.