DCloud 🌥️

Discord-Based Cloud Storage Solution

Transform your Discord server into a secure cloud storage backend with automatic compression, segmentation, and intelligent file management.

Documentation • Quick Start • Examples • API Docs • Changelog

📋 Table of Contents

• Overview
• Quick Start
• Features
• Prerequisites
• Installation
• Configuration
• Usage
• API Documentation
• Project Structure
• Scripts & Commands
• Troubleshooting
• Development
• 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

npm install discord-dcloud

2️⃣ Clone & Install (Development)

git clone https://github.com/NeelFrostrain/DCloud.git
cd DCloud
npm install

3️⃣ Get Discord Credentials

• Create a Discord bot at Discord Developer Portal
• 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:

const TOKEN = "YOUR_BOT_TOKEN";
const CHANNEL_ID = "YOUR_FORUM_CHANNEL_ID";
const GUILD_ID = "YOUR_SERVER_ID";

5️⃣ Run

# 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

git clone https://github.com/NeelFrostrain/DCloud.git
cd DCloud

Step 2: Install Dependencies

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

# Check TypeScript compilation
npm run type-check

# Lint code
npm run lint

# Try building
npm run build

Step 4: Configuration (See Configuration Section)

⚙️ Configuration

Setting Up Discord Bot (Step-by-Step)

1. Create Discord Application

1. Go to Discord Developer Portal
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 or similar

Environment Configuration

Option A: Direct in Code (Development)

Edit src/index.ts:

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:

DISCORD_TOKEN=YOUR_BOT_TOKEN
DISCORD_SERVER_ID=YOUR_SERVER_ID
DISCORD_FORUM_CHANNEL_ID=YOUR_FORUM_CHANNEL_ID

Update src/index.ts:

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:

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 section.

📖 Usage

Using from NPM Package

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

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);

// 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)

npm run dev

Watches for file changes and automatically restarts.

2. Production Mode (Compiled)

npm run build
npm start

Compiles TypeScript to JavaScript and runs it.

3. Type Check Only

npm run type-check

Validates TypeScript without emitting files.

🔌 API Documentation

DCloud Class

Main class for file upload/download operations.

Constructor

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.

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:

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:

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

interface ICloudBot {
  TOKEN: string; // Discord bot token
  SERVER_ID: string; // Guild/server ID
  FORUM_CHANNEL_ID: string; // Forum channel ID
}

ICompressor

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

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 | Note | | --------------- | ---------------------- | ----------------------------------- | | npm start | Build and run | Compiles and executes compiled code | | npm run build | TypeScript compilation | Creates dist/ folder |

Quick Reference

# 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:

npm run lint

Config file: eslint.config.ts

TypeScript Validation

Verify types and compilation:

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:

export interface IMyFeature {
  name: string;
  value: number;
}

Step 2: Create Utilities

Add functions to src/utils/:

export function myUtility(input: string): string {
  return input.toUpperCase();
}

Step 3: Add Methods

Update classes in src/classes/:

public async myMethod(param: string): Promise<void> {
  // Implementation
}

Step 4: Update Public API

Export in index.d.ts:

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:

  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:

  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

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

import { DCloud } from "discord-dcloud";

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
• Bot Documentation
• Gateway Intents

Related Libraries

• Discord.js Documentation
• 7-Zip Documentation
• Node.js Child Process

📄 License

This project is marked as private. Please contact the author for licensing information.

👤 Author

Neel Frostrain (@NeelFrostrain)

• GitHub: NeelFrostrain
• Repository: 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 section
2. Review existing GitHub 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 27, 2026 Version: 0.1.0

To install dependencies:

npm install

To run:

npm start

📝 Changelog

v0.1.0 (January 27, 2026)

New Features

• Metadata File Attachments: Metadata now sent as metadata.json file attachment instead of message code blocks
• Stream-Based Downloads: Improved memory efficiency for large file downloads
• Dual Metadata Support: Downloader handles both new file-based and legacy metadata formats

Improvements

• Refactored upload method with improved error handling and logging
• Added ensureFileReady() helper for reliable file status checking
• Added cleanupFolder() for non-blocking background cleanup
• Improved 7zip compression parameters with precise byte values
• Better error messages and consistent formatting throughout codebase
• Removed axios dependency (migrated to native fetch API)

Changes

• Version Bump: 0.0.8 → 0.1.0
• Breaking Change: initializeNewChannel() now requires inputPath parameter
• Dependencies Removed: axios and all transitive dependencies (axios, follow-redirects, form-data, etc.)

Bug Fixes

• Fixed metadata handling in downloader to match Restore() function requirements
• Improved file stability detection before upload
• Better error propagation in async flows

📝 Changelog & Release Notes

v0.1.0 (January 27, 2026)

🚀 New Features

• Metadata File Attachments: Metadata now sent as metadata.json file attachment instead of message code blocks

  • More reliable delivery
  • Avoids Discord's 2000-character message limit
  • Cleaner Discord interface

• Stream-Based Downloads: Improved memory efficiency for large file downloads

  • Lower RAM footprint
  • Better performance on constrained systems

• Dual Metadata Support: Downloader handles both new file-based and legacy metadata formats

  • Seamless transitions between versions
  • Backwards compatible

✨ Improvements

• Refactored upload method with improved error handling and logging

• Added ensureFileReady() helper for reliable file status checking

  • Polls file every 250ms until stable
  • Prevents uploading incomplete files

• Added cleanupFolder() for non-blocking background cleanup

  • 2-second delay to release file handles
  • Doesn't block function returns

• Improved 7zip compression parameters with precise byte values

  • Changed from -v8m to -v8388608 (8MB in bytes)
  • More reliable segment sizing

• Better error messages and consistent formatting throughout codebase

• Removed axios dependency (migrated to native fetch API)

  • Package size reduced by ~50KB
  • Fewer security vulnerabilities

⚠️ Breaking Changes

• initializeNewChannel() signature changed

  // Before
  initializeNewChannel(fileName: string)
  
  // After
  initializeNewChannel(fileName: string, inputPath: string)

  Impact: Only if you called this method directly

  Workaround: Use upload() method instead (handles it internally)

📦 Dependencies Removed

• axios - HTTP client (replaced with native fetch)
• follow-redirects
• form-data
• asynckit
• combined-stream
• mime-types
• mime-db

🐛 Bug Fixes

• Fixed metadata handling in downloader to match Restore() function requirements
• Improved file stability detection before upload
• Better error propagation in async flows

📊 Statistics

| Metric | Value | | ---------------------- | ----------- | | Lines Added | 235 | | Lines Removed | 151 | | Net Change | +84 lines | | Files Modified | 7 | | Compilation Status | ✓ No errors | | Package Size Reduction | ~50KB |

🔧 Technical Details

New Methods

ensureFileReady(filePath: string): Promise<void>

Ensures 7zip has finished writing the file before upload.

private async ensureFileReady(filePath: string): Promise<void> {
  // Polls every 250ms
  // Waits for file size stability (2 consecutive equal sizes)
  // Minimum file size: > 0 bytes
}

Purpose: Prevent uploading incomplete files

Polling Interval: 250ms

Stability Threshold: 2 consecutive equal file sizes

cleanupFolder(folderPath: string): Promise<void>

Removes temporary files without blocking return.

private async cleanupFolder(folderPath: string) {
  // 2-second delay to release file handles
  // Recursive directory removal
  // Silent failure (doesn't throw)
}

Purpose: Clean up TempOutput directory

Delay: 2 seconds (allows file handles to be released)

Error Handling: Silent failure (cleanup not critical)

Metadata File Flow

Upload Process:

1. Compress files to 8MB segments
2. Upload segments to Discord
3. Create metadata.json with upload metadata
4. Send metadata.json as file attachment
5. Clean up temporary files

Format:

{
  "originalName": "filename.ext",
  "totalSize": "150.50 MB",
  "createdAt": "1/27/2026, 10:30:45 AM",
  "parts": [
    {
      "name": "filename.7z.001",
      "url": "https://discord.com/channels/..."
    }
  ]
}

Download/Restore Flow

1. Parse Metadata: Supports both attachment and legacy formats
2. Create Directory: With proper folder naming
3. Save Metadata: Write to disk (required by Restore)
4. Download Parts: Stream-based using pipeline()
5. Reassemble: Call Restore() with metadata
6. Cleanup: Remove parts and metadata.json

🔄 Migration Guide (v0.0.8 → v0.1.0)

For Regular Users

# Update to v0.1.0
npm install

# That's it! Your existing code still works

For Developers

If you extended DCloudClass, update any direct calls to initializeNewChannel():

// ❌ Old way (no longer works)
const thread = await dcloud.initializeNewChannel(filename);

// ✅ New way
const thread = await dcloud.initializeNewChannel(filename, filepath);

// ✅ Alternative (recommended)
const result = await dcloud.upload(filepath);

Metadata Format

• Old Format: metadata.json code block in Discord message
• New Format: metadata.json file attachment
• Downloads: Both formats supported automatically ✓

✅ Testing Recommendations

Unit Tests

• [ ] ensureFileReady() with different file sizes
• [ ] cleanupFolder() with missing files
• [ ] Metadata serialization/deserialization

Integration Tests

• [ ] Upload small file (< 8MB)
• [ ] Upload medium file (50-100MB)
• [ ] Upload folder with multiple files
• [ ] Download with new metadata format
• [ ] Download with legacy metadata format
• [ ] Partial failure recovery

Edge Cases

• [ ] File locked by another process
• [ ] Disk space exhausted
• [ ] Discord API rate limiting
• [ ] Network interruption during upload
• [ ] Corrupted metadata.json

🛡️ Security Notes

What's Changed

• ✅ No breaking security changes
• ✅ Removed axios (fewer dependencies = smaller attack surface)
• ✅ Native fetch API used (built-in security)

Best Practices

• Keep bot token in .env file
• Don't commit sensitive credentials
• Use Discord OAuth2 for production deployments
• Regularly update dependencies

🔍 Troubleshooting

Common Issues

Problem: "Metadata message was null"

• Cause: Discord API error when sending message
• Solution: Check bot permissions, Discord API status

Problem: "File not found at path"

• Cause: Input path doesn't exist or is inaccessible
• Solution: Verify path exists and is readable

Problem: "7zip binary not found"

• Cause: 7zip-bin not properly installed
• Solution: Reinstall: npm install --save 7zip-bin

Problem: "No parts were generated"

• Cause: Compression failed or produced no output
• Solution: Check file permissions, available disk space

Debug Mode

Enable detailed logging:

const dcloud = DCloud({
  TOKEN: "your-token",
  SERVER_ID: "your-server",
  FORUM_CHANNEL_ID: "your-channel",
});

// All errors logged with chalk colors
// Check console for detailed output

📚 API Documentation

Core Classes

DCloudClass

Main class for file operations.

constructor(config: ICloudBot)

Methods:

• init(): Promise<void> - Initialize bot connection
• upload(inputPath: string): Promise<ICompressorResult> - Upload file/folder
• downloader(messageLink: string, output: string): Promise<void> - Download file

CloudBotClass

Handles Discord bot operations.

extends Client

Methods:

• Init(): Promise<void> - Login to Discord
• IsBotOnline(): boolean - Check connection status
• initializeNewThread(name: string, msg: EmbedBuilder): Promise<ThreadChannel> - Create forum thread
• sendToForumChannel(filePath: string, fileName: string): Promise<string | null> - Upload file to thread

Interfaces

interface ICloudBot {
  TOKEN: string;
  SERVER_ID: string;
  FORUM_CHANNEL_ID: string;
}

interface ICompressor {
  originalName: string;
  totalSize: string;
  createdAt: string;
  parts: Array<{ name: string; url: string }>;
}

interface ICompressorResult {
  originalName: string;
  totalSize: string;
  createdAt: string;
  metadata: string;
}

🎓 Learning Resources

For New Users

1. Read the Quick Start section
2. Review Features
3. Check Configuration

For Developers

1. Understand Project Structure
2. Review API Documentation
3. Explore source code in src/

For Contributors

1. Read the Development section
2. Review Technical Details
3. Run tests before submitting PRs

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

Development Commands

# Install dependencies
npm install

# Development mode (with auto-reload)
npm run dev

# Build
npm run build

# Lint code
npm run lint

# Type check
npm run type-check

# Run compiled version
npm start

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Neel Frostrain

• GitHub: @NeelFrostrain
• Repository: DCloud

🙏 Acknowledgments

• Discord.js team for the amazing Discord API library
• 7-Zip project for the compression algorithm
• Node.js community

📞 Support

For issues, questions, or suggestions:

1. Check Troubleshooting
2. Review FAQ
3. Open an issue on GitHub
4. Provide:
   • Error messages and logs
   • Steps to reproduce
   • System information

Last Updated: January 27, 2026
Current Version: 0.1.0
Status: ✅ Production Ready

This project was created with ❤️ for the Discord community