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

Go to Discord Developer Portal
Click "New Application"
Enter name: DCloud Bot (or your preference)
Accept Terms and Create

2. Create Bot User

Navigate to "Bot" section
Click "Add Bot"
Click "Reset Token" to copy bot token
⚠️ Keep this token secret! Never commit to git

3. Configure Bot Permissions

Go to "OAuth2" → "URL Generator"
Select Scopes: bot
Select Permissions:
- ✓ Send Messages
- ✓ Create Public Threads
- ✓ Send Messages in Threads
- ✓ Embed Links
- ✓ Attach Files
- ✓ Read Message History
Copy the generated URL

4. Add Bot to Server

Open the OAuth2 URL in your browser
Select your Discord server
Click "Authorize"
Complete the CAPTCHA

5. Get Required IDs

Method 1: Developer Mode (Easiest)

Open Discord User Settings → Advanced
Enable "Developer Mode"
Right-click server name → "Copy Server ID" (Server ID)
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:

Validates input path
Initializes Discord thread with file info
Compresses file with LZMA2 (8MB segments)
Uploads segments to Discord
Generates and uploads metadata.json
Cleans up temporary files
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:

Fetches metadata.json
Creates directory structure
Downloads all archive segments
Extracts using 7-Zip
Cleans up temporary files
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

Write Code: Create TypeScript files in src/
Test Locally: Use npm run dev for auto-reload testing
Validate: Run npm run type-check to check types
Lint: Run npm run lint to check code quality
Build: Run npm run build to verify compilation
Test Complete Flow: Manually test upload/download
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

Related Libraries

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

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
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:

Compress pre-upload (though files are already compressed)
Use multiple bot instances
Increase Discord API request limits if possible
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:

Bot token is correct
Bot is invited to server
Forum channel exists and bot has access
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:

📞 Support

Getting Help

Check Troubleshooting section
Review existing GitHub Issues
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:

Compress files to 8MB segments
Upload segments to Discord
Create metadata.json with upload metadata
Send metadata.json as file attachment
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

Parse Metadata: Supports both attachment and legacy formats
Create Directory: With proper folder naming
Save Metadata: Write to disk (required by Restore)
Download Parts: Stream-based using pipeline()
Reassemble: Call Restore() with metadata
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

🛡️ 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

Read the Quick Start section
Review Features
Check Configuration

For Developers

Understand Project Structure
Review API Documentation
Explore source code in src/

For Contributors

Read the Development section
Review Technical Details
Run tests before submitting PRs

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Run tests and linting
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:

Check Troubleshooting
Review FAQ
Open an issue on GitHub
Provide:
- Error messages and logs
- Steps to reproduce
- System information

Last Updated: January 27, 2026
Current Version: 0.1.0

This project was created with ❤️ for the Discord community

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
eslint.config.ts		eslint.config.ts
index.d.ts		index.d.ts
package.json		package.json
shims-dc-cloud.d.ts		shims-dc-cloud.d.ts
tsconfig.json		tsconfig.json

License

NeelFrostrain/DCloud

Folders and files

Latest commit

History

Repository files navigation

DCloud 🌥️

📋 Table of Contents

🎯 Overview

🔄 How It Works

💡 Key Concept

⚡ Quick Start

1️⃣ Install Package

2️⃣ Clone & Install (Development)

3️⃣ Get Discord Credentials

4️⃣ Update Configuration

5️⃣ Run

✨ Features

📦 Prerequisites

Minimum Requirements

External Dependencies

Discord Bot Permissions

Operating System Support

🚀 Installation

Step 1: Clone Repository

Step 2: Install Dependencies

Step 3: Verify Installation

Step 4: Configuration (See Configuration Section)

⚙️ Configuration

Setting Up Discord Bot (Step-by-Step)

1. Create Discord Application

2. Create Bot User

3. Configure Bot Permissions

4. Add Bot to Server

5. Get Required IDs

Environment Configuration

Option A: Direct in Code (Development)

Option B: Environment Variables (Production)

Configuration Verification

📖 Usage

Using from NPM Package

Local Development Setup

Running the Application

1. Development Mode (Auto-reload)

2. Production Mode (Compiled)

3. Type Check Only

🔌 API Documentation

DCloud Class

Constructor

Methods

init(): Promise<void>

upload(filePath: string): Promise<ICompressorResult>

downloader(metadataUrl: string, outputPath: string): Promise<void>

CloudBot Class

Methods

Init(): Promise<void>

IsBotOnline(): boolean

Interfaces

ICloudBot

ICompressor

ICompressorResult

📁 Project Structure

Directory Breakdown

📋 Scripts & Commands

Development Commands

Production Commands

Quick Reference

🔧 Development

Code Quality

ESLint Configuration

TypeScript Validation

Development Workflow

Adding Features

Step 1: Define Types

Step 2: Create Utilities

Step 3: Add Methods

Step 4: Update Public API

🐛 Troubleshooting

Bot Connection Issues

Upload Failures

`init(): Promise<void>`

`upload(filePath: string): Promise<ICompressorResult>`

`downloader(metadataUrl: string, outputPath: string): Promise<void>`

`Init(): Promise<void>`

`IsBotOnline(): boolean`

`ensureFileReady(filePath: string): Promise<void>`

`cleanupFolder(folderPath: string): Promise<void>`