dc-cloud 0.0.1

package/README.md

@@ -0,0 +1,1086 @@
+# DCloud 🌥️
+
+<div align="center">
+
+[![Version](https://img.shields.io/badge/version-0.0.1-blue?style=flat-square)](https://github.com/NeelFrostrain/DCloud)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=flat-square)](https://nodejs.org)
+[![License](https://img.shields.io/badge/license-private-red?style=flat-square)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/typescript-%3E%3D5.0-blue?style=flat-square)](https://www.typescriptlang.org)
+
+**Discord-Based Cloud Storage Solution**
+
+Transform your Discord server into a secure cloud storage backend with automatic compression, segmentation, and intelligent file management.
+
+[**Documentation**](#-table-of-contents) • [**Quick Start**](#-quick-start) • [**Examples**](#-example-workflow) • [**API Docs**](#-api-documentation)
+
+</div>
+
+---
+
+## 📋 Table of Contents
+
+- [Overview](#-overview)
+- [Quick Start](#-quick-start)
+- [Features](#-features)
+- [Prerequisites](#-prerequisites)
+- [Installation](#-installation)
+- [Configuration](#-configuration)
+- [Usage](#-usage)
+- [API Documentation](#-api-documentation)
+- [Project Structure](#-project-structure)
+- [Scripts & Commands](#-scripts--commands)
+- [Troubleshooting](#-troubleshooting)
+- [Development](#-development)
+- [FAQ](#-faq)
+
+---
+
+## 🎯 Overview
+
+**DCloud** is an innovative cloud storage solution that leverages Discord servers as a secure backend for file storage. It automatically compresses files into 8MB segments using 7-Zip (LZMA2), uploads them to Discord forum channels via a dedicated bot, and maintains metadata for easy retrieval and restoration.
+
+### 🔄 How It Works
+
+```
+Local File/Folder
+       ↓
+   Compression (LZMA2)
+       ↓
+   Segmentation (8MB chunks)
+       ↓
+   Upload to Discord Bot
+       ↓
+   Store in Forum Threads
+       ↓
+   Metadata Tracking (JSON)
+```
+
+### 💡 Key Concept
+
+DCloud acts as a bridge between your local file system and Discord servers, enabling:
+
+- **🗜️ Compression**: Automatic file/folder compression using LZMA2 algorithm with 512MB dictionary
+- **✂️ Segmentation**: Intelligent splitting of large files into manageable 8MB parts
+- **📤 Upload**: Fully automated uploading to Discord forum threads via bot
+- **📥 Retrieval**: Seamless download and restore with automatic cleanup
+- **📋 Metadata**: JSON-based tracking for file integrity and recovery
+
+---
+
+## ⚡ Quick Start
+
+### 1️⃣ Install Package
+
+```bash
+npm install dc-cloud
+```
+
+### 2️⃣ Clone & Install (Development)
+
+```bash
+git clone https://github.com/NeelFrostrain/DCloud.git
+cd DCloud
+npm install
+```
+
+### 3️⃣ Get Discord Credentials
+
+- Create a Discord bot at [Discord Developer Portal](https://discord.com/developers/applications)
+- Get your bot token, server ID, and forum channel ID
+- Add bot to your server with proper permissions
+
+### 4️⃣ Update Configuration
+
+Edit `src/index.ts`:
+
+```typescript
+const TOKEN = "YOUR_BOT_TOKEN";
+const CHANNEL_ID = "YOUR_FORUM_CHANNEL_ID";
+const GUILD_ID = "YOUR_SERVER_ID";
+```
+
+### 5️⃣ Run
+
+```bash
+# Development mode (with auto-reload)
+npm run dev
+
+# Or production mode
+npm run build && npm start
+```
+
+---
+
+## ✨ Features
+
+| Feature                        | Description                                                   |
+| ------------------------------ | ------------------------------------------------------------- |
+| **🗜️ Advanced Compression**    | LZMA2 algorithm with 512MB dictionary for maximum compression |
+| **✂️ Smart Segmentation**      | Automatic 8MB chunking for Discord compatibility              |
+| **🤖 Discord Bot Integration** | Full Discord.js v14 support with forum thread management      |
+| **📋 Metadata Tracking**       | JSON-based metadata for file integrity and recovery           |
+| **⚡ Concurrent Uploads**      | Parallel upload handling for optimal performance              |
+| **📥 Full Restoration**        | Complete download and extraction pipeline                     |
+| **✅ TypeScript**              | Fully typed codebase with strict type checking                |
+| **🎨 Rich Logging**            | Color-coded console output with Chalk                         |
+| **🛡️ Error Handling**          | Comprehensive error management and recovery                   |
+| **📦 Production Ready**        | Optimized for production use with proper cleanup              |
+
+---
+
+## 📦 Prerequisites
+
+### Minimum Requirements
+
+| Requirement    | Version     | Note                                       |
+| -------------- | ----------- | ------------------------------------------ |
+| **Node.js**    | ≥ 18.0.0    | Runtime environment                        |
+| **npm**        | ≥ 9.0.0     | Package manager                            |
+| **TypeScript** | ≥ 5.0       | Peer dependency (required for development) |
+| **Disk Space** | 500MB+      | For temporary files during compression     |
+| **RAM**        | 2GB minimum | 4GB+ recommended                           |
+
+### External Dependencies
+
+- **Discord Server**: Admin access to create forum channels
+- **Discord Bot**: Valid bot token with proper permissions
+- **7-Zip**: Bundled via `7zip-bin` package (auto-installed)
+
+### Discord Bot Permissions
+
+Your bot requires these permissions:
+
+```
+PERMISSIONS NEEDED:
+✓ Send Messages
+✓ Create Public Threads
+✓ Send Messages in Threads
+✓ Embed Links
+✓ Attach Files
+✓ Read Message History
+```
+
+### Operating System Support
+
+| OS          | Status             | Notes                                      |
+| ----------- | ------------------ | ------------------------------------------ |
+| **Windows** | ✅ Fully Supported | Recommended                                |
+| **macOS**   | ✅ Fully Supported | Requires p7zip-full                        |
+| **Linux**   | ✅ Fully Supported | Install: `sudo apt-get install p7zip-full` |
+
+---
+
+## 🚀 Installation
+
+### Step 1: Clone Repository
+
+```bash
+git clone https://github.com/NeelFrostrain/DCloud.git
+cd DCloud
+```
+
+### Step 2: Install Dependencies
+
+```bash
+npm install
+```
+
+This installs:
+
+- **discord.js** v14.25.1 - Discord bot framework
+- **7zip-bin** v5.2.0 - 7-Zip binary
+- **chalk** v5.6.2 - Terminal styling
+- **Dev Tools** - ESLint, TypeScript, Nodemon
+
+### Step 3: Verify Installation
+
+```bash
+# Check TypeScript compilation
+npm run type-check
+
+# Lint code
+npm run lint
+
+# Try building
+npm run build
+```
+
+### Step 4: Configuration (See [Configuration](#-configuration) Section)
+
+---
+
+## ⚙️ Configuration
+
+### Setting Up Discord Bot (Step-by-Step)
+
+#### 1. Create Discord Application
+
+1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
+2. Click **"New Application"**
+3. Enter name: `DCloud Bot` (or your preference)
+4. Accept Terms and Create
+
+#### 2. Create Bot User
+
+1. Navigate to **"Bot"** section
+2. Click **"Add Bot"**
+3. Click **"Reset Token"** to copy bot token
+4. **⚠️ Keep this token secret!** Never commit to git
+
+#### 3. Configure Bot Permissions
+
+1. Go to **"OAuth2"** → **"URL Generator"**
+2. Select **Scopes**: `bot`
+3. Select **Permissions**:
+   - ✓ Send Messages
+   - ✓ Create Public Threads
+   - ✓ Send Messages in Threads
+   - ✓ Embed Links
+   - ✓ Attach Files
+   - ✓ Read Message History
+4. Copy the generated URL
+
+#### 4. Add Bot to Server
+
+1. Open the OAuth2 URL in your browser
+2. Select your Discord server
+3. Click **"Authorize"**
+4. Complete the CAPTCHA
+
+#### 5. Get Required IDs
+
+**Method 1: Developer Mode** (Easiest)
+
+1. Open Discord User Settings → Advanced
+2. Enable **"Developer Mode"**
+3. Right-click server name → **"Copy Server ID"** (Server ID)
+4. Right-click forum channel → **"Copy Channel ID"** (Forum Channel ID)
+
+**Method 2: Discord API**
+Use [Discord Server Info Bot](https://top.gg/bot/905182607851741205) or similar
+
+### Environment Configuration
+
+#### Option A: Direct in Code (Development)
+
+Edit `src/index.ts`:
+
+```typescript
+import { DCloud } from "./classes/dCloud";
+
+const TOKEN = "MTQxODYyMjg0MDE4NTQyMTgzNg..."; // Bot token
+const CHANNEL_ID = "1465235994243502162"; // Forum channel ID
+const GUILD_ID = "1316439358609297418"; // Server ID
+
+const dCloud = DCloud({
+  FORUM_CHANNEL_ID: CHANNEL_ID,
+  TOKEN: TOKEN,
+  SERVER_ID: GUILD_ID,
+});
+
+await dCloud.init();
+```
+
+#### Option B: Environment Variables (Production)
+
+Create `.env` file:
+
+```bash
+DISCORD_TOKEN=YOUR_BOT_TOKEN
+DISCORD_SERVER_ID=YOUR_SERVER_ID
+DISCORD_FORUM_CHANNEL_ID=YOUR_FORUM_CHANNEL_ID
+```
+
+Update `src/index.ts`:
+
+```typescript
+import dotenv from "dotenv";
+dotenv.config();
+
+const dCloud = DCloud({
+  TOKEN: process.env.DISCORD_TOKEN!,
+  SERVER_ID: process.env.DISCORD_SERVER_ID!,
+  FORUM_CHANNEL_ID: process.env.DISCORD_FORUM_CHANNEL_ID!,
+});
+```
+
+### Configuration Verification
+
+Test your configuration:
+
+```bash
+npm run dev
+```
+
+Expected output:
+
+```
+[Bot] [Status]: Logged in as DCloud#1234
+[Bot] [Guild]: Connected to Server: MyServer
+[Bot] [Channel]: Target Forum: #uploads
+```
+
+If you see errors, review the [Troubleshooting](#-troubleshooting) section.
+
+---
+
+## 📖 Usage
+
+### Using from NPM Package
+
+```typescript
+import { DCloud } from "@discord/dcloud";
+
+const dCloud = DCloud({
+  FORUM_CHANNEL_ID: "1465235994243502162",
+  TOKEN: "YOUR_BOT_TOKEN",
+  SERVER_ID: "1316439358609297418",
+});
+
+// Initialize the bot
+await dCloud.init();
+
+// Upload a file
+const result = await dCloud.upload("C:\\path\\to\\file.zip");
+console.log("Upload complete:", result);
+```
+
+### Local Development Setup
+
+```typescript
+import { DCloud } from "./src/classes/dCloud";
+
+const dCloud = DCloud({
+  FORUM_CHANNEL_ID: "1465235994243502162",
+  TOKEN: "YOUR_BOT_TOKEN",
+  SERVER_ID: "1316439358609297418",
+});
+
+// Initialize the bot
+await dCloud.init();
+
+// Upload a file
+const result = await dCloud.upload("C:\\path\\to\\file.zip");
+console.log("Upload complete:", result);
+```
+
+```typescript
+// Download using metadata URL
+await dCloud.downloader(
+  "https://cdn.discordapp.com/attachments/.../metadata.json",
+  "C:\\output\\path",
+);
+console.log("Download and extraction complete!");
+```
+
+### Running the Application
+
+#### 1. Development Mode (Auto-reload)
+
+```bash
+npm run dev
+```
+
+Watches for file changes and automatically restarts.
+
+#### 2. Production Mode (Compiled)
+
+```bash
+npm run build
+npm start
+```
+
+Compiles TypeScript to JavaScript and runs it.
+
+#### 3. Type Check Only
+
+```bash
+npm run type-check
+```
+
+Validates TypeScript without emitting files.
+
+---
+
+## 🔌 API Documentation
+
+### DCloud Class
+
+Main class for file upload/download operations.
+
+#### Constructor
+
+```typescript
+DCloud(config: ICloudBot): DCloudClass
+```
+
+**Parameters**:
+
+- `config.TOKEN`: Discord bot token (string)
+- `config.SERVER_ID`: Discord guild/server ID (string)
+- `config.FORUM_CHANNEL_ID`: Target forum channel ID (string)
+
+#### Methods
+
+##### `init(): Promise<void>`
+
+Initializes the bot and connects to Discord.
+
+```typescript
+await dCloud.init();
+```
+
+##### `upload(filePath: string): Promise<ICompressorResult>`
+
+Uploads a file or directory to Discord.
+
+**Parameters**:
+
+- `filePath`: Absolute path to file or directory
+
+**Returns**: Upload result with metadata URL
+
+**Example**:
+
+```typescript
+const result = await dCloud.upload("C:\\files\\mydata.zip");
+```
+
+**Process Flow**:
+
+1. Validates input path
+2. Initializes Discord thread with file info
+3. Compresses file with LZMA2 (8MB segments)
+4. Uploads segments to Discord
+5. Generates and uploads metadata.json
+6. Cleans up temporary files
+7. Returns metadata URL
+
+##### `downloader(metadataUrl: string, outputPath: string): Promise<void>`
+
+Downloads and restores files from Discord.
+
+**Parameters**:
+
+- `metadataUrl`: URL to metadata.json file
+- `outputPath`: Directory to save restored files
+
+**Example**:
+
+```typescript
+await dCloud.downloader(
+  "https://cdn.discordapp.com/attachments/.../metadata.json",
+  "C:\\restored\\",
+);
+```
+
+**Process Flow**:
+
+1. Fetches metadata.json
+2. Creates directory structure
+3. Downloads all archive segments
+4. Extracts using 7-Zip
+5. Cleans up temporary files
+6. Completes restoration
+
+### CloudBot Class
+
+Handles Discord bot operations and thread management.
+
+#### Methods
+
+##### `Init(): Promise<void>`
+
+Initializes the Discord bot connection.
+
+##### `IsBotOnline(): boolean`
+
+Checks if bot is connected and ready.
+
+### Interfaces
+
+#### ICloudBot
+
+```typescript
+interface ICloudBot {
+  TOKEN: string; // Discord bot token
+  SERVER_ID: string; // Guild/server ID
+  FORUM_CHANNEL_ID: string; // Forum channel ID
+}
+```
+
+#### ICompressor
+
+```typescript
+interface ICompressor {
+  originalName: string; // Original file/folder name
+  totalSize: string; // Size in MB
+  createdAt: string; // Creation timestamp
+  parts: {
+    name: string; // Segment filename
+    url: string; // Discord CDN URL
+  }[];
+}
+```
+
+#### ICompressorResult
+
+```typescript
+interface ICompressorResult {
+  originalName: string; // Original file/folder name
+  totalSize: string; // Total size in MB
+  createdAt: string; // Creation timestamp
+  metadata: string; // Metadata.json URL
+}
+```
+
+---
+
+## 📁 Project Structure
+
+```
+DCloud/
+├── src/
+│   ├── classes/
+│   │   ├── cloudBot.ts       # Discord bot management
+│   │   └── dCloud.ts         # Main upload/download logic
+│   ├── interface/
+│   │   └── index.ts          # TypeScript interfaces
+│   ├── utils/
+│   │   ├── 7zip.ts           # 7-Zip compression utilities
+│   │   └── lib.ts            # Helper functions
+│   └── index.ts              # Entry point & examples
+├── dist/                      # Compiled JavaScript (auto-generated)
+├── node_modules/            # Dependencies (auto-generated)
+├── eslint.config.ts         # ESLint rules
+├── tsconfig.json            # TypeScript configuration
+├── package.json             # Dependencies & npm scripts
+├── index.d.ts               # Public API type definitions
+└── README.md                # This documentation
+```
+
+### Directory Breakdown
+
+| Directory          | Purpose                            |
+| ------------------ | ---------------------------------- |
+| **src/**           | TypeScript source code             |
+| **src/classes/**   | Core DCloud and CloudBot classes   |
+| **src/interface/** | Type definitions and interfaces    |
+| **src/utils/**     | Utility functions (7-Zip, helpers) |
+| **dist/**          | Compiled JavaScript output         |
+
+---
+
+## 📋 Scripts & Commands
+
+### Development Commands
+
+| Command              | Purpose                  | Usage                |
+| -------------------- | ------------------------ | -------------------- |
+| `npm run dev`        | Start with auto-reload   | `npm run dev`        |
+| `npm run build`      | Compile TypeScript       | `npm run build`      |
+| `npm run type-check` | Check types without emit | `npm run type-check` |
+| `npm run lint`       | Run ESLint               | `npm run lint`       |
+
+### Production Commands
+
+| Command         | Purpose                |
+| --------------- | ---------------------- | ----------------------------------- |
+| `npm start`     | Build and run          | Compiles and executes compiled code |
+| `npm run build` | TypeScript compilation | Creates `dist/` folder              |
+
+### Quick Reference
+
+```bash
+# Development workflow
+npm install              # Install dependencies
+npm run dev             # Start development server
+
+# Before committing
+npm run lint            # Check code quality
+npm run type-check      # Verify types
+
+# Production deployment
+npm run build           # Compile code
+npm start              # Run compiled version
+```
+
+---
+
+## 🔧 Development
+
+### Code Quality
+
+#### ESLint Configuration
+
+The project uses ESLint with TypeScript support:
+
+```bash
+npm run lint
+```
+
+Config file: `eslint.config.ts`
+
+#### TypeScript Validation
+
+Verify types and compilation:
+
+```bash
+npm run type-check    # Check types without emitting
+npm run build         # Full compilation to JavaScript
+```
+
+### Development Workflow
+
+1. **Write Code**: Create TypeScript files in `src/`
+2. **Test Locally**: Use `npm run dev` for auto-reload testing
+3. **Validate**: Run `npm run type-check` to check types
+4. **Lint**: Run `npm run lint` to check code quality
+5. **Build**: Run `npm run build` to verify compilation
+6. **Test Complete Flow**: Manually test upload/download
+7. **Commit**: Push changes once verified
+
+### Adding Features
+
+#### Step 1: Define Types
+
+Add interfaces to `src/interface/index.ts`:
+
+```typescript
+export interface IMyFeature {
+  name: string;
+  value: number;
+}
+```
+
+#### Step 2: Create Utilities
+
+Add functions to `src/utils/`:
+
+```typescript
+export function myUtility(input: string): string {
+  return input.toUpperCase();
+}
+```
+
+#### Step 3: Add Methods
+
+Update classes in `src/classes/`:
+
+```typescript
+public async myMethod(param: string): Promise<void> {
+  // Implementation
+}
+```
+
+#### Step 4: Update Public API
+
+Export in `index.d.ts`:
+
+```typescript
+export { myUtility } from "./src/utils/lib";
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Bot Connection Issues
+
+**Problem**: "Could not find server with ID"
+
+**Solution**:
+
+- Verify your `SERVER_ID` is correct
+- Ensure the bot is invited to the server
+- Check bot permissions in server settings
+
+**Problem**: "Channel ID provided is not a Forum Channel"
+
+**Solution**:
+
+- Verify you're using a forum channel, not a regular channel
+- Right-click the channel in Discord to confirm it's a forum
+- Get the correct channel ID
+
+### Upload Failures
+
+**Problem**: "File not found at path"
+
+**Solution**:
+
+- Use absolute paths (e.g., `C:\\Users\\...`)
+- Verify the file exists before uploading
+- Check file permissions (must be readable)
+
+**Problem**: "Bot is not online"
+
+**Solution**:
+
+- Call `await dCloud.init()` before uploading
+- Verify bot token is correct and still valid
+- Check bot permissions in Discord server
+
+### Compression Issues
+
+**Problem**: "7-Zip binary not found"
+
+**Solutions**:
+
+- Reinstall dependencies: `npm install`
+- Ensure `7zip-bin` package is properly installed
+- On Linux, install p7zip: `sudo apt-get install p7zip-full`
+- On macOS: `brew install p7zip`
+
+**Problem**: "Input path does not exist"
+
+**Solutions**:
+
+- Verify file path is absolute and correct
+- Check file permissions (must be readable)
+- Use forward slashes or escaped backslashes in paths
+
+### Memory & Performance Issues
+
+**Problem**: "FATAL ERROR: CALL_AND_RETRY_LAST"
+
+**Solutions**:
+
+- Increase Node.js memory limit:
+  ```bash
+  node --max-old-space-size=4096 dist/index.js
+  ```
+- Reduce file size being compressed
+- Monitor system resources and close unnecessary applications
+
+**Problem**: Slow uploads to Discord
+
+**Solutions**:
+
+- Check internet connection speed
+- Add delays between uploads: `setTimeout(...)`
+- Use exponential backoff for retries
+- Consider uploading during off-peak hours
+
+### Discord Rate Limiting
+
+**Problem**: "429 Too Many Requests"
+
+**Causes**: Discord API rate limiting (20 requests/sec per channel)
+
+**Solutions**:
+
+- Add delays between file uploads
+- Implement exponential backoff retry logic:
+  ```typescript
+  let retries = 0;
+  while (retries < 3) {
+    try {
+      await dCloud.upload(filePath);
+      break;
+    } catch (e) {
+      await new Promise((r) => setTimeout(r, Math.pow(2, retries) * 1000));
+      retries++;
+    }
+  }
+  ```
+- Split uploads across multiple bot instances
+
+---
+
+## 📊 Performance & Benchmarks
+
+### Compression Metrics
+
+| Metric                | Value                         |
+| --------------------- | ----------------------------- |
+| **Algorithm**         | LZMA2 with 512MB dictionary   |
+| **Compression Ratio** | 40-70% (file type dependent)  |
+| **Speed**             | ~10-50 MB/min (CPU dependent) |
+| **Dictionary Size**   | 512MB (maximum)               |
+
+### Upload Performance
+
+| Metric                 | Value                                 |
+| ---------------------- | ------------------------------------- |
+| **Discord Rate Limit** | 20 requests/sec per channel           |
+| **Typical Speed**      | 50-200 MB/hour                        |
+| **Segment Size**       | 8MB (safe margin below Discord limit) |
+| **Bottleneck**         | Discord API rate limiting             |
+
+### Optimal File Types
+
+| Category      | Best For                                | Avoid                              |
+| ------------- | --------------------------------------- | ---------------------------------- |
+| **Text**      | Source code, logs, documents            | Already compressed files           |
+| **Media**     | High-quality images, uncompressed video | MP4, JPG, PNG (already compressed) |
+| **Archives**  | ZIP/RAR before uploading                | Don't double-compress              |
+| **Databases** | Raw database files, backups             | Encrypted archives                 |
+
+- Poor for: Already compressed files (zip, mp4, jpg)
+
+---
+
+## 📝 Example Workflow
+
+### Complete Upload Example
+
+```typescript
+import { DCloud } from "./src/classes/dCloud.js";
+import fs from "fs";
+
+async function uploadExample() {
+  const dCloud = DCloud({
+    TOKEN: process.env.DISCORD_TOKEN || "YOUR_TOKEN",
+    SERVER_ID: process.env.DISCORD_SERVER_ID || "YOUR_SERVER_ID",
+    FORUM_CHANNEL_ID: process.env.DISCORD_FORUM_CHANNEL_ID || "YOUR_FORUM_ID",
+  });
+
+  try {
+    // Step 1: Initialize bot connection
+    console.log("🤖 Initializing bot...");
+    await dCloud.init();
+
+    // Step 2: Upload file
+    console.log("📤 Starting upload...");
+    const result = await dCloud.upload("C:\\files\\backup.zip");
+
+    // Step 3: Display results
+    console.log("✅ Upload successful!");
+    console.log(`📦 Name: ${result.originalName}`);
+    console.log(`📊 Size: ${result.totalSize}`);
+    console.log(`🔗 Metadata: ${result.metadata}`);
+
+    // Step 4: Save metadata URL for later
+    fs.writeFileSync("upload_metadata.json", JSON.stringify(result, null, 2));
+    console.log("💾 Metadata saved to upload_metadata.json");
+  } catch (error) {
+    console.error("❌ Upload failed:", error);
+  }
+}
+
+uploadExample();
+```
+
+### Using NPM Package - Complete Download Example
+
+```typescript
+import { DCloud } from "dc-cloud";
+
+async function downloadExample() {
+  const dCloud = DCloud({
+    TOKEN: process.env.DISCORD_TOKEN || "YOUR_TOKEN",
+    SERVER_ID: process.env.DISCORD_SERVER_ID || "YOUR_SERVER_ID",
+    FORUM_CHANNEL_ID: process.env.DISCORD_FORUM_CHANNEL_ID || "YOUR_FORUM_ID",
+  });
+
+  try {
+    // Step 1: Initialize bot
+    console.log("🤖 Initializing bot...");
+    await dCloud.init();
+
+    // Step 2: Download and restore
+    console.log("📥 Starting download...");
+    await dCloud.downloader(
+      "https://cdn.discordapp.com/attachments/.../metadata.json",
+      "C:\\restored\\",
+    );
+
+    console.log("✅ Download and extraction complete!");
+    console.log("📁 Files restored to C:\\restored\\");
+  } catch (error) {
+    console.error("❌ Download failed:", error);
+  }
+}
+
+downloadExample();
+```
+
+---
+
+## 📚 Additional Resources
+
+### Discord Developer Portal
+
+- [Applications](https://discord.com/developers/applications)
+- [Bot Documentation](https://discord.com/developers/docs/intro)
+- [Gateway Intents](https://discord.com/developers/docs/topics/gateway#gateway-intents)
+
+### Related Libraries
+
+- [Discord.js Documentation](https://discord.js.org)
+- [7-Zip Documentation](https://www.7-zip.org)
+- [Node.js Child Process](https://nodejs.org/api/child_process.html)
+
+---
+
+## 📄 License
+
+This project is marked as **private**. Please contact the author for licensing information.
+
+---
+
+## 👤 Author
+
+**Neel Frostrain** (@NeelFrostrain)
+
+- **GitHub**: [NeelFrostrain](https://github.com/NeelFrostrain)
+- **Repository**: [DCloud](https://github.com/NeelFrostrain/DCloud)
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Here's how to contribute:
+
+1. **Fork** the repository
+2. **Create** a feature branch: `git checkout -b feature/amazing-feature`
+3. **Commit** changes: `git commit -m 'Add amazing feature'`
+4. **Push** to branch: `git push origin feature/amazing-feature`
+5. **Open** a Pull Request
+
+### Development Guidelines
+
+- Write in TypeScript
+- Follow existing code style (use `npm run lint`)
+- Test all changes locally
+- Update documentation as needed
+- Include meaningful commit messages
+
+---
+
+## ❓ FAQ
+
+### General Questions
+
+**Q: Is my data safe on Discord?**
+
+A: Data is encrypted via Discord's HTTPS connections. However, Discord can theoretically access encrypted messages. For sensitive data, consider additional encryption.
+
+**Q: What's the maximum file size I can upload?**
+
+A: Theoretical limit depends on Discord storage. Each bot account can upload ~5GB before approaching limits. Use multiple bot accounts for larger backups.
+
+**Q: Can I use multiple bot instances?**
+
+A: Yes! You can scale horizontally by deploying multiple bot instances across different Discord servers.
+
+**Q: How long do uploaded files stay on Discord?**
+
+A: As long as the Discord message exists. Discord stores messages indefinitely unless deleted. Your responsibility is to maintain backup URLs.
+
+### Technical Questions
+
+**Q: Can I use different compression algorithms?**
+
+A: Currently, LZMA2 is hardcoded. You can modify `src/utils/7zip.ts` to support other algorithms (PPMd, BZip2, etc.).
+
+**Q: How do I reduce upload time?**
+
+A: Options:
+
+1. Compress pre-upload (though files are already compressed)
+2. Use multiple bot instances
+3. Increase Discord API request limits if possible
+4. Optimize network connection
+
+**Q: Can I restore files partially?**
+
+A: No, the current implementation requires all segments. You must restore complete archives.
+
+**Q: Does DCloud support streaming uploads?**
+
+A: No, currently uses buffer-based uploads. Streaming support could be added as a future feature.
+
+### Troubleshooting Questions
+
+**Q: Bot is not responding?**
+
+A: Check:
+
+1. Bot token is correct
+2. Bot is invited to server
+3. Forum channel exists and bot has access
+4. Internet connection is stable
+
+**Q: Uploads are very slow?**
+
+A: Causes and solutions:
+
+- **Network**: Check internet speed
+- **CPU**: Compression is CPU-intensive
+- **Discord Rate Limit**: Add delays between uploads
+- **Large Files**: Break into smaller chunks before uploading
+
+**Q: Can I cancel an upload in progress?**
+
+A: Not gracefully in the current version. You'd need to kill the process. Consider adding cancellation tokens in future versions.
+
+---
+
+## 🐛 Known Limitations
+
+- ⚠️ No partial restoration (must restore entire archives)
+- ⚠️ Single-threaded uploads (can be optimized)
+- ⚠️ No built-in encryption (Discord HTTPS provides some protection)
+- ⚠️ Metadata URLs may expire if Discord messages are deleted
+- ⚠️ No support for incremental backups (only full backups)
+
+---
+
+## 🚀 Future Enhancements
+
+Planned features for future versions:
+
+- [ ] Incremental backup support
+- [ ] Built-in encryption layer
+- [ ] Progress tracking UI
+- [ ] Scheduled automatic backups
+- [ ] Multi-threaded uploads
+- [ ] Compression algorithm selection
+- [ ] WebUI dashboard
+- [ ] REST API interface
+
+---
+
+## 📞 Support
+
+### Getting Help
+
+1. Check [Troubleshooting](#-troubleshooting) section
+2. Review existing [GitHub Issues](https://github.com/NeelFrostrain/DCloud/issues)
+3. Create a new issue with:
+   - Error message and logs
+   - Steps to reproduce
+   - System information (OS, Node.js version)
+   - DCloud version
+
+### Reporting Bugs
+
+When reporting bugs, include:
+
+- Full error stack trace
+- Console output
+- File/folder being uploaded
+- System specifications
+
+---
+
+**Made with ❤️ for the Discord community**
+
+**Last Updated**: January 26, 2026
+**Version**: 0.0.1
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.5. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.