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

Add a `GET /api/v1/simulator/scenarios` endpoint to list available simulation scenarios

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

Nobody has claimed this yet.

Assessment

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

Research direction

Start in src/simulator/, reading simulator.controller.ts, simulator.service.ts, simulation.dto.ts and simulation.entity.ts to see where scenarios are defined today, and check the README around line 241. Add the two GET routes and a typed scenario registry, then extend the colocated spec. Done when both endpoints return the documented fields without seeds or internal state, and docs/ and docs/openapi.json are updated. Whether the endpoints need authentication is not settled in the issue, so confirm that first.

Written by the indexing model from the issue text.

Description

enhancement good first issue help wanted

Problem

src/simulator/ has 6 files: simulator.controller.ts, simulator.module.ts, simulator.service.ts, simulation.dto.ts, simulation.entity.ts, and a spec. The README (line 241) says "Use the simulator environment for safe, deterministic testing before enabling live on-chain submission."

But there is no documented way to discover what simulation scenarios exist. A client must know the scenario ids in advance, which means the simulator is only usable by clients that have read the source code.

Why it matters

Discovery is the difference between a simulator that is usable and one that is a developer tool. If a client can list scenarios with their parameters and expected outcomes, it can offer a UI for choosing and running simulations — which is the README's "safe, deterministic testing" promise made real.

Suggested Direction

  1. Add GET /api/v1/simulator/scenarios returning { id, name, description, parameters, expectedOutcome } per scenario.
  2. Add GET /api/v1/simulator/scenarios/:id for full details.
  3. If scenarios are defined in code, expose them as a typed registry rather than hardcoding in the controller.
  4. Document the endpoint in docs/ and add @ApiResponse decorators.
  5. Add a colocated spec.

Constraints

  • Scenario definitions must be typed and validated.
  • Do not expose internal simulation state or seeds in the list response.
  • The endpoint should be read-only and unauthenticated if scenarios are not sensitive, or authenticated if they reveal internal configuration.

Acceptance Criteria

  • GET /api/v1/simulator/scenarios returns a list of available scenarios.
  • Each scenario includes its parameters and expected outcome.
  • GET /api/v1/simulator/scenarios/:id returns full details.
  • The endpoint is documented in docs/ and in docs/openapi.json.
  • A colocated spec covers the controller.
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.