Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add a `/api/v1/meta` discovery endpoint describing limits, tiers, and capabilities

Open
  • Is something wrong?
#231 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
22/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
nodejs, typescript
Domain
api, backend

Research direction

Start by reading how the rate-limit tiers are resolved (resolveRateLimitTierFromRole and the RATE_LIMIT_* values in env.validation.ts), then the module registry in src/modules/ (module-registry.service.ts, tenant-module-state.entity.ts). The new GET /api/v1/meta endpoint should read from those same sources, and a test must show it matches the enforcement path and that no secret from .env.example appears in the response. Done means the documented shape is returned, tenant module state is reflected when authenticated, and the endpoint is in docs/openapi.json.

Written by the indexing model from the issue text.

Description

documentation enhancement good first issue help wanted

Problem

Clients have no way to discover server capabilities at runtime. Everything about rate limits, tiers, and feature flags has to be hardcoded by the integrator.

The information exists but is scattered:

  • Rate-limit tiers: RATE_LIMIT_FREE_PER_MINUTE, RATE_LIMIT_PAID_PER_MINUTE, RATE_LIMIT_ENTERPRISE_PER_MINUTE (README lines 239-241)
  • resolveRateLimitTierFromRole(...), used by the auth services to set the tier claim
  • Feature flags in env.validation.ts (507 lines) and the .env templates
  • The module registry at src/modules/ — module-registry.service.ts with module-manifest.schema.json, module.entity.ts, tenant-module-state.entity.ts, and module-lifecycle.loader.ts. This is a full plugin system that presumably knows which modules are enabled, but exposes it only through module-registry.controller.ts for admins.

docs/module-registry.md documents that system.

Why it matters

An integrator cannot answer "what is my current rate limit?" or "is the simulator module enabled for my tenant?" without reading the source or hardcoding values that drift. The tier is already computed into the JWT (tier: resolveRateLimitTierFromRole(user.role) in enhanced-auth.service.ts:561), so the client already half-knows — but only after login, and only its own tier, not the enforced numbers.

For a platform with a plugin system, a capability endpoint is what makes the extension model usable by third parties.

Suggested Direction

  1. Add GET /api/v1/meta returning: 
    {
  "apiVersion": "v1",
  "rateLimits": { "tier": "paid", "perMinute": 120, "windowMs": 60000 },
  "features": { "simulator": true, "graphql": true, "webhooks": false },
  "limits": { "maxUploadBytes": 52428800, "maxPageSize": 100 },
  "modules": [ { "id": "portfolio", "status": "enabled" } ]
}
  2. Derive every value from the same source the enforcement code uses. Read the values from ConfigService and from the module registry's resolved state — do not duplicate the numbers, or this endpoint will lie.
  3. Scope by tenant and tier, not just global. The module registry already models per-tenant state (tenant-module-state.entity.ts), so a tenant with a module disabled should see that reflected. This is the main reason to build it rather than hardcoding a static response.
  4. Keep it unauthenticated but non-sensitive for the global parts, and require auth for tenant-specific parts. Verify nothing secret leaks — no DSNs, no internal URLs, no signing config.
  5. Document it in docs/ and add @ApiResponse decorators so it appears in the generated SDKs.

Constraints

  • The single most important constraint: this endpoint must not become a place where config values leak. Audit every field against the actual secret values in .env.example before shipping.
  • Feature flags should reflect effective state, including tenant overrides, not raw env booleans.
  • Cache the response briefly (or compute once at startup) so it is not a hot path that reads config on every request.
  • Do not let it become an internal-config dump; if a value is not useful to a client, leave it out.

Acceptance Criteria

  • GET /api/v1/meta exists and returns the documented shape.
  • Values come from the same config the enforcement path reads, verified in a test.
  • Tenant-specific module state is reflected for an authenticated tenant.
  • No secret values (keys, DSNs, internal hosts) appear in the response — assert this in a test.
  • The endpoint appears in docs/openapi.json with @ApiResponse decorators.
  • docs/module-registry.md and the README reference it.
Dominant language
TypeScript
Stars
7
Forks
55
Avg merge
1d 17h
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from SourceXXL/alian_structure-api

All issues in SourceXXL/alian_structure-api

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.