Rosalia Nightsong

Rosalia Nightsong (hereinafter the “Application”) is a centralised alert server that receives and forwards application logs, errors, uptime notifications, Discord entitlements, and Stripe payment events to both email and Discord channels for real-time monitoring and notification purposes.

1. User Documentation

This section is for those interacting with a live instance of the Application.

Overview

Rosalia Nightsong serves as a webhook endpoint and notification hub for various services. The application accepts HTTP POST requests containing structured data and forwards them as formatted notifications to configured email addresses and Discord channels.

API Endpoints

The Application provides several webhook endpoints:

GET / - Returns the application’s homepage with basic information
POST /log - Accepts application log messages
POST /error - Accepts error reports with stack traces
POST /uptime - Accepts uptime/health check notifications
POST /entitlement - Handles Discord entitlement purchase notifications
POST /stripe - Processes Stripe payment webhook events

Authentication

All POST endpoints (except Stripe webhooks) require authentication via the Authorization header containing a valid API token. Discord entitlements use Ed25519 signature verification for security.

Supported Applications

The server maintains a registry of supported Discord applications with their respective verification keys for entitlement webhook validation.

2. Technical Documentation

This section is for those interested in running their own instance of the Application.

Architecture

Rosalia Nightsong is built using:

Runtime: Node.js with TypeScript
Web Framework: Fastify for high-performance HTTP handling
Email: Nodemailer with SMTP transport
Discord Integration: Discord API v10 for channel messaging
Payment Processing: Stripe SDK for webhook handling
Webhook Verification: discord-verify for Ed25519 signature validation

Environment Configuration

The application requires the following environment variables:

MATRIX_ACCESS_TOKEN="matrix_access_token"
MATRIX_ROOM_ID="matrix_room_id"
API_AUTH="api_authentication_token"
EMAIL_PASSWORD="smtp_password"
DISCORD_WEBHOOK_URL="discord_webhook_url"
STRIPE_SECRET_KEY="stripe_secret_key"
STRIPE_WEBHOOK_SECRET="stripe_webhook_secret"
DISCORD_TOKEN="discord_bot_token"

Installation and Setup

Prerequisites
- Node.js 22+ with pnpm package manager
- TypeScript compiler
- Access to SMTP server for email notifications
- Discord bot token and channel access
- Stripe account with webhook configuration (if using payment features)
Installation
Terminal window
```
pnpm install
```
Build
Terminal window
```
pnpm run build
```
Start
Terminal window
```
pnpm start
```

The server will listen on port 5003 by default.

API Schema Validation

The application uses JSON schema validation for incoming requests:

Log Endpoint (`/log`)

{
  application: string;
  level: string;
  message: string;
}

Error Endpoint (`/error`)

{
  application: string;
  context: string;
  message: string;
  stack: string;
}

Uptime Endpoint (`/uptime`)

{
  application: string;
  message: string;
}

Notification Formats

Email Notifications: Plain text format sent to configured SMTP recipient Discord Notifications: Rich embed format with structured components and markdown support

Security Features

API token authentication for log/error/uptime endpoints
Ed25519 signature verification for Discord entitlements
Stripe webhook signature validation
Request body validation against JSON schemas
Error handling with notification forwarding

Monitoring and Logging

The application includes comprehensive error handling that forwards internal errors to the configured notification channels, ensuring operational visibility and quick incident response.

3. Legal Documentation

This section is for expansions to our legal policies specific to the Application.

License

This software is licensed under Naomi’s Public Licence. Copyright held by Naomi Carrigan.

Data Handling

The Application processes and forwards notification data but does not persistently store user data. All webhook payloads are processed in memory and forwarded to configured notification channels.

Third-Party Services

The Application integrates with:

Discord API for message delivery
Stripe API for payment webhook processing
SMTP servers for email delivery

Users should review the privacy policies and terms of service for these third-party services.

4. Contributing Documentation

This section is for documentation related to contributing to the Application’s codebase.

Development Setup

Clone the repository
Install dependencies: pnpm install
Configure environment variables in prod.env
Run linting: pnpm run lint
Build the project: pnpm run build
Start development server: pnpm start

Code Structure

src/
├── config/          # Application configuration and data
├── interfaces/      # TypeScript interface definitions
├── modules/         # Core functionality modules
├── schemas/         # JSON schema validation definitions
├── server/          # Fastify server setup and routing
└── utils/           # Utility functions

Development Guidelines

Follow the existing ESLint configuration (@nhcarrigan/eslint-config)
Use TypeScript strict mode
Include comprehensive error handling
Add appropriate JSDoc comments for public functions
Maintain the existing code style and structure

Testing

Currently, no automated tests are configured. Contributors are encouraged to manually test all endpoints and error scenarios.

Pull Request Process

Review the contributing guidelines
Follow the Code of Conduct
Create a feature branch from main
Make your changes with appropriate commit messages
Ensure linting passes
Submit a pull request with a clear description

Contact

For questions or support, contact through the Chat Server or email [email protected].