features: add entity feature retrieval and listing queries

[Kzoeps]

Scope

Adds public org.hypercerts.entity.getFeature and org.hypercerts.entity.listFeatures endpoints with author/type/organization filters, cursor pagination, actor sidecars, HTTP/unit coverage, and a Changeset.

Validation

• Offline pnpm test:unit: 108/108 tests passed; pnpm check and pnpm build passed locally.
• Local pnpm test:http was not run. Unit tests use local fixtures/fake adapters and do not install handlers, seed PostgreSQL, or contact HappyView. CI HTTP coverage exercises real XRPC over HTTP against the installed HappyView + PostgreSQL test environment; its result is pending from PR creation.

Summary by CodeRabbit

• New Features
  • Added public endpoints to retrieve a feature by its exact URI and list features with author, type, and organization-record filters.
  • Feature results include available author and organization details, with paginated listing and ascending or descending sorting.
• Documentation
  • Expanded API and contributor documentation with feature-query details, test coverage, and fixture information.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
api-endpoints	Ready	Preview	Oct 6, 2026 3:21pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: 343fecf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hypercerts-org/hypercerts-api	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 21 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: f2762445-aaf5-4b1e-9d3a-d09ae82a3eb5

📥 Commits

Reviewing files that changed from the base of the PR and between 5641104 and 343fecf.

📒 Files selected for processing (26)

• .changeset/feature-query-endpoints.md
• CONTRIBUTING.md
• README.md
• api/README.md
• api/lexicons/org.hypercerts.entity.defs.json
• api/lexicons/org.hypercerts.entity.getFeature.json
• api/lexicons/org.hypercerts.entity.listFeatures.json
• api/lua/endpoints/getBadgeDefinition.lua
• api/lua/endpoints/getFeature.lua
• api/lua/endpoints/listBadgeDefinitions.lua
• api/lua/endpoints/listFeatures.lua
• api/lua/shared/badgeDefinitionValidation.lua
• api/lua/shared/featureValidation.lua
• api/lua/src/getBadgeDefinition.lua
• api/lua/src/getFeature.lua
• api/lua/src/listBadgeDefinitions.lua
• api/lua/src/listFeatures.lua
• api/manifest.json
• api/modules/badge-definitions/manifest.json
• api/modules/features/manifest.json
• api/tests/http/features.http.test.js
• api/tests/http/fixtures/features.fixture.js
• api/tests/http/fixtures/graph-follows.fixture.js
• api/tests/unit/feature.test.js
• api/tests/unit/fixtures/http-seed-rows.test.js
• api/tests/unit/tooling/badge-definition.contract.test.js

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: e8ef10d5-c757-41ba-9ca6-cf400f54a8a0

📥 Commits

Reviewing files that changed from the base of the PR and between 02714f2 and 5641104.

📒 Files selected for processing (27)

• .changeset/feature-query-endpoints.md
• CONTRIBUTING.md
• README.md
• api/README.md
• api/lexicons/org.hypercerts.entity.defs.json
• api/lexicons/org.hypercerts.entity.getFeature.json
• api/lexicons/org.hypercerts.entity.listFeatures.json
• api/lua/endpoints/getBadgeDefinition.lua
• api/lua/endpoints/getFeature.lua
• api/lua/endpoints/listBadgeDefinitions.lua
• api/lua/endpoints/listFeatures.lua
• api/lua/shared/badgeDefinitionValidation.lua
• api/lua/shared/featureValidation.lua
• api/lua/src/getBadgeDefinition.lua
• api/lua/src/getFeature.lua
• api/lua/src/listBadgeDefinitions.lua
• api/lua/src/listFeatures.lua
• api/manifest.json
• api/modules/badge-definitions/manifest.json
• api/modules/features/manifest.json
• api/tests/http/features.http.test.js
• api/tests/http/fixtures/features.fixture.js
• api/tests/http/fixtures/graph-follows.fixture.js
• api/tests/unit/feature.test.js
• api/tests/unit/fixtures/fixtures.test.js
• api/tests/unit/fixtures/http-seed-rows.test.js
• api/tests/unit/tooling/badge-definition.contract.test.js

💤 Files with no reviewable changes (1)

• api/tests/unit/fixtures/fixtures.test.js

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

This change adds getFeature and listFeatures query endpoints. It defines their lexicons, implements PostgreSQL-backed retrieval and author hydration, registers the handlers, and adds tests and documentation. It also centralizes badge-definition URI validation and updates fixture-isolation checks.

Changes

Feature query endpoints

Layer / File(s)	Summary
Feature query contracts and retrieval api/lexicons/org.hypercerts.entity.*.json, api/lua/shared/featureValidation.lua, api/lua/endpoints/getFeature.lua, api/lua/src/getFeature.lua, api/modules/features/manifest.json, api/manifest.json	Defines the feature view and query schemas. getFeature validates the requested feature URI, looks up the indexed record, and returns it with available author profile and organization records. The manifests register both feature handlers.
Feature filtering and cursor pagination api/lua/endpoints/listFeatures.lua, api/lua/src/listFeatures.lua	Adds repeated author and type filters, organization-record filtering, sort direction, limits, and direction-bound cursors. The endpoint queries and hydrates feature views, then returns a cursor when another page exists.
Endpoint tests and documentation api/tests/http/features.http.test.js, api/tests/http/fixtures/features.fixture.js, api/tests/unit/feature.test.js, api/tests/unit/fixtures/*, api/tests/unit/tooling/badge-definition.contract.test.js, README.md, CONTRIBUTING.md, api/README.md, .changeset/feature-query-endpoints.md	Adds unit and HTTP coverage for feature retrieval, filters, hydration, pagination, and invalid requests. Updates fixture-isolation checks, endpoint documentation, test instructions, and the changeset.

Badge URI validation

Layer / File(s)	Summary
Shared badge collection validation api/lua/shared/badgeDefinitionValidation.lua, api/lua/endpoints/getBadgeDefinition.lua, api/lua/endpoints/listBadgeDefinitions.lua, api/lua/src/getBadgeDefinition.lua, api/lua/src/listBadgeDefinitions.lua, api/modules/badge-definitions/manifest.json, api/tests/unit/tooling/badge-definition.contract.test.js	Both badge query handlers use the shared badge-definition collection constant and URI validator. The contract test checks that invalid URIs are rejected before a database query.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant ListFeatures as listFeatures.handle()
  participant PostgreSQL
  Client->>ListFeatures: Send filters and pagination parameters
  ListFeatures->>PostgreSQL: Query matching feature rows
  PostgreSQL-->>ListFeatures: Return feature rows
  ListFeatures->>PostgreSQL: Load author profile and organization records
  PostgreSQL-->>ListFeatures: Return author records
  ListFeatures-->>Client: Return feature views and optional cursor

Loading

Merge Risk: ⚪ Minimal · up to 56411

No identified issue blocks merging after normal checks. The HTTP test result remains pending.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 80 functions across 16 files. (10 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding entity feature retrieval and listing queries.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 80 functions across 16 files. (10 skipped: 10 unsupported.)

✨ Finishing Touches 💡 3

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch queries/features

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

❌ The last analysis has failed.

See analysis details on SonarQube Cloud