feat(api): build portfolio, transaction & agent APIs with WhatsApp formatter layer (#6)

[Chucks1093]

Closes #6

Summary

Implemented the WhatsApp-first API surface for portfolio, transactions, protocols/agent status, deposit, and withdraw flows, including a formatter layer that converts structured data into chat-optimized replies.

Changes

API Routes Added

• GET /api/portfolio/:userId
• GET /api/portfolio/:userId/history?period=7d|30d|90d
• GET /api/portfolio/:userId/earnings
• GET /api/transactions/:userId?page=1&limit=5
• GET /api/transactions/detail/:txHash
• GET /api/protocols/rates
• GET /api/protocols/agent/status
• POST /api/deposit
• POST /api/withdraw

Route Registration

• Registered all new routes in src/index.ts:
  • /api/portfolio
  • /api/transactions
  • /api/protocols
  • /api/deposit
  • /api/withdraw

Authentication + Access Control

• Added src/middleware/auth.ts:
  • requireAuth for bearer token/session authentication
  • enforceUserAccess to ensure user-specific endpoints can only access own data
• Enforced auth on all user-specific endpoints.

Validation + Status Codes

• Added zod input validation for query/body payloads.
• Implemented required HTTP behavior:
  • 401 Unauthorized (missing/invalid token, wrong user access)
  • 404 Not Found (missing user/tx/agent status)
  • 409 Conflict (duplicate deposit txHash)
  • 400 Validation error

WhatsApp Formatter Layer (Critical)

• Added src/whatsapp/formatters.ts with formatter functions for all user-facing responses:
  • Portfolio snapshot
  • Portfolio history
  • Earnings summary
  • Transactions list
  • Transaction detail
  • Protocol rates
  • Agent status
  • Deposit response
  • Withdraw response
• Formatting includes WhatsApp-friendly text style (*bold*, _italic_, concise mobile-readable lines, emojis).

Deposit & Withdraw Requirements

• POST /api/deposit returns whatsappReply.
• POST /api/withdraw returns whatsappReply.
• Duplicate deposit txHash returns 409.

Testing

• Added integration test suite:
  • tests/integration/api/api.test.ts
• Added test env bootstrap:
  • tests/setupEnv.ts
• Updated Jest config to include integration tests and test TS config.
• Added tsconfig.test.json.

Test Coverage Added (Integration)

• Portfolio routes:
  • 401 without token
  • 404 for missing user
  • correct response shape
• Transaction routes:
  • default pagination limit = 5
• Deposit route:
  • duplicate tx hash returns 409
  • successful response includes whatsappReply

Build / Verification

• npm run lint ✅
• npm run test ✅
• npm run build ✅ (zero TypeScript errors)

Notes

• API responses include both structured JSON and WhatsApp-ready whatsappReply strings for chat delivery through Twilio.
• Server boot logic was adjusted so app.listen() only runs when executed directly, which improves testability.

[robertocarlous]

Can you attach a screenshot of your tests passing

[Chucks1093]

okay

[Chucks1093]

[Chucks1093]

@robertocarlous can you review and merge this?

[robertocarlous]

Hello @Chucks1093 Pls pull main branch and sync with your branch and run ci to ensure it pass, so i can merge,thank you

[Chucks1093]

Okay

[Chucks1093]

@robertocarlous