📌 Description
The StreamObject registered in src/openapi/spec.ts describes fields sender, recipient, depositAmount, ratePerSecond, and a StreamStatus enum of ['scheduled', 'active', 'paused', 'completed', 'cancelled']. The persisted schema in migrations/1774715131962_streams-table.ts and the StreamRecord mapped by rowToRecord in src/db/repositories/streamRepository.ts use sender_address, recipient_address, amount, streamed_amount, remaining_amount, rate_per_second, and a DB-level CHECK (status IN ('active','paused','completed','cancelled')) that does NOT include scheduled. The published spec therefore advertises a field set and a status value that the API can never return, breaking client codegen and contract tests.
💡 Why it matters: Consumers generating types from the OpenAPI document get wrong field names and a scheduled status that the database rejects, producing runtime deserialization failures.
🧩 Requirements and context
- Align
StreamObject property names with the serialized API response shape (and document any intentional camelCase mapping layer if one exists).
- Remove
scheduled from StreamStatus or add it to the DB CHECK constraint and STREAM_INVARIANTS — decide one source of truth.
- Add the missing monetary fields (
streamedAmount/remainingAmount or their serialized equivalents) to the schema.
- Add a test that diffs the OpenAPI
Stream schema keys against StreamRecord keys to prevent future drift.
- Regenerate/verify the served spec at
GET /docs (see src/routes/docs.ts).
- Update examples to use a real Stellar
G… address consistently.
Non-functional requirements
- Must be secure, tested, and documented.
- Should be efficient and easy to review.
🛠️ Suggested execution
1. Fork the repo and create a branch
git checkout -b fix/openapi-stream-schema-drift
2. Implement changes
- Write/modify the relevant source:
src/openapi/spec.ts, possibly src/db/types.ts
- Write comprehensive tests:
tests/routes/docs.test.ts
- Add documentation: regenerated spec served at
/docs
- Include TSDoc doc comments noting the single source of truth for status values
- Validate security assumptions: examples contain no real secrets/keys
3. Test and commit
- Cover edge cases: every status enum value round-trips, every documented field exists on the record
- Include test output and security notes in the PR description.
Example commit message
fix(openapi): align Stream schema field names and status enum with DB
✅ Acceptance criteria
🔒 Security notes
A misleading contract can cause clients to mishandle amount fields; ensure decimal amounts stay documented as strings (never floats) to preserve precision, matching the DB CHECK regex.
📋 Guidelines
- Minimum 95% test coverage
- Clear documentation
- Timeframe: 96 hours
📌 Description
The
StreamObjectregistered insrc/openapi/spec.tsdescribes fieldssender,recipient,depositAmount,ratePerSecond, and aStreamStatusenum of['scheduled', 'active', 'paused', 'completed', 'cancelled']. The persisted schema inmigrations/1774715131962_streams-table.tsand theStreamRecordmapped byrowToRecordinsrc/db/repositories/streamRepository.tsusesender_address,recipient_address,amount,streamed_amount,remaining_amount,rate_per_second, and a DB-levelCHECK (status IN ('active','paused','completed','cancelled'))that does NOT includescheduled. The published spec therefore advertises a field set and a status value that the API can never return, breaking client codegen and contract tests.🧩 Requirements and context
StreamObjectproperty names with the serialized API response shape (and document any intentional camelCase mapping layer if one exists).scheduledfromStreamStatusor add it to the DB CHECK constraint andSTREAM_INVARIANTS— decide one source of truth.streamedAmount/remainingAmountor their serialized equivalents) to the schema.Streamschema keys againstStreamRecordkeys to prevent future drift.GET /docs(seesrc/routes/docs.ts).G…address consistently.Non-functional requirements
🛠️ Suggested execution
1. Fork the repo and create a branch
2. Implement changes
src/openapi/spec.ts, possiblysrc/db/types.tstests/routes/docs.test.ts/docs3. Test and commit
npm testExample commit message
✅ Acceptance criteria
Streamfield names match the API response.scheduledis reconciled across spec, DB CHECK, and invariants.StreamRecord./docsserves the corrected spec.🔒 Security notes
A misleading contract can cause clients to mishandle amount fields; ensure decimal amounts stay documented as strings (never floats) to preserve precision, matching the DB CHECK regex.
📋 Guidelines