warframe-status

Warframe WorldState API built with NestJS

Access

REST-ish:

• http://$host:$port/$platform
• http://$host:$port/$platform/$child-item
• http://$host:$port/$a-bunch-of-static-data

Sockets:

ws://$host:$port/socket (or for the secure socket) wss://$host:$port/socket

Requests taken as json strings in the socket packet.

Consumers will need to parse responses and stringify requests yourself, as ws doesn't provide a way to automatically parse them.

{ "event": "ws:req", "packet": { "platform": "$platform", "language": "$language" } }

{ "event": "twitter" }

{ "event": "rss" }

connecting automatically subscribes the connection to events structured as:

{
  event: 'twitter',
  packet: '[]', // tweets
}

{
  event: 'ws:update',
  packet: '{}', // entire updated worldstate
}

{
  event: '', // worldstate key,
  packet: '', // worldstate key data
}

probably several others that can take some experimenting

---

Quick Start

# Install dependencies
npm install

# Development mode (hot reload)
npm run dev

# Build for production
npm run build

# Production mode
npm start

ENV Variables

Common Variables

Key	Meaning
PORT/IP	Port or IP address for hosting service
HOST/HOSTNAME	host or hostname for hosting service
LOG_LEVEL	Logging level for logging
SENTRY_DSN	Sentry DNS for reporting errors
BUILD	Whether or not to forcibly build caches on startup

External Service Variables

Key	Meaning
TWITTER_KEY	Twitter Account Key
TWITTER_SECRET	Twitter Account Secret
TWITTER_BEARER_TOKEN	Twitter OAuth Bearer Token
WFINFO_FILTERED_ITEMS	WF Info filtered items source json url
WFINFO_PRICES	WF Info prices source json url
DISABLE_PRICECHECKS	Disable pricecheck services

NestJS-Specific Variables

Key	Meaning
USE_WORLDSTATE	Enable WorldState endpoints (true/false)
FEATURES	Comma-separated features (e.g., SOCKET,worldstate)
WS_EMITTER_FEATURES	WebSocket emitter features (e.g., rss,rivens,worldstate)
USE_CLUSTER	Enable built-in clustering (true/false)
NODE_ENV	Environment mode (development/production)

It's highly recommended to use the local loopback (127.0.0.1) for HOST/HOSTNAME

---

Docker Deployment

# Build image
docker build -t ghcr.io/wfcd/warframe-status:latest .

# Run container
docker run -d \
  --name warframe-status \
  -p 3001:3001 \
  -v ./caches:/app/caches \
  ghcr.io/wfcd/warframe-status:latest

Or use docker-compose.example.yml for a compose-based setup.

Warframe content servers are geo-restricted. If the host cannot reach them, run behind a Cloudflare WARP sidecar — see docker-compose.warp.example.yml and DEPLOYMENT.md.

---

Testing

NestJS Tests

# Unit tests (fast, uses mocks)
npm run test:nest

# Integration tests (slow, uses real APIs)
npm run test:nest:integration

# All tests
npm run test:nest:all

# Watch mode
npm run test:nest:watch

Test Results: - 357 unit tests passing - 80%+ code coverage - 100% endpoint coverage

See INTEGRATION_TESTING.md for details.

Express Tests

npm test

---

Documentation

• MIGRATION_PLAN.md - Express → NestJS migration status and remaining work
• API Documentation - Complete API reference (built from this repo)

# Export OpenAPI from Nest, lint with Redocly, and bundle static docs
npm run docs:build

# Local preview after building
npm run docs:preview

Docs deploy automatically on release via .github/workflows/release.yml. If that step fails or is skipped, manually redeploy from GitHub Actions → API docs → Run workflow (optional ref for branch/tag/SHA, defaults to main).

Deploy uses GITHUB_TOKEN with contents: write. Keep gh-pages unprotected so Actions can push freely; also ensure repo workflow permissions are Read and write.

---

Development

NestJS Development

# Start development server (hot reload)
npm run nest:start:dev

# Debug mode
npm run nest:start:debug

# Build for production
npm run nest:build

# Run tests
npm run test:nest

Express Development

# Start development server
npm run dev

# With PM2
npm run dev:pm2

---

Architecture

NestJS Features

• TypeScript with ES Modules - Modern module system with .js extensions
• Built-in Clustering - Node.js cluster module (not PM2)
• WebSocket Support - @nestjs/websockets with ws adapter
• File-based Caching - Stateless with flat-cache
• Dependency Injection - NestJS DI container
• Feature Flags - Conditional module loading via env vars

Shared Features

• 100% API Compatibility - Both implementations return identical responses
• WorldState Parsing - warframe-worldstate-parser
• Static Data - Warframe items, drops, rivens, etc.
• RSS Feed - Warframe news aggregation
• Twitter Integration - Optional Twitter feed
• Price Checking - Optional WFInfo integration

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

Project uses Biome for linting and formatting.

---

Support & Community

• GitHub Issues: WFCD/warframe-status
• Discord: Warframe Community Developers

---

License

Apache-2.0