docs/src/content/docs/projects/serenya.md

title

title
Serenya

Serenya (hereinafter the "Application") is a Discord bot that allows users to enforce self-breaks by timing themselves out in Discord servers for a specified duration.

1. User Documentation

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

Overview

Serenya is a Discord bot designed to help users take mandatory breaks from Discord servers. When you need to step away but lack the self-control to stay away, Serenya can timeout your account for a duration you specify, preventing you from participating in server activities.

Available Commands

/about

Displays information about Serenya, including:

• What the bot can do
• How to get help
• Links to the support Discord server

/break <minutes>

Parameters:

• minutes (required): The number of minutes you want to be timed out

Functionality:

• Times out your Discord account for the specified duration
• Cannot be undone once executed - this enforces the break
• Requires the bot to have proper permissions and role hierarchy

Requirements

For Serenya to work properly in your server:

1. The bot must have "Timeout Members" permission
2. Serenya's role must be positioned higher than your role in the server's role hierarchy
3. Your account must be moderatable by the bot

Getting Help

If you encounter issues or need assistance:

• Visit the support Discord server: https://chat.nhcarrigan.com
• The bot will provide error messages if it cannot perform the requested action

2. Technical Documentation

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

Architecture

Serenya is built using:

• Discord.js v14.22.1: Discord API interaction
• Fastify v5.5.0: Web server for health monitoring
• TypeScript: Type-safe development
• Node.js: Runtime environment

Project Structure

src/
├── index.ts           # Main bot entry point and event handlers
├── commands/
│   ├── about.ts       # About command implementation
│   └── break.ts       # Break/timeout command implementation
├── server/
│   └── serve.ts       # Web server for health monitoring
└── utils/
    └── logger.ts      # Logging utility

Key Components

Main Bot (src/index.ts)

• Initializes Discord client with guild-only intents
• Handles slash command interactions
• Routes commands to appropriate handlers

Commands (src/commands/)

• about.ts: Provides bot information using Discord's new UI components
• break.ts: Handles user timeout requests with validation

Web Server (src/server/serve.ts)

• Runs on port 7066 for health monitoring
• Serves static HTML page with bot information
• Provides invite link and documentation links

Logging (src/utils/logger.ts)

• Uses @nhcarrigan/logger package
• Configurable with LOG_TOKEN environment variable

Environment Variables

Required:

• BOT_TOKEN: Discord bot token

Optional:

• LOG_TOKEN: Token for external logging service

Development Setup

1. Install dependencies: pnpm install
2. Build project: pnpm run build
3. Set environment variables in prod.env
4. Start bot: pnpm start

Scripts

• pnpm build: Compile TypeScript to JavaScript
• pnpm lint: Run ESLint with zero warnings tolerance
• pnpm start: Run production build with 1Password environment
• pnpm test: Placeholder test command

Deployment

The bot uses 1Password for secret management in production:

op run --env-file=prod.env -- node prod/index.js

3. Legal Documentation

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

License

Serenya is licensed under "Naomi's Public License" as specified in the source code headers.

Copyright

Copyright held by NHCarrigan/Naomi Carrigan.

Data Handling

The bot processes:

• Discord user IDs and server membership information
• Command interactions and parameters
• No persistent user data storage beyond Discord's built-in timeout functionality

Third-Party Services

The application integrates with:

• Discord API for bot functionality
• External logging service (optional, via LOG_TOKEN)
• nhcarrigan.com CDN for avatar images

4. Contributing Documentation

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

Code Style

The project enforces strict code style through:

• ESLint with @nhcarrigan/eslint-config
• TypeScript with @nhcarrigan/typescript-config
• Maximum warnings tolerance of 0

File Headers

All source files must include the copyright header:

/**
 * @copyright NHCarrigan
 * @license Naomi's Public License
 * @author Naomi Carrigan
 */

Development Standards

• TypeScript strict mode enabled
• ESLint rules must pass with zero warnings
• Proper error handling with logging
• Component-based architecture for Discord UI elements

Key Dependencies

• Discord.js for Discord API interaction
• Fastify for web server functionality
• Custom logger package for structured logging

Bot Permissions

The bot requires:

• "Timeout Members" permission
• Proper role hierarchy positioning
• Guild-only operation (no DM support)

Testing

Currently, the project has a placeholder test setup. Contributors should:

• Ensure code compiles without TypeScript errors
• Verify ESLint passes with zero warnings
• Test bot functionality in a development Discord server

Contribution Process

1. Follow existing code patterns and architecture
2. Maintain TypeScript type safety
3. Include proper error handling and logging
4. Test changes in a development environment
5. Ensure all linting and build checks pass