nhcarrigan/docs
9
0
Fork 0
generated from nhcarrigan/template
Code Issues 2 Pull Requests 6 Actions Releases 1 Activity

feat: new product docs
Node.js CI / Lint and Test (push) Successful in 53s
Details

Browse Source
This commit is contained in:
Naomi Carrigan
2025-09-15 12:50:16 -07:00
parent f43cb18b6c
commit 592a4eb681
10 changed files with 1627 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/components/navigation.ts
+41 -1
View File
@@ -204,7 +204,47 @@ export const navigation = [
link: "/projects/website-headers",
badge: { text: "v2.1.0", variant: "tip" },
},
].sort((a, b) => a.label.localeCompare(b.label)),
{
label: "Altaria",
link: "/projects/altaria",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Caelia",
link: "/projects/caelia",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Chibika",
link: "/projects/chibika",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Lynira",
link: "/projects/lynira",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Pavelle",
link: "/projects/pavelle",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Serenya",
link: "/projects/serenya",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Sorielle",
link: "/projects/sorielle",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Umbrelle",
link: "/projects/umbrelle",
badge: { text: "v1.0.0", variant: "tip" },
},
].sort((a, b) => a.label.localeCompare(b.label)),
},
{
label: "Staff Guidelines",
src/content/docs/projects/altaria.md
+222
View File
@@ -0,0 +1,222 @@
---
title: Altaria
---
Altaria (hereinafter the "Application") is a Discord bot that provides gentle reminders to users when they upload images without alt-text descriptions, promoting accessibility and inclusion within Discord communities.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### What is Altaria?
Altaria is a friendly Discord bot designed to encourage the use of alt-text (alternative text) for images in Discord servers. Alt-text helps make content accessible to users who rely on screen readers and assistive technologies.
### How to Add Altaria to Your Server
1. Use the official invitation link: [Add to Discord](https://discord.com/oauth2/authorize?client_id=1405356559214837860)
2. Select your server from the dropdown menu
3. Grant the necessary permissions:
- Read Messages/View Channels
- Send Messages
- Use Slash Commands
### How Altaria Works
- **Automatic Monitoring**: Altaria monitors messages in channels where it has permissions
- **Image Detection**: When someone posts an image without alt-text, Altaria detects it automatically
- **Gentle Reminders**: The bot responds with one of 100 carefully crafted, encouraging messages
- **Educational Links**: Each reminder includes helpful resources about adding alt-text and writing descriptions
### Using Slash Commands
Altaria supports slash commands that provide information about the bot:
- Type `/` and select an Altaria command to learn more about the bot's features and purpose
### Reminder Message Categories
Altaria's reminders fall into five themed categories:
1. **Gentle Encouragement** (20 messages) - Soft, supportive reminders
2. **Playful/Cute** (20 messages) - Fun, anime-inspired messages with emoticons
3. **Educational** (20 messages) - Informative content about accessibility
4. **Community Vibes** (20 messages) - Emphasizing collective responsibility
5. **Thematic/Fantasy** (20 messages) - Creative, story-driven reminders
### Getting Help
If you need assistance:
- Join the support server: [Discord Server](https://chat.nhcarrigan.com)
- Review Discord's guide: [How to add alt-text](https://support.discord.com/hc/en-us/articles/211866427-How-do-I-upload-images-and-GIFs)
- Use Cordelia for AI-generated descriptions: [Cordelia](https://cordelia.nhcarrigan.com)
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture Overview
Altaria is built using:
- **Node.js** with TypeScript
- **Discord.js** v14.21.0 for Discord API interaction
- **Fastify** v5.5.0 for the web server
- **@nhcarrigan/logger** for structured logging
### Project Structure
```
src/
├── index.ts # Main application entry point
├── modules/
│ └── checkAltText.ts # Core alt-text detection logic
├── config/
│ ├── blocks.ts # Discord UI blocks configuration
│ └── reminders.ts # Collection of reminder messages
├── utils/
│ ├── errorHandler.ts # Error handling utilities
│ ├── logger.ts # Logger configuration
│ └── getRandomValue.ts # Random selection utility
└── server/
└── serve.ts # Web server for health checks
```
### Core Functionality
#### Alt-Text Detection (`src/modules/checkAltText.ts:16`)
- Filters messages for image attachments
- Identifies images without descriptions
- Sends randomized gentle reminders with educational resources
#### Random Reminder Selection (`src/utils/getRandomValue.ts:15`)
- Securely selects random messages using Node.js crypto module
- Ensures variety in user experience
#### Web Server (`src/server/serve.ts:54`)
- Provides health monitoring endpoint on port 6022
- Serves informational landing page with bot details
### Installation Requirements
- Node.js (compatible with ES modules)
- pnpm package manager v10.14.0+
- TypeScript 5.9.2+
### Environment Variables
- `BOT_TOKEN`: Discord bot token (required)
- `LOG_TOKEN`: Logging service token (optional)
### Development Setup
1. Clone the repository
2. Install dependencies: `pnpm install`
3. Create environment file with required tokens
4. Build: `pnpm run build`
5. Start: `pnpm start`
### Deployment
- Production deployment uses 1Password CLI: `op run --env-file=./prod.env -- node prod/index.js`
- Web server runs on port 6022 for health monitoring
- Supports process monitoring and logging
### API Endpoints
- `GET /`: Landing page with bot information and invite link
- Health check endpoint for monitoring services
## 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 License. Full details available at: https://docs.nhcarrigan.com/#/license
### Copyright
Copyright held by Naomi Carrigan (@nhcarrigan).
### Privacy Considerations
- Altaria only processes message content to detect image attachments
- No message content or user data is stored permanently
- Bot interactions are logged for debugging purposes only
- Complies with Discord's Terms of Service and Developer Policy
### Data Processing
- **Message Scanning**: Bot analyses messages in real-time for image attachments
- **Temporary Processing**: Message data is processed only for alt-text detection
- **No Data Retention**: No user messages or personal data are stored
- **Logging**: Error logs may contain anonymized debugging information
### Terms of Use
By adding Altaria to your Discord server, you agree to:
- Allow the bot to read messages in authorized channels
- Accept that the bot will send reminder messages about alt-text
- Understand that the bot promotes accessibility and inclusion
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Getting Started
1. Fork the repository on GitHub
2. Clone your fork locally
3. Install dependencies: `pnpm install`
4. Read the [Contributing Guidelines](CONTRIBUTING.md)
5. Review the [Code of Conduct](CODE_OF_CONDUCT.md)
### Development Workflow
1. Create a feature branch from `main`
2. Make your changes following the coding standards
3. Run linting: `pnpm run lint`
4. Build the project: `pnpm run build`
5. Test your changes thoroughly
6. Submit a Pull Request
### Code Style Guidelines
- **TypeScript**: Strict typing enabled
- **ESLint**: Uses `@nhcarrigan/eslint-config` with max 0 warnings
- **Formatting**: Consistent code style enforced
- **Comments**: JSDoc comments for functions and modules
- **Error Handling**: Comprehensive error handling with UUID tracking
### Adding New Reminder Messages
To add new reminder messages to `src/config/reminders.ts:9`:
1. Choose an appropriate category (gentle, playful, educational, community, thematic)
2. Follow the existing tone and length guidelines
3. Include accessibility-focused messaging
4. Test that messages display correctly in Discord
5. Maintain the current array structure
### Testing Guidelines
- Test Discord interactions manually in a development server
- Verify alt-text detection works for various image types
- Ensure reminder messages display correctly
- Test web server endpoints
### Submission Requirements
- All code must pass linting without warnings
- Changes should include appropriate JSDoc documentation
- Pull requests must include a clear description of changes
- Follow existing patterns and conventions
### Contact for Contributors
- **Discord**: [Chat Server](https://chat.nhcarrigan.com)
- **Forum**: [Discussion Forum](https://forum.nhcarrigan.com)
- **Email**: contact@nhcarrigan.com
- **Issues**: GitHub Issues for bug reports and feature requests
### Recognition
Contributors will be recognized in future releases and project documentation as appropriate.
src/content/docs/projects/caelia.md
+218
View File
@@ -0,0 +1,218 @@
---
title: Caelia
---
Caelia (hereinafter the "Application") is a Discord bot that provides gentle reminders when users utilize non-inclusive language in their messages, helping promote more welcoming and inclusive community spaces.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### What is Caelia?
Caelia is a Discord bot designed to help create more inclusive communities by gently notifying users when they may have used language that could be considered non-inclusive. The bot uses the Alex.js library to analyze messages and provide helpful suggestions for more inclusive alternatives.
### How to Add Caelia to Your Server
1. Visit the authorization link: https://discord.com/oauth2/authorize?client_id=1408530011572535346
2. Select your server and grant the necessary permissions
3. Caelia will automatically begin monitoring messages in channels where she has access
### Required Permissions
- **Read Messages**: To analyse message content
- **Send Messages**: To provide feedback and suggestions
- **View Channels**: To monitor designated channels
### Using Caelia
Once added to your server, Caelia works automatically:
- She monitors messages in real-time
- When potentially non-inclusive language is detected, she replies with gentle suggestions
- Code blocks and links are ignored during analysis
- Bot messages and system messages are not analysed
### Slash Commands
- `/about` - Learn about Caelia and her functionality
### Getting Help
If you need assistance or believe Caelia has made an error, you can:
- Join the support Discord server: https://chat.nhcarrigan.com
- Contact support via email: contact@nhcarrigan.com
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### System Requirements
- Node.js (version compatible with TypeScript 5.9.2)
- npm/pnpm package manager
- Discord Bot Token
- Environment variables configuration
### Installation
1. Clone the repository
2. Install dependencies: `pnpm install`
3. Set up environment variables (see Configuration section)
4. Build the project: `pnpm run build`
5. Start the application: `pnpm start`
### Configuration
The application requires the following environment variable:
- `BOT_TOKEN`: Your Discord bot token
### Architecture Overview
The application consists of several key modules:
#### Core Components
- **`src/index.ts`**: Main entry point that initializes the Discord client and event handlers
- **`src/modules/processMessage.ts`**: Handles message analysis using Alex.js for inclusive language checking
- **`src/modules/processInteraction.ts`**: Processes slash command interactions
- **`src/server/serve.ts`**: Fastify web server for health monitoring and bot information
- **`src/config/alex.ts`**: Configuration for the Alex.js language analysis library
- **`src/utils/logger.ts`**: Logging utilities
#### Message Processing Flow
1. Discord message received via `Events.MessageCreate`
2. Message content filtered (removes code blocks and links)
3. Alex.js analyses content for non-inclusive language
4. If issues found, bot responds with suggestions and feedback link
5. Errors are logged and handled gracefully
#### Web Server
A Fastify server runs on port 7055 providing:
- Health check endpoint
- Bot information and invite link
- Links to source code and documentation
### Dependencies
#### Production Dependencies
- `discord.js`: Discord API wrapper
- `alex`: Inclusive language analysis
- `extra-markdown-text`: Markdown processing utilities
- `fastify`: Web server framework
- `@nhcarrigan/logger`: Logging utilities
#### Development Dependencies
- `typescript`: TypeScript compiler
- `eslint`: Code linting
- Various type definitions and configuration packages
### Scripts
- `pnpm build`: Compile TypeScript to JavaScript
- `pnpm lint`: Run ESLint with zero warnings tolerance
- `pnpm start`: Start the production server
- `pnpm test`: Run tests (currently placeholder)
### Deployment
The application is configured for production deployment using:
- 1Password CLI for environment variable management
- Production environment file (`prod.env`)
- Compiled output in `prod/` directory
## 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 License. All code is copyright NHCarrigan and authored by Naomi Carrigan.
### Data Handling
- Caelia analyses message content in real-time but does not store message data
- Only processes text content, ignoring code blocks and URLs
- No personal data is collected or retained
- All processing occurs in memory and is not persisted
### Privacy Considerations
- Message analysis is performed locally within the bot's runtime
- No message content is transmitted to external services beyond Discord's API
- The Alex.js library runs locally and does not send data externally
- Error logging may contain message metadata but not content
### Service Availability
- The bot is provided as-is with no guarantees of uptime
- Support is provided on a best-effort basis
- Service may be interrupted for maintenance or updates
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Development Setup
1. Fork the repository
2. Clone your fork locally
3. Install dependencies: `pnpm install`
4. Set up your development environment variables
5. Run linting: `pnpm run lint`
6. Build the project: `pnpm run build`
### Code Style
The project uses:
- ESLint with `@nhcarrigan/eslint-config` for code quality
- TypeScript with strict configuration
- Maximum 0 warnings policy for linting
### Project Structure
```
src/
├── config/ # Configuration files
│ └── alex.ts # Alex.js configuration
├── modules/ # Core application modules
│ ├── processMessage.ts # Message analysis logic
│ └── processInteraction.ts # Slash command handling
├── server/ # Web server components
│ └── serve.ts # Fastify server setup
├── utils/ # Utility functions
│ └── logger.ts # Logging utilities
└── index.ts # Application entry point
```
### Contributing Guidelines
1. Follow the existing code style and patterns
2. Ensure all linting passes with zero warnings
3. Test your changes thoroughly
4. Update documentation as needed
5. Submit pull requests with clear descriptions
### Key Areas for Contribution
- **Language Rules**: Enhancing Alex.js configuration for better accuracy
- **Error Handling**: Improving error recovery and user experience
- **Performance**: Optimizing message processing speed
- **Features**: Adding new functionality while maintaining simplicity
- **Documentation**: Improving user and developer documentation
### Reporting Issues
- Use GitHub issues for bug reports
- Join the Discord support server for discussions: https://chat.nhcarrigan.com
- Email support: contact@nhcarrigan.com
### Code Review Process
All contributions require:
- Code review by project maintainers
- Passing lint checks (`pnpm run lint`)
- Successful build (`pnpm run build`)
- Adherence to project conventions and patterns
src/content/docs/projects/chibika.md
+196
View File
@@ -0,0 +1,196 @@
---
title: Chibika
---
Chibika (hereinafter the "Application") is a Discord bot that provides ASCII art on demand. The Application offers curated collections of ASCII art in categories such as anime and cats, along with emoji ASCII art, delivered through Discord's slash command interface with subscription-based access control.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Getting Started
1. **Add Chibika to Your Discord Server**: Use the [Discord OAuth2 authorization link](https://discord.com/oauth2/authorize?client_id=1396225647269122098) to add Chibika to your Discord server.
2. **Purchase Server Subscription**: To use Chibika's features, you must purchase a server subscription through Discord's built-in store system.
### Available Commands
#### `/about`
Displays information about Chibika, including:
- What the bot does
- How to get started with server subscriptions
- Support and help resources
- Links to Discord server and forum for assistance
#### `/ascii [category]`
Retrieves random ASCII art from the specified category:
- **anime**: Anime-themed ASCII art
- **cats**: Cat-themed ASCII art
Usage: `/ascii category:anime` or `/ascii category:cats`
#### `/emoji`
Retrieves random emoji-based ASCII art from the emoji collection.
### Features
- **Random Art Selection**: Each command returns a randomly selected piece from the respective collection
- **Subscription-Based Access**: Commands require an active Discord server subscription
- **Interactive Components**: Art is displayed using Discord's modern component system
- **Error Handling**: Graceful error messages for invalid inputs or system issues
### Support
If you encounter issues or need assistance:
- Join the [Discord support server](https://chat.nhcarrigan.com)
- Visit the [support forum](https://forum.nhcarrigan.com)
- Contact via email: `contact@nhcarrigan.com`
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture
Chibika is built using:
- **Discord.js v14.21.0**: Discord API integration
- **Fastify v5.4.0**: Web server for health monitoring
- **TypeScript**: Type-safe development
- **Node.js**: Runtime environment
### Project Structure
```
src/
├── assets/ # ASCII art collections
│ ├── anime.ts # Anime ASCII art data
│ ├── cats.ts # Cat ASCII art data
│ └── emoji.ts # Emoji ASCII art data
├── commands/ # Discord slash commands
│ ├── about.ts # About command handler
│ ├── ascii.ts # ASCII art command handler
│ └── emoji.ts # Emoji command handler
├── config/ # Configuration files
│ └── entitlements.ts # Guild entitlement configuration
├── events/ # Discord event handlers
│ └── interactionCreate.ts # Command interaction handling
├── interfaces/ # TypeScript interfaces
│ ├── ascii.ts # ASCII art data structure
│ └── command.ts # Command handler interface
├── modules/ # Utility modules
│ ├── getArtComponents.ts # Discord component generation
│ └── sendUnentitledResponse.ts # Subscription check responses
├── server/ # Web server
│ └── serve.ts # Health monitoring server
├── utils/ # Utility functions
│ ├── checkEntitlement.ts # Subscription verification
│ ├── errorHandler.ts # Error handling
│ ├── getRandomValue.ts # Random selection utility
│ └── logger.ts # Logging utility
└── index.ts # Application entry point
```
### Installation and Setup
1. **Prerequisites**:
- Node.js (compatible with package manager pnpm@10.13.1)
- Discord Bot Token
- Discord Application with appropriate permissions
2. **Installation**:
```bash
pnpm install
```
3. **Environment Configuration**:
Create a `prod.env` file with:
```
DISCORD_TOKEN=your_discord_bot_token_here
```
4. **Build**:
```bash
pnpm run build
```
5. **Start**:
```bash
pnpm start
```
### Development
- **Linting**: `pnpm run lint` (ESLint with @nhcarrigan/eslint-config)
- **Testing**: `pnpm run test` (Vitest)
- **TypeScript**: Configured with @nhcarrigan/typescript-config
### Key Components
#### Entitlement System
- Subscription verification through Discord's entitlement API (`src/utils/checkEntitlement.ts:16`)
- Fallback to hardcoded entitled guilds (`src/config/entitlements.ts`)
- Un-entitled users receive subscription prompts (`src/modules/sendUnentitledResponse.ts`)
#### ASCII Art Management
- Structured data format with `text` and `author` fields (`src/interfaces/ascii.ts:7`)
- Category-based organization (anime, cats, emoji)
- Random selection utility (`src/utils/getRandomValue.ts`)
#### Web Server
- Health monitoring server on port 5018 (`src/server/serve.ts:65`)
- Static HTML page with bot information and links
- Integration with nhcarrigan.com ecosystem
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### Licensing
- Source code licensed under Naomi's Public License
- Copyright held by Naomi Carrigan (@nhcarrigan)
### Terms and Privacy
- [Global Terms of Service](https://docs.nhcarrigan.com/#/terms)
- [Privacy Policy](https://docs.nhcarrigan.com/#/privacy)
### Security
- Security guidelines and reporting procedures outlined in `SECURITY.md`
- Responsible disclosure encouraged through GitHub issues
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Contributing Guidelines
- Comprehensive contributing guidelines: https://docs.nhcarrigan.com/#/contributing
- Additional project-specific guidelines in `CONTRIBUTING.md`
### Code Standards
- **ESLint Configuration**: @nhcarrigan/eslint-config v5.2.0
- **TypeScript**: Strict configuration via @nhcarrigan/typescript-config v4.0.0
- **Testing**: Vitest for unit testing
- **Code Style**: Enforced through automated linting with zero warnings policy
### Development Workflow
1. Fork the repository
2. Create feature branch
3. Make changes following code standards
4. Run tests and linting: `pnpm run test && pnpm run lint`
5. Build successfully: `pnpm run build`
6. Submit pull request
### Issue Reporting
- Bug reports and feature requests via [GitHub Issues](https://github.com/anthropics/claude-code/issues)
- Security issues through responsible disclosure (see `SECURITY.md`)
### Community
- [Discord Server](https://chat.nhcarrigan.com) for real-time discussion
- Code of Conduct available at repository root
### Architecture Decisions
- Discord.js v14 for modern Discord API features
- TypeScript for type safety and developer experience
- Fastify for lightweight web server functionality
- Component-based Discord interactions for enhanced user experience
- Subscription-based access model through Discord's monetization features
src/content/docs/projects/lynira.md
+195
View File
@@ -0,0 +1,195 @@
---
title: Lynira
---
Lynira (hereinafter the "Application") is a link shortening service managed via a Discord bot with subscription-based access control and usage limits.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Overview
Lynira is a Discord-integrated URL shortening service that allows users to create shortened links through Discord commands. The service operates on a subscription model with different tiers offering varying numbers of shortened URLs.
### Discord Commands
#### `/add`
Creates a new shortened URL.
- **Parameters:**
- `slug` (required): The short identifier for your URL (e.g., "my-link")
- `url` (required): The full URL to redirect to (must be a valid HTTP/HTTPS URL)
- **Usage:** `/add slug:my-link url:https://example.com`
- **Result:** Creates a short URL accessible at `https://lynira.link/mylink`
#### `/list`
Displays all your active shortened URLs along with usage statistics.
- **Features:**
- Shows current usage count vs. subscription limit
- Provides clickable buttons to access Discord server and forum
- Lists all active short URLs with their destinations
#### `/remove`
Removes a shortened URL from your account.
- **Parameters:**
- `slug` (required): The slug identifier to remove
- **Usage:** `/remove slug:mylink`
- **Note:** Removed slugs cannot be reused for security reasons
#### `/about`
Displays information about the Lynira service.
### Subscription Tiers
The service operates on multiple subscription tiers with different link limits:
- **Personal**: Limited number of links
- **Professional**: Higher link allowance
- **Business**: Business-level capacity
- **Organisation**: Significant link capacity
- **Enterprise**: Maximum link capacity
### Web Interface
The service provides several web pages:
- **Home page** (`/`): Service information
- **Error page** (`/error`): Displayed when system errors occur
- **Unsubscribed page** (`/unsub`): Shown when accessing links from unsubscribed users
- **Over limit page** (`/overlimit`): Displayed when users exceed their subscription limits
- **404 page** (`/404`): Shown for non-existent or deleted links
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture
Lynira is built using:
- **Node.js** with TypeScript
- **Discord.js** for Discord bot functionality
- **Fastify** web server for HTTP handling
- **Prisma** ORM for database operations
- **PostgreSQL** database (implied from Prisma usage)
### Core Components
#### Discord Bot (`src/index.ts`)
The main entry point that initializes:
- Prisma database connection
- Discord client with minimal intents
- Command processing system
- Web server instance
#### Web Server (`src/server/serve.ts`)
Fastify-based HTTP server providing:
- Static route handling
- Dynamic link redirection
- Subscription validation
- Usage limit enforcement
- Error page serving
#### Command System
Commands are modularized in `src/commands/`:
- `add.ts`: URL creation with validation and limit checking
- `list.ts`: User link listing with usage statistics
- `remove.ts`: Link deletion with ownership verification
- `about.ts`: Service information
#### Core Modules
- **`getEntitlement.ts`**: Discord entitlement validation
- **`getSkuLimit.ts`**: Subscription tier limit determination
- **`processCommand.ts`**: Command routing and execution
- **`sendUnintitledResponse.ts`**: Unsubscribed user handling
### Database Schema
The application uses Prisma with a `links` table containing:
- `id`: Primary key
- `slug`: Short URL identifier
- `url`: Target URL
- `userId`: Discord user ID
- `deleted`: Soft deletion flag
### Environment Configuration
Required environment variables:
- `BOT_TOKEN`: Discord bot token
- Database connection string (Prisma configuration)
### Security Features
- URL validation with regex patterns
- Reserved slug protection
- User ownership verification
- Subscription status validation
- Soft deletion for security
- Error handling and logging
### Deployment
- Production build via `npm run build`
- Prisma schema generation
- Environment-based configuration
- Port 5044 for web server
- 1Password integration for production secrets
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### Licensing
The Application is licensed under "Naomi's Public License" as indicated in the source code headers.
### Copyright
Copyright held by Naomi Carrigan (@nhcarrigan).
### Data Handling
The Application processes:
- Discord user IDs for authentication
- User-provided URLs for shortening
- Link access patterns for subscription enforcement
- Discord entitlement data for subscription validation
### Service Terms
- Users must maintain active Discord subscriptions
- Removed links cannot be reused for security
- Link editing is not permitted after creation
- Service availability depends on Discord API functionality
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Development Setup
1. Clone the repository
2. Install dependencies: `pnpm install`
3. Set up Prisma database connection
4. Configure Discord bot token
5. Run development build: `npm run build`
### Code Standards
- **ESLint**: Enforced with `@nhcarrigan/eslint-config`
- **TypeScript**: Strict configuration via `@nhcarrigan/typescript-config`
- **Testing**: Currently no test suite (`npm test` placeholder)
- **Linting**: `npm run lint` with zero warnings policy
### Project Structure
```
src/
├── commands/ # Discord slash commands
├── config/ # Configuration files and handlers
├── interfaces/ # TypeScript interfaces
├── modules/ # Core business logic
├── server/ # Web server and HTML templates
└── utils/ # Utility functions
```
### Key Patterns
- Error handling with centralized `errorHandler`
- Logging via `@nhcarrigan/logger`
- Command pattern for Discord interactions
- Subscription-based access control
- Soft deletion for data safety
### Contribution Guidelines
- Follow existing code patterns and conventions
- Maintain TypeScript strict mode compliance
- Include proper error handling
- Add logging for important operations
- Respect subscription and security models
### Reserved Components
- Reserved slugs defined in `src/config/reservedSlugs.ts`
- Admin privileges for user ID `465650873650118659`
- Discord entitlement SKU IDs are environment-specific
src/content/docs/projects/pavelle.md
+174
View File
@@ -0,0 +1,174 @@
---
title: Pavelle
---
Pavelle (hereinafter the "Application") is a Discord bot that allows users to throw things (like cake) at their fellow server members in a fun, interactive game with scoring and leaderboards.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Commands
The bot provides the following slash commands:
#### `/throw [target]`
- **Purpose**: Throw an item (based on server theme) at another user
- **Usage**: `/throw @username` or `/throw` (for random target)
- **Rate Limit**: 10 throws per hour per user (resets every hour)
- **Scoring System**:
- **Counter Hit (-1 points)**: Target catches and throws back (10% chance)
- **Miss (0 points)**: Throw fails to hit target (40% chance)
- **Hit (+1 point)**: Successfully hits target (45% chance)
- **Bonus Hit (+5 points)**: Exceptional throw with special effects (5% chance)
#### `/leaderboard`
- **Purpose**: Display server leaderboard showing top 10 players and your rank
- **Usage**: `/leaderboard`
- **Features**: Shows total points and ranking for all players
#### `/config [theme] [spoiler]`
- **Purpose**: Configure server settings (requires Manage Guild permission)
- **Parameters**:
- `theme`: Visual theme for throws (currently supports "cake")
- `spoiler`: Whether to hide result GIFs behind spoiler tags
- **Usage**: `/config theme:cake spoiler:true`
#### `/about`
- **Purpose**: Display information about the bot
### Gameplay Features
- **Hourly Reset**: Throw counts reset at the top of every hour
- **Interactive Results**: Each throw result includes themed messages, GIFs, and buttons
- **Persistent Scoring**: Points are tracked across sessions and contribute to server leaderboards
- **Guild-Specific**: Each server maintains its own leaderboard and configuration
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Prerequisites
- Node.js (version compatible with TypeScript 5.9.2)
- pnpm package manager (version 10.14.0+)
- PostgreSQL database (via Prisma ORM)
- Discord Bot Token
- 1Password CLI (for production secrets management)
### Installation
1. Clone the repository
2. Install dependencies: `pnpm install`
3. Set up database with Prisma: `pnpm run build` (includes `prisma generate`)
4. Configure environment variables (see Configuration section)
### Configuration
Required environment variables:
- `BOT_TOKEN`: Discord bot token
- Database connection string for Prisma
### Scripts
- `pnpm run build`: Generate Prisma client and compile TypeScript
- `pnpm run lint`: Run ESLint with zero warnings policy
- `pnpm run start`: Start production build with 1Password environment
- `pnpm test`: Currently returns success (no tests implemented)
### Architecture
**Core Components**:
- **Discord Client**: Handles Discord.js interactions with guild-only intent filtering
- **Prisma Database**: Manages user scores and server configurations
- **Caching System**: Hourly throw count cache to prevent database spam
- **Scheduled Jobs**: Automatic cache clearing every hour
- **Fastify Server**: Web server component for additional functionality
**Key Modules**:
- `processCommand.ts`: Routes slash commands to handlers
- `processButton.ts`: Handles interactive button responses
- `generateScore.ts`: Implements weighted random scoring system
- `checkEntitlement.ts`: Validates guild permissions/access
- `getThrowComponents.ts`: Builds Discord UI components for results
**Database Schema**:
- `users`: Stores per-server user scores (`serverId`, `userId`, `points`)
- `servers`: Stores per-server configuration (`serverId`, `theme`, `spoiler`)
### Security Features
- Guild-only operation (DM interactions blocked)
- Permission-based configuration (Manage Guild required)
- Input validation and type guards
- Comprehensive error handling with UUID tracking
- Rate limiting via hourly throw counts
## 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 License as specified in the source code headers.
### Data Collection
The Application collects and stores:
- Discord user IDs and server IDs for scoring functionality
- Throw counts and point totals per user per server
- Server configuration preferences (themes, spoiler settings)
### Data Retention
- User scores persist indefinitely unless manually removed
- Throw count cache is cleared hourly
- No message content or personal information is stored
### Third-Party Services
The Application integrates with:
- Discord API for bot functionality
- Database service for persistent storage
- 1Password for secure credential management (production)
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Development Setup
1. **Environment**: Node.js with TypeScript, pnpm package manager
2. **Code Standards**: ESLint with NHCarrigan configuration (zero warnings policy)
3. **Database**: Prisma ORM with PostgreSQL
4. **Framework**: Discord.js v14 with slash commands
### Code Style Guidelines
- **Licensing**: All files must include copyright header with Naomi's Public License
- **Comments**: Minimal commenting (code should be self-documenting)
- **TypeScript**: Strict typing with explicit interfaces
- **ESLint**: Zero warnings policy enforced in CI
- **Naming**: Follow existing conventions (camelCase, descriptive names)
### Architecture Patterns
- **Command Pattern**: Each slash command in separate file with common interface
- **Error Handling**: Centralized error handler with UUID tracking
- **Type Safety**: Comprehensive TypeScript interfaces and type guards
- **Separation of Concerns**: Clear module boundaries (commands, modules, utils, config)
### Adding New Features
1. **Themes**: Add new theme data to `config/themes.ts` with all message variants
2. **Commands**: Create new command file in `commands/` implementing `Command` interface
3. **Scoring**: Modify `generateScore.ts` for new scoring mechanics
4. **Database**: Update Prisma schema and run migrations as needed
### Testing
- Currently no test framework implemented
- Manual testing via Discord bot interactions required
- Lint checking enforced: `pnpm run lint`
### Deployment
- Production uses 1Password CLI for secure environment management
- Build process includes Prisma client generation
- TypeScript compilation to `prod/` directory
src/content/docs/projects/serenya.md
+201
View File
@@ -0,0 +1,201 @@
---
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:
```bash
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:
```typescript
/**
* @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
src/content/docs/projects/sorielle.md
+158
View File
@@ -0,0 +1,158 @@
---
title: Sorielle
---
Sorielle (hereinafter the "Application") is a Discord bot that automatically deletes messages from a venting channel after a configurable timeout period, providing a safe space for users to express themselves with temporary visibility.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Adding Sorielle to Your Server
You can add Sorielle to your Discord server using this [invitation link](https://discord.com/oauth2/authorize?client_id=1391489982887362761).
### Getting Started
1. **Purchase Server Subscription**: Before configuring Sorielle, you need to purchase the server subscription from the Discord store.
2. **Configure Your Venting Channel**: Use the `/config` command to set up your venting channel:
- Select the text channel where messages should be automatically deleted
- Set the timeout duration (in seconds) after which messages will be deleted
- Ensure Sorielle has the necessary permissions: `Manage Messages`, `View Channel`, and `Read Message History`
3. **Using the Venting Channel**: Once configured, any message sent to the designated venting channel will be automatically deleted after the specified timeout period.
### Available Commands
- `/config <channel> <timeout>`: Configure the venting channel and deletion timeout
- `/about`: Learn more about Sorielle and get help information
### Getting Help
If you need assistance or encounter issues:
- Join the [Discord Server](https://chat.nhcarrigan.com)
- Visit the [Forum](https://forum.nhcarrigan.com)
- Contact via email: contact@nhcarrigan.com
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### System Requirements
- Node.js (compatible with Discord.js 14.21.0)
- PostgreSQL database (via Prisma)
- Discord bot token
- Environment variables for configuration
### Architecture Overview
Sorielle is built using:
- **Discord.js**: Discord API interaction and bot framework
- **Prisma**: Database ORM for PostgreSQL
- **Fastify**: Web server for health monitoring and landing page
- **TypeScript**: Type-safe development
### Key Components
- **Main Bot Logic** (`src/index.ts`): Core Discord client setup and event handling
- **Message Handler** (`src/events/messageCreate.ts`): Processes messages in venting channels and schedules deletions
- **Commands** (`src/commands/`): Slash command implementations
- **Database Models**: Prisma-managed PostgreSQL schema for storing server configurations
- **Web Server** (`src/server/serve.ts`): Health monitoring endpoint on port 5019
- **Entitlement System** (`src/utils/checkEntitlement.ts`): Validates server subscriptions
### Installation & Setup
1. Clone the repository
2. Install dependencies: `pnpm install`
3. Set up environment variables (Discord token, database URL)
4. Generate Prisma client: `prisma generate`
5. Build the project: `pnpm run build`
6. Start the application: `pnpm start`
### Database Schema
The application uses a `vents` table to store:
- `serverId`: Discord server ID
- `channelId`: Configured venting channel ID
- `ttl`: Time-to-live for messages (in seconds)
### Development
- **Linting**: `pnpm run lint`
- **Building**: `pnpm run build`
- **Testing**: `pnpm run test` (currently placeholder)
## 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 License. Full license terms are available at [docs.nhcarrigan.com](https://docs.nhcarrigan.com/#/license).
### Copyright
Copyright held by Naomi Carrigan.
### Privacy & Data Handling
- Sorielle stores minimal server configuration data (server ID, channel ID, timeout settings)
- Messages are automatically deleted according to configured timeouts
- No message content is permanently stored or logged
- For detailed privacy policies, refer to [PRIVACY.md](PRIVACY.md)
### Terms of Service
For complete terms of service, refer to [TERMS.md](TERMS.md).
### Security
For security-related concerns, please review [SECURITY.md](SECURITY.md) for our security policy and reporting procedures.
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Contributing Guidelines
Complete contributing guidelines are available at [docs.nhcarrigan.com](https://docs.nhcarrigan.com/#/contributing).
### Code of Conduct
Before interacting with our community, please read our [Code of Conduct](CODE_OF_CONDUCT.md).
### Development Environment
- **Language**: TypeScript
- **Framework**: Discord.js v14
- **Database**: PostgreSQL with Prisma ORM
- **Package Manager**: pnpm
- **Linting**: ESLint with @nhcarrigan/eslint-config
### Code Structure
- `src/commands/`: Slash command implementations
- `src/events/`: Discord event handlers
- `src/interfaces/`: TypeScript interface definitions
- `src/modules/`: Reusable modules and utilities
- `src/utils/`: Utility functions (logging, error handling, entitlements)
- `src/config/`: Configuration files
- `src/server/`: Web server implementation
### Submitting Changes
1. Fork the repository
2. Create a feature branch
3. Make your changes following existing code patterns
4. Ensure linting passes: `pnpm run lint`
5. Test your changes thoroughly
6. Submit a pull request
### Getting Help
For development questions or support:
- [Discord Server](https://chat.nhcarrigan.com)
- GitHub Issues for bug reports and feature requests
src/content/docs/projects/umbrelle.md
+214
View File
@@ -0,0 +1,214 @@
---
title: Umbrelle
---
Umbrelle (hereinafter the "Application") is a Discord bot that allows server administrators to configure honeypot channels to automatically detect and soft-ban compromised accounts. When an account posts in a designated honeypot channel, the bot will temporarily ban the user to remove their message history and immediately unban them, allowing them to return once they've recovered their account.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Getting Started
1. **Adding Umbrelle to Your Server**
- Use the Discord OAuth2 authorization link: https://discord.com/oauth2/authorize?client_id=1412945347134881862
- Ensure you have "Manage Server" permissions to add bots
2. **Setting Up a Honeypot Channel**
- Use the `/honeypot` command followed by the channel you want to designate as a honeypot
- Only users with "Manage Guild" permissions can configure honeypot channels
- Example: `/honeypot channel:#suspicious-activity`
3. **How It Works**
- When any user (excluding bots and system messages) posts in the configured honeypot channel, they will be automatically soft-banned
- Soft-ban process:
- User receives a DM explaining the situation
- User is banned to remove message history (24 hours of messages)
- User is immediately unbanned and can rejoin when ready
- Only accounts that are "bannable" (not server owners, higher role hierarchy) will be affected
### Available Commands
- `/about` - Display information about Umbrelle and links to support resources
- `/honeypot <channel>` - Configure a honeypot channel (requires Manage Guild permission)
### Support and Help
If you need assistance:
- Join the support Discord server: https://chat.nhcarrigan.com
- Visit the documentation: https://docs.nhcarrigan.com/
- View source code: https://git.nhcarrigan.com/nhcarrigan/umbrelle
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Architecture Overview
Umbrelle is built with:
- **Discord.js v14** - Discord API interaction
- **TypeScript** - Type-safe development
- **Prisma** - Database ORM
- **MongoDB** - Data persistence
- **Fastify** - Web server for health monitoring
- **1Password CLI** - Secure environment variable management
### System Requirements
- Node.js (compatible with the version specified in package.json)
- MongoDB database
- Discord Bot Token
- 1Password CLI (for production deployment)
### Project Structure
```
src/
├── components/ # Discord UI components
│ └── about.ts # About command interface
├── events/ # Discord event handlers
│ ├── handleInteraction.ts # Slash command processing
│ ├── handleMessage.ts # Message event handling
│ └── handleReady.ts # Bot initialization
├── interfaces/ # TypeScript type definitions
│ └── umbrelle.ts # Core application interface
├── server/ # Web server implementation
│ └── serve.ts # Health monitoring server
├── utils/ # Utility functions
│ └── logger.ts # Logging implementation
└── index.ts # Application entry point
```
### Database Schema
The application uses a simple MongoDB schema with Prisma:
```prisma
model Honeypots {
id String @id @default(auto()) @map("_id") @db.ObjectId
serverId String @unique
channelId String @unique
}
```
### Environment Variables
Required environment variables:
- `BOT_TOKEN` - Discord bot token
- `MONGO_URI` - MongoDB connection string
### Build and Deployment
1. **Development Setup**
```bash
npm install
npm run build
```
2. **Production Deployment**
```bash
npm run start # Uses 1Password CLI for environment management
```
3. **Available Scripts**
- `build` - Generate Prisma client and compile TypeScript
- `lint` - Run ESLint with zero warnings tolerance
- `start` - Production start with 1Password environment loading
- `test` - Placeholder test command
### Security Considerations
- Bot permissions are limited to Guild and Guild Messages intents
- Only users with Manage Guild permissions can configure honeypots
- Soft-ban mechanism preserves user ability to rejoin
- No sensitive data logging or exposure
- Follows Discord's best practices for bot development
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### License
This application is licensed under Naomi's Public License. The full license text can be found in the LICENSE.md file in the repository.
### Copyright
Copyright held by Naomi Carrigan (NHCarrigan).
### Data Handling
- Umbrelle stores minimal data: server IDs and channel IDs for honeypot configuration
- No user messages, personal information, or sensitive data is stored
- Database records are only used for bot functionality
- Users can request removal of their server's data by removing the bot from their server
### Terms of Service
Users should refer to TERMS.md for detailed terms of service.
### Privacy Policy
Users should refer to PRIVACY.md for detailed privacy policy information.
### Security Policy
Security concerns should be reported according to the guidelines in SECURITY.md.
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Development Environment
1. **Prerequisites**
- Node.js and npm/pnpm
- MongoDB instance (local or cloud)
- Discord application with bot token
- Git for version control
2. **Setup Process**
```bash
git clone <repository-url>
cd umbrelle
pnpm install
# Configure environment variables
pnpm run build
```
3. **Code Style**
- ESLint configuration enforces code standards
- Maximum warnings: 0 (strict enforcement)
- TypeScript strict mode enabled
- Follow existing patterns in the codebase
### Contribution Guidelines
Please refer to CONTRIBUTING.md for detailed contribution guidelines including:
- Code of conduct (CODE_OF_CONDUCT.md)
- Pull request process
- Issue reporting
- Development workflow
### Code Quality Standards
- All code must pass ESLint validation with zero warnings
- TypeScript strict mode compliance required
- Proper error handling for all async operations
- Comprehensive JSDoc comments for public functions
- Follow existing architectural patterns
### Testing
Currently, the project has placeholder tests. Contributors are welcome to:
- Implement comprehensive test coverage
- Add unit tests for core functionality
- Create integration tests for Discord interactions
- Establish CI/CD testing pipeline
### Contact and Support
For development questions and support:
- Join the Discord community: https://chat.nhcarrigan.com
- Email: contact@nhcarrigan.com
- Review existing GitHub issues and discussions