generated from nhcarrigan/template
This commit is contained in:
@@ -0,0 +1,373 @@
|
||||
---
|
||||
title: Callista
|
||||
---
|
||||
|
||||
Callista (hereinafter the "Application") is a Discord bot that allows users to bookmark messages so they can find them later. The Application provides a simple interface for saving message links via DM, with optional note-taking capabilities to help organize and remember why messages were bookmarked.
|
||||
|
||||
## 1. User Documentation
|
||||
|
||||
This section is for those interacting with a live instance of the Application.
|
||||
|
||||
### 1.1 Adding the Bot
|
||||
|
||||
Callista is available as a Discord user-installable application. You can add Callista to your Discord account by visiting:
|
||||
https://discord.com/oauth2/authorize?client_id=1391494389477412906
|
||||
|
||||
### 1.2 Bookmarking Messages
|
||||
|
||||
To bookmark a message:
|
||||
|
||||
1. Right-click (or long-press on mobile) any message in a guild or private channel
|
||||
2. Navigate to Apps → Bookmark
|
||||
3. Callista will send you a DM containing the message link
|
||||
|
||||
**Note:** You must have Direct Messages enabled to receive bookmarks. If you receive an error, check your Discord privacy settings.
|
||||
|
||||
### 1.3 Adding Notes to Bookmarks
|
||||
|
||||
Each bookmark can have an associated note to help you remember context:
|
||||
|
||||
1. When you receive a bookmark DM, click the **Add Note** button
|
||||
2. A modal will appear asking "What would you like to note down?"
|
||||
3. Enter your note (1-1000 characters)
|
||||
4. Your note will be appended to the bookmark message
|
||||
|
||||
### 1.4 Editing Notes
|
||||
|
||||
To edit an existing note on a bookmark:
|
||||
|
||||
1. Click the **Edit Note** button on the bookmark message
|
||||
2. Update the note text in the modal
|
||||
3. The bookmark message will be updated with your new note
|
||||
|
||||
### 1.5 Deleting Bookmarks
|
||||
|
||||
To delete a bookmark from your DMs:
|
||||
|
||||
1. Right-click the bookmark message in your DM with Callista
|
||||
2. Navigate to Apps → Delete
|
||||
3. The bookmark message will be deleted
|
||||
|
||||
**Note:** The Delete command only works in DMs with Callista (bot DM context).
|
||||
|
||||
### 1.6 Additional Features
|
||||
|
||||
Each bookmark message includes convenient buttons:
|
||||
- **Add Note/Edit Note**: Add or modify notes on your bookmarks
|
||||
- **Join our Discord**: Link to the support server (https://chat.nhcarrigan.com)
|
||||
- **Donate**: Premium button for supporting the bot developer
|
||||
|
||||
### 1.7 Command Reference
|
||||
|
||||
| Command | Type | Context | Description |
|
||||
|---------|------|---------|-------------|
|
||||
| Bookmark | Message Context Menu | Guilds, Private Channels | Sends you a DM with the message link |
|
||||
| Delete | Message Context Menu | Bot DMs | Deletes the bookmark message |
|
||||
|
||||
## 2. Technical Documentation
|
||||
|
||||
This section is for those interested in running their own instance of the Application.
|
||||
|
||||
### 2.1 Prerequisites
|
||||
|
||||
- Node.js (compatible with version specified in package.json)
|
||||
- pnpm 10.17.1 or higher (specified in packageManager field)
|
||||
- A Discord Bot Token
|
||||
- 1Password CLI (op) for production environment variables (or modify start script)
|
||||
|
||||
### 2.2 Dependencies
|
||||
|
||||
**Runtime Dependencies:**
|
||||
- `discord.js` (14.22.1): Discord API wrapper
|
||||
- `@nhcarrigan/logger` (1.0.0): Logging utility
|
||||
- `fastify` (5.6.1): Web server for health monitoring
|
||||
|
||||
**Development Dependencies:**
|
||||
- TypeScript (5.9.2)
|
||||
- ESLint with @nhcarrigan configuration
|
||||
- tsx for development execution
|
||||
|
||||
### 2.3 Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd callista
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
3. Create a production environment file (`prod.env`) with the following:
|
||||
```
|
||||
BOT_TOKEN=your_discord_bot_token
|
||||
```
|
||||
|
||||
4. Register Discord commands by running:
|
||||
```bash
|
||||
node commandData.js
|
||||
```
|
||||
Copy the output JSON and register it via the Discord Developer Portal or API.
|
||||
|
||||
### 2.4 Building
|
||||
|
||||
Compile TypeScript to JavaScript:
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
Output is generated in the `prod/` directory.
|
||||
|
||||
### 2.5 Running
|
||||
|
||||
**Production:**
|
||||
```bash
|
||||
pnpm start
|
||||
```
|
||||
|
||||
This uses 1Password CLI to inject environment variables. Modify the start script in `package.json` if using a different secrets management solution.
|
||||
|
||||
**Development:**
|
||||
```bash
|
||||
tsx src/index.ts
|
||||
```
|
||||
|
||||
### 2.6 Architecture Overview
|
||||
|
||||
**Project Structure:**
|
||||
```
|
||||
src/
|
||||
├── index.ts # Main entry point, Discord client setup
|
||||
├── server/
|
||||
│ └── serve.ts # Fastify web server for health checks (port 6111)
|
||||
├── interactions/
|
||||
│ ├── bookmark.ts # Bookmark command handler
|
||||
│ └── deleteCmd.ts # Delete command handler
|
||||
├── buttons/
|
||||
│ ├── addNote.ts # Add note button definition
|
||||
│ ├── editNote.ts # Edit note button definition
|
||||
│ ├── discord.ts # Discord invite button
|
||||
│ └── donate.ts # Premium donation button
|
||||
├── modals/
|
||||
│ └── note.ts # Note input modal definition
|
||||
└── utils/
|
||||
└── logger.ts # Logger configuration
|
||||
```
|
||||
|
||||
**Component Interactions:**
|
||||
|
||||
1. **Discord Client** (`index.ts:22-24`): Initialized with no intents (interaction-only bot)
|
||||
2. **Interaction Handler** (`index.ts:27-81`): Routes interactions to appropriate handlers
|
||||
3. **Web Server** (`server/serve.ts:54-79`): Runs on port 6111 for health monitoring
|
||||
4. **Message Context Commands**: Registered via `commandData.js` with user-install integration
|
||||
|
||||
### 2.7 Bot Configuration
|
||||
|
||||
The bot requires the following Discord application settings:
|
||||
|
||||
**Intents:** None (the bot uses no gateway intents)
|
||||
|
||||
**Integration Types:**
|
||||
- User Install (ApplicationIntegrationType.UserInstall)
|
||||
|
||||
**Interaction Contexts:**
|
||||
- Bookmark: Guilds and Private Channels
|
||||
- Delete: Bot DMs only
|
||||
|
||||
**Commands to Register:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"type": 3,
|
||||
"name": "Bookmark",
|
||||
"contexts": [0, 2],
|
||||
"integration_types": [1]
|
||||
},
|
||||
{
|
||||
"type": 3,
|
||||
"name": "Delete",
|
||||
"contexts": [1],
|
||||
"integration_types": [1]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 2.8 Environment Variables
|
||||
|
||||
| Variable | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| BOT_TOKEN | Yes | Discord bot token for authentication |
|
||||
|
||||
### 2.9 Monitoring and Health Checks
|
||||
|
||||
The Application exposes a web server on port 6111:
|
||||
- **Endpoint:** `GET /`
|
||||
- **Response:** HTML page with bot information
|
||||
- **Purpose:** Health monitoring and bot information display
|
||||
|
||||
### 2.10 Logging
|
||||
|
||||
Logging is handled via `@nhcarrigan/logger` with the following log levels:
|
||||
- `debug`: Informational messages (bot online, server started)
|
||||
- `error`: Error conditions (server failures, etc.)
|
||||
|
||||
Logs are written from `utils/logger.ts:1`.
|
||||
|
||||
### 2.11 Error Handling
|
||||
|
||||
The Application implements error handling for:
|
||||
- Failed DM delivery (user has DMs disabled) - `interactions/bookmark.ts:43-46`
|
||||
- Missing message context for modals - `index.ts:46-52`
|
||||
- Server startup failures - `server/serve.ts:66-77`
|
||||
|
||||
### 2.12 Deployment Considerations
|
||||
|
||||
1. **Port Configuration:** The web server runs on port 6111 by default
|
||||
2. **Secrets Management:** The default start script uses 1Password CLI
|
||||
3. **Build Output:** Compiled JavaScript is output to `prod/` directory
|
||||
4. **Process Management:** Consider using PM2, systemd, or Docker for production
|
||||
|
||||
## 3. Legal Documentation
|
||||
|
||||
This section is for expansions to our legal policies specific to the Application.
|
||||
|
||||
### 3.1 License
|
||||
|
||||
This Application is licensed under **Naomi's Public License** as indicated in the source file headers.
|
||||
|
||||
Copyright held by **NHCarrigan / Naomi Carrigan**.
|
||||
|
||||
Full license text available at: https://docs.nhcarrigan.com/#/license
|
||||
|
||||
### 3.2 Privacy
|
||||
|
||||
Privacy policy document: `PRIVACY.md` in the repository root.
|
||||
|
||||
**Data Collection:** The Application processes the following user data:
|
||||
- Discord User IDs (for DM delivery)
|
||||
- Message URLs (bookmarked messages)
|
||||
- User-provided notes (stored in Discord messages)
|
||||
|
||||
**Data Storage:** All data is stored within Discord's infrastructure via message content. The Application does not maintain a separate database.
|
||||
|
||||
**Data Retention:** Data persists as long as users keep their DM messages. Users can delete bookmarks at any time using the Delete command.
|
||||
|
||||
### 3.3 Terms of Service
|
||||
|
||||
Terms of service document: `TERMS.md` in the repository root.
|
||||
|
||||
### 3.4 Security
|
||||
|
||||
Security policy document: `SECURITY.md` in the repository root.
|
||||
|
||||
For security concerns, please follow the reporting procedures outlined in the security policy.
|
||||
|
||||
### 3.5 Code of Conduct
|
||||
|
||||
Code of conduct document: `CODE_OF_CONDUCT.md` in the repository root.
|
||||
|
||||
## 4. Contributing Documentation
|
||||
|
||||
This section is for documentation related to contributing to the Application's codebase.
|
||||
|
||||
### 4.1 Contributing Guidelines
|
||||
|
||||
Contributing guidelines document: `CONTRIBUTING.md` in the repository root.
|
||||
|
||||
Before contributing, please review:
|
||||
1. The Code of Conduct (`CODE_OF_CONDUCT.md`)
|
||||
2. The Contributing Guidelines (`CONTRIBUTING.md`)
|
||||
3. The License terms (`LICENSE.md`)
|
||||
|
||||
### 4.2 Development Setup
|
||||
|
||||
1. Fork the repository
|
||||
2. Clone your fork
|
||||
3. Install dependencies: `pnpm install`
|
||||
4. Create a Discord application and bot at https://discord.com/developers/applications
|
||||
5. Copy your bot token to a `prod.env` file (or use environment variables directly)
|
||||
6. Run the development server: `tsx src/index.ts`
|
||||
|
||||
### 4.3 Code Standards
|
||||
|
||||
The project uses:
|
||||
- **TypeScript** (5.9.2) with strict type checking
|
||||
- **ESLint** with `@nhcarrigan/eslint-config` (5.2.0)
|
||||
- **TypeScript Config** from `@nhcarrigan/typescript-config` (4.0.0)
|
||||
|
||||
Run linting with:
|
||||
```bash
|
||||
pnpm run lint
|
||||
```
|
||||
|
||||
**Note:** The lint script uses `--max-warnings 0`, so warnings are treated as errors.
|
||||
|
||||
### 4.4 Code Style Notes
|
||||
|
||||
- All source files include copyright headers with `@copyright`, `@license`, and `@author` tags
|
||||
- Some ESLint rules are selectively disabled with comments (e.g., `index.ts:26`)
|
||||
- The project uses ESM (module) syntax (`"type": "module"` in package.json)
|
||||
|
||||
### 4.5 Testing
|
||||
|
||||
Currently, the project has a placeholder test script:
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
|
||||
This exits with code 0 (no tests configured yet).
|
||||
|
||||
### 4.6 Pull Request Process
|
||||
|
||||
1. Create a feature branch from `main`
|
||||
2. Make your changes following the code standards
|
||||
3. Run `pnpm run lint` to ensure code quality
|
||||
4. Run `pnpm run build` to verify the build succeeds
|
||||
5. Submit a pull request with a clear description of changes
|
||||
6. Address any review feedback
|
||||
|
||||
### 4.7 Adding New Features
|
||||
|
||||
**Adding a new button:**
|
||||
1. Create a new file in `src/buttons/` exporting a `ButtonBuilder`
|
||||
2. Import and add the button to the relevant `ActionRowBuilder` in `index.ts`
|
||||
3. Add handler logic in `handleInteraction` if the button requires custom behavior
|
||||
|
||||
**Adding a new command:**
|
||||
1. Create a handler in `src/interactions/`
|
||||
2. Add the command definition to `commandData.js`
|
||||
3. Run `node commandData.js` and register the output with Discord
|
||||
4. Add the command routing logic to `handleInteraction` in `index.ts`
|
||||
|
||||
**Adding a new modal:**
|
||||
1. Create modal definition in `src/modals/`
|
||||
2. Add modal handling logic in the `isModalSubmit` section of `handleInteraction`
|
||||
3. Link the modal to a button or command that calls `showModal()`
|
||||
|
||||
### 4.8 Repository Information
|
||||
|
||||
- **Main Branch:** `main`
|
||||
- **Package Manager:** pnpm (lockfile version: 10.17.1)
|
||||
- **CI/CD:** Configuration available in `.gitea/` directory
|
||||
- **Editor Configuration:** VSCode settings in `.vscode/`
|
||||
|
||||
### 4.9 Contact
|
||||
|
||||
For questions or support:
|
||||
- **Support Server:** https://chat.nhcarrigan.com
|
||||
- **Email:** contact@nhcarrigan.com
|
||||
- **Documentation:** https://docs.nhcarrigan.com/
|
||||
- **Source Code:** https://git.nhcarrigan.com/nhcarrigan/callista
|
||||
|
||||
### 4.10 Issue Reporting
|
||||
|
||||
Please report bugs and feature requests via GitHub/Gitea issues at:
|
||||
https://git.nhcarrigan.com/nhcarrigan/callista
|
||||
|
||||
Include:
|
||||
- Clear description of the issue or feature
|
||||
- Steps to reproduce (for bugs)
|
||||
- Expected vs actual behavior
|
||||
- Environment details (Discord client version, etc.)
|
||||
Reference in New Issue
Block a user