npm package: @nepse-toolkit/api
Description: REST API server for Nepal Stock Exchange data and analysis
Latest version: 0.2.5

# @nepse-toolkit/api

REST API server for Nepal Stock Exchange data and analysis.

Part of the [nepse-toolkit](https://github.com/pawanpaudel93/nepse-toolkit) monorepo.

## Overview

- Hono-based API with market, stock, analysis, portfolio, and provider routes
- Multi-provider failover via `@nepse-toolkit/core`
- Built-in telemetry capture worker with anomaly monitoring
- Optional API guardrails: API key auth, CORS allowlist, and rate limiting

## Install

```bash
npm install @nepse-toolkit/api
```

## Quick Start

```bash
# from monorepo root
bun run build
bun run api

# Docker
# docker build -t nepse-api .
# docker run -p 3000:3000 nepse-api
```

Server listens on `PORT` (default `3000`).

## Environment

### Core

```bash
PORT=3000
```

### API Security

```bash
API_AUTH_KEY=...                           # optional, require x-api-key on all routes except /health
API_CORS_ORIGINS=https://app.example.com,https://admin.example.com   # optional allowlist; default allows all origins
API_RATE_LIMIT_ENABLED=false               # default false
API_RATE_LIMIT_WINDOW_SECONDS=60           # request window when enabled
API_RATE_LIMIT_MAX_REQUESTS=120            # max requests per key/ip per window when enabled
```

### Telemetry Worker

```bash
PAYLOAD_TELEMETRY_WORKER_ENABLED=true
PAYLOAD_TELEMETRY_WORKER_INTERVAL_MINUTES=15
PAYLOAD_TELEMETRY_WORKER_LIMIT_ENDPOINTS=100
PAYLOAD_TELEMETRY_WORKER_RUN_ON_START=true
PAYLOAD_TELEMETRY_RETENTION_ENABLED=true
PAYLOAD_TELEMETRY_RETENTION_DAYS=30
PAYLOAD_TELEMETRY_ANOMALY_ALERTS_ENABLED=true
PAYLOAD_TELEMETRY_ANOMALY_WINDOW_HOURS=24
PAYLOAD_TELEMETRY_ANOMALY_TOP_ENDPOINTS=20
PAYLOAD_TELEMETRY_ANOMALY_MIN_SAMPLES=20
PAYLOAD_TELEMETRY_ANOMALY_MIN_FAILURES=3
PAYLOAD_TELEMETRY_ANOMALY_FAILURE_RATE=0.2
PAYLOAD_TELEMETRY_ANOMALY_COOLDOWN_MINUTES=60
PAYLOAD_TELEMETRY_ALERT_WEBHOOK_URL=https://alerts.example.com/webhook
PAYLOAD_TELEMETRY_ALERT_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
PAYLOAD_TELEMETRY_ALERT_EMAIL_WEBHOOK_URL=https://mailer.example.com/send
PAYLOAD_TELEMETRY_ALERT_EMAIL_TO=ops@example.com
PAYLOAD_TELEMETRY_ALERT_DELIVERY_TIMEOUT_MS=8000
PAYLOAD_TELEMETRY_ALERT_DELIVERY_MAX_ATTEMPTS=3
PAYLOAD_TELEMETRY_ALERT_DELIVERY_RETRY_DELAY_MS=1000
PAYLOAD_TELEMETRY_ALERT_DEAD_LETTER_ENABLED=true
```

## Route Groups

- `/health`
- `/api/v1/market`
- `/api/v1/stocks`
- `/api/v1/analysis`
- `/api/v1/portfolio`
- `/api/v1/watchlists`
- `/api/v1/alerts`
- `/api/v1/backtest`
- `/api/v1/providers`

Provider telemetry alert-management routes:

- `GET /api/v1/providers/payload-telemetry/alerts/sinks`
- `PUT /api/v1/providers/payload-telemetry/alerts/sinks`
- `DELETE /api/v1/providers/payload-telemetry/alerts/sinks/:id`
- `GET /api/v1/providers/payload-telemetry/alerts/controls`
- `PUT /api/v1/providers/payload-telemetry/alerts/controls`
- `DELETE /api/v1/providers/payload-telemetry/alerts/controls`
- `POST /api/v1/providers/payload-telemetry/prune?retentionDays=30`
- `GET /api/v1/providers/payload-telemetry/alerts/dead-letters`
- `POST /api/v1/providers/payload-telemetry/alerts/dead-letters/:id/resolve`

For full endpoint examples and payload shapes, see the root [README](../../README.md).

## Development

```bash
bun --filter @nepse-toolkit/api run build
bun --filter @nepse-toolkit/api run typecheck
bun test packages/api/tests/
```

## License

MIT