@jesusacd/mediafire

Complete MediaFire SDK for Node.js. Just use your email and password to access all API features.

✨ Features

• 🔐 Simple Authentication - Just email and password, no API keys needed
• 📁 Full Management - Files and folders (create, move, copy, delete)
• 📤 File Upload - Supports large files
• 🔍 Search - Search files in your account
• 🔗 Direct Links - Get download URLs
• 📊 TypeScript - Full type definitions included

📦 Installation

npm install @jesusacd/mediafire

🚀 Quick Start

const { MediaFireClient } = require("@jesusacd/mediafire");

const client = new MediaFireClient();

async function main() {
  // Just email and password - that's it!
  await client.login("your-email@example.com", "your-password");

  // Get user info
  const user = await client.user.getInfo();
  console.log(`Hello, ${user.displayName}!`);

  // Upload a file
  const result = await client.upload.file("./my-file.pdf");
  console.log(`Uploaded: ${result.quickKey}`);

  // Get download link
  const links = await client.files.getLinks(result.quickKey);
  console.log(`Link: ${links.directDownload}`);
}

main();

📚 API Reference

Authentication

const client = new MediaFireClient();

// Login with email and password
await client.login("email@example.com", "password");

// Check if authenticated
client.isAuthenticated(); // true

// Get session data
const session = client.getSession();

// Restore previous session
client.setSession(session);

// Logout
client.logout();

---

👤 User Module

// User information
const user = await client.user.getInfo();
// { displayName, email, firstName, lastName, gender, birthDate, premium, emailVerified, createdAt }

// Storage info
const storage = await client.user.getStorage();
// { used, total, usedFormatted: "500 MB", totalFormatted: "10 GB", percentUsed: 5 }

---

📁 Folders Module

// List folder contents
const content = await client.folders.getContent("folderKey");
// { items: [...], moreChunks, chunkNumber }

// Get only files
const files = await client.folders.getFiles("folderKey");

// Get only folders
const folders = await client.folders.getFolders("folderKey");

// Get folder info
const info = await client.folders.getInfo("folderKey");
// { folderKey, name, description, created, privacy, fileCount, folderCount, totalSize }

// Create folder
const newFolder = await client.folders.create("My Folder", "parentKey");
// { folderKey, name }

// Rename folder
await client.folders.rename("folderKey", "New Name");

// Move to another folder
await client.folders.move("folderKey", "destFolderKey");

// Copy folder
const newKey = await client.folders.copy("folderKey", "destFolderKey");

// Change privacy
await client.folders.setPrivacy("folderKey", "public"); // or 'private'

// Delete (move to trash)
await client.folders.delete("folderKey");

// Permanently delete
await client.folders.purge("folderKey");

---

📄 Files Module

// Get file info
const fileInfo = await client.files.getInfo("quickKey");
// { quickKey, name, size, sizeFormatted, hash, created, privacy, mimeType, ... }

// Get links
const links = await client.files.getLinks("quickKey");
// { viewLink, normalDownload, directDownload }

// Search files
const results = await client.files.search("document");
// { files: [...], total }

// Change privacy
await client.files.setPrivacy("quickKey", "public");
await client.files.makePublic("quickKey"); // Shortcut
await client.files.makePrivate("quickKey"); // Shortcut

// Rename file
await client.files.rename("quickKey", "new-name.pdf");

// Move to another folder
await client.files.move("quickKey", "folderKey");

// Copy file
const newKeys = await client.files.copy("quickKey", "folderKey");

// Delete (move to trash)
await client.files.delete("quickKey");

// Restore from trash
await client.files.restore("quickKey");

// Permanently delete
await client.files.purge("quickKey");

// Get file versions
const versions = await client.files.getVersions("quickKey");

// Get recently modified files
const recent = await client.files.getRecentlyModified();

---

📤 Upload Module

// Upload file from disk
const result = await client.upload.file("./file.pdf", {
  folderKey: "destFolderKey", // Optional: destination folder
  actionOnDuplicate: "keep", // 'skip' | 'keep' | 'replace'
});
// { quickKey, filename, size, uploadKey }

// Upload from Buffer
const buffer = Buffer.from("File content");
const result = await client.upload.buffer(buffer, "file.txt", {
  folderKey: "destFolderKey",
});

// Check if file exists (for instant upload)
const check = await client.upload.check(sha256Hash, "file.pdf", fileSize);
// { hashExists, inAccount, inFolder, duplicateQuickKey }

// Instant upload (if file already exists on MediaFire)
const result = await client.upload.instant(
  sha256Hash,
  "file.pdf",
  fileSize,
  "folderKey",
);

---

💡 Usage Examples

Upload multiple files

const files = ["doc1.pdf", "doc2.pdf", "image.png"];

for (const file of files) {
  const result = await client.upload.file(file);
  console.log(`✅ ${file} -> ${result.quickKey}`);
}

Create folder structure

// Create main folder
const main = await client.folders.create("Project 2024");

// Create subfolders
await client.folders.create("Documents", main.folderKey);
await client.folders.create("Images", main.folderKey);
await client.folders.create("Videos", main.folderKey);

Backup local folder

const fs = require("fs");
const path = require("path");

async function backupFolder(localPath, remoteFolderKey) {
  const files = fs.readdirSync(localPath);

  for (const file of files) {
    const filePath = path.join(localPath, file);

    if (fs.statSync(filePath).isFile()) {
      const result = await client.upload.file(filePath, {
        folderKey: remoteFolderKey,
      });
      console.log(`✅ ${file} uploaded`);
    }
  }
}

// Usage
const folder = await client.folders.create("Backup-" + Date.now());
await backupFolder("./my-documents", folder.folderKey);

Get all links from a folder

const files = await client.folders.getFiles("folderKey");

for (const file of files) {
  const links = await client.files.getLinks(file.quickKey);
  console.log(`${file.name}: ${links.directDownload || links.viewLink}`);
}

Search and download

const results = await client.files.search("report");

for (const file of results.files) {
  const links = await client.files.getLinks(file.quickKey);
  console.log(`📄 ${file.name}`);
  console.log(`   Download: ${links.directDownload}`);
}

---

⚠️ Error Handling

const { MediaFireClient, MediaFireError } = require("@jesusacd/mediafire");

try {
  await client.login("email", "wrong-password");
} catch (error) {
  if (error instanceof MediaFireError) {
    console.log("MediaFire Error:", error.message);
    console.log("Code:", error.code);
  }
}

---

📊 Limits and Performance

• Max file size: Depends on your MediaFire plan
• Upload speed: ~16 MB/s (depends on your connection)
• Session: Automatically managed with key rotation

---

🔧 Advanced Configuration

const client = new MediaFireClient({
  appId: "42511", // App ID (optional, uses default)
  apiVersion: "1.3", // API version
  timeout: 30000, // Timeout in ms
});

---

📋 Available Methods

Module	Method	Description
Auth	login(email, password)	Log in
	logout()	Log out
	isAuthenticated()	Check authentication
	getSession()	Get session data
	setSession(session)	Restore session
User	getInfo()	User info
	getStorage()	Storage used
Folders	getContent(key, options)	List contents
	getFiles(key, options)	List files
	getFolders(key, options)	List folders
	getInfo(key)	Folder info
	create(name, parentKey)	Create folder
	rename(key, newName)	Rename
	move(key, destKey)	Move
	copy(key, destKey)	Copy
	setPrivacy(key, privacy)	Change privacy
	delete(key)	Delete (trash)
	purge(key)	Permanently delete
Files	getInfo(quickKey)	File info
	getLinks(quickKey)	Get links
	search(query, options)	Search files
	setPrivacy(quickKey, privacy)	Change privacy
	makePublic(quickKey)	Make public
	makePrivate(quickKey)	Make private
	rename(quickKey, newName)	Rename
	move(quickKey, folderKey)	Move
	copy(quickKey, folderKey)	Copy
	delete(quickKey)	Delete (trash)
	restore(quickKey)	Restore
	purge(quickKey)	Permanently delete
	getVersions(quickKey)	Version history
	getRecentlyModified()	Recent files
Upload	file(path, options)	Upload from disk
	buffer(buffer, name, options)	Upload from buffer
	check(hash, name, size)	Check existence
	instant(hash, name, size)	Instant upload

---

📄 License

MIT © JesusACD