@marcuth/mediafire 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marcuth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# @marcuth/mediafire
+
+**@marcuth/mediafire** is a package for the [Mediafire](https://mediafire.com) service designed to communicate with its API, handling authentication, file management, and folder organization.
+
+## 📦 Installation
+
+Installation is straightforward; simply use your preferred package manager. Here is an example using NPM:
+
+```bash
+npm i @marcuth/mediafire
+
+```
+
+## 🚀 Usage
+
+<a href="https://www.buymeacoffee.com/marcuth">
+  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="200">
+</a>
+
+### Authentication
+
+To access the routes, you must first authenticate. There are two ways to do this: using email and password (the only method implemented so far) or via API Keys.
+
+**Using email and password:**
+
+```ts
+import { Mediafire } from "@marcuth/mediafire"
+
+;(async () => {
+	const mediafire = new Mediafire({
+		email: "YOUR_EMAIL",
+		password: "YOUR_PASSWORD"
+	})
+	
+	await mediafire.logIn()
+})();
+
+```
+
+---
+
+### Folders
+
+#### Getting information
+
+```ts
+import { Mediafire } from "@marcuth/mediafire"
+
+;(async () => {
+	// Your way of instantiating Mediafire
+
+	const folderInfo = await mediafire.folders.getInfo({
+		folderKey: "your-folder-key"
+	})
+
+	console.log(folderInfo)
+})();
+
+```
+
+#### Getting information by path
+
+```ts
+import { Mediafire } from "@marcuth/mediafire"
+
+;(async () => {
+	// Your way of instantiating Mediafire
+
+	const folderInfo = await mediafire.folders.getInfo({
+		folderPath: "path/to/folder"
+	})
+
+	console.log(folderInfo)
+})();
+
+```
+
+#### Getting contents
+
+```ts
+import { Mediafire } from "@marcuth/mediafire"
+
+;(async () => {
+	// Your way of instantiating Mediafire
+
+	const folderContents = await mediafire.folders.getContents({
+		folderKey: "your-folder-key"
+	})
+
+	console.log(folderContents)
+})();
+
+```
+
+#### Getting contents by path
+
+```ts
+import { Mediafire } from "@marcuth/mediafire"
+
+;(async () => {
+	// Your way of instantiating Mediafire
+
+	const folderContents = await mediafire.folders.getContents({
+		folderPath: "path/to/folder"
+	})
+
+	console.log(folderContents)
+})();
+
+```
+
+---
+
+### Files
+
+#### Getting information
+
+```ts
+import { Mediafire } from "@marcuth/mediafire"
+
+;(async () => {
+	// Your way of instantiating Mediafire
+
+	const fileInfo = await mediafire.files.getInfo({
+		quickKey: "your-quick-key"
+	})
+
+	console.log(fileInfo)
+})();
+
+```
+
+#### Getting information by path
+
+```ts
+import { Mediafire } from "@marcuth/mediafire"
+
+;(async () => {
+	// Your way of instantiating Mediafire
+
+	const fileInfo = await mediafire.files.getInfoByPath({
+		filePath: "path/to/folder/file.ext"
+	})
+
+	console.log(fileInfo)
+})();
+
+```
+
+#### Getting download links
+
+```ts
+import { Mediafire } from "@marcuth/mediafire"
+
+;(async () => {
+	// Your way of instantiating Mediafire
+
+	const fileLinksInfo = await mediafire.files.getLinks({
+		quickKey: "your-quick-key"
+	})
+
+	console.log(fileLinksInfo)
+})();
+
+```
+
+#### Uploading a file
+
+```ts
+import { Mediafire } from "@marcuth/mediafire"
+import fs from "node:fs"
+
+;(async () => {
+	// Your way of instantiating Mediafire
+
+	const uploadInfo = await mediafire.files.upload({
+		fileName: "file.ext",
+		file: fs.createReadStream("path/to/source-file.ext")
+	})
+
+	console.log(uploadInfo)
+})();
+
+```
+
+#### Uploading a file to a specific path
+
+```ts
+import { Mediafire } from "@marcuth/mediafire"
+import fs from "node:fs"
+
+;(async () => {
+	// Your way of instantiating Mediafire
+
+	const uploadInfo = await mediafire.files.uploadToPath({
+		filePath: "path/to/destination/file.ext",
+		file: fs.createReadStream("path/to/source-file.ext")
+	})
+
+	console.log(uploadInfo)
+})();
+
+```
+
+---
+
+## 🧪 Testing
+
+Automated tests are located in the `__tests__` directory. To run them:
+
+```bash
+npm run test
+
+```
+
+## 🤝 Contributing
+
+Want to contribute? Follow these steps:
+
+1. Fork the repository.
+2. Create a new branch (`git checkout -b feature-new`).
+3. Commit your changes (`git commit -m 'Add new feature'`).
+4. Push to the branch (`git push origin feature-new`).
+5. Open a Pull Request.
+
+## 📝 License
+
+This project is licensed under the MIT License.

package/dist/enums/action-on-duplicate-file.d.ts

@@ -0,0 +1,5 @@
+export declare enum ActionOnDuplicateFile {
+    Keep = "keep",
+    Skip = "skip",
+    Replace = "replace"
+}

package/dist/enums/action-on-duplicate-file.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionOnDuplicateFile = void 0;
+var ActionOnDuplicateFile;
+(function (ActionOnDuplicateFile) {
+    ActionOnDuplicateFile["Keep"] = "keep";
+    ActionOnDuplicateFile["Skip"] = "skip";
+    ActionOnDuplicateFile["Replace"] = "replace";
+})(ActionOnDuplicateFile || (exports.ActionOnDuplicateFile = ActionOnDuplicateFile = {}));

package/dist/enums/content-type.d.ts

@@ -0,0 +1,5 @@
+export declare enum ContentType {
+    Folders = "folders",
+    Files = "files",
+    Both = "both"
+}

package/dist/enums/content-type.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentType = void 0;
+var ContentType;
+(function (ContentType) {
+    ContentType["Folders"] = "folders";
+    ContentType["Files"] = "files";
+    ContentType["Both"] = "both";
+})(ContentType || (exports.ContentType = ContentType = {}));

package/dist/enums/details.d.ts

@@ -0,0 +1,5 @@
+export declare enum Details {
+    No = "no",
+    Yes = "yes",
+    Shallow = "shallow"
+}

package/dist/enums/details.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Details = void 0;
+var Details;
+(function (Details) {
+    Details["No"] = "no";
+    Details["Yes"] = "yes";
+    Details["Shallow"] = "shallow";
+})(Details || (exports.Details = Details = {}));

package/dist/enums/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./action-on-duplicate-file";
+export * from "./content-type";
+export * from "./details";
+export * from "./order-direction";
+export * from "./order-by";
+export * from "./upload-status";

package/dist/enums/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./action-on-duplicate-file"), exports);
+__exportStar(require("./content-type"), exports);
+__exportStar(require("./details"), exports);
+__exportStar(require("./order-direction"), exports);
+__exportStar(require("./order-by"), exports);
+__exportStar(require("./upload-status"), exports);

package/dist/enums/order-by.d.ts

@@ -0,0 +1,6 @@
+export declare enum OrderBy {
+    Name = "name",
+    Date = "date",
+    Size = "size",
+    Downloads = "downloads"
+}

package/dist/enums/order-by.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderBy = void 0;
+var OrderBy;
+(function (OrderBy) {
+    OrderBy["Name"] = "name";
+    OrderBy["Date"] = "date";
+    OrderBy["Size"] = "size";
+    OrderBy["Downloads"] = "downloads";
+})(OrderBy || (exports.OrderBy = OrderBy = {}));

package/dist/enums/order-direction.d.ts

@@ -0,0 +1,4 @@
+export declare enum OrderDirection {
+    Asc = "asc",
+    Desc = "desc"
+}

package/dist/enums/order-direction.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderDirection = void 0;
+var OrderDirection;
+(function (OrderDirection) {
+    OrderDirection["Asc"] = "asc";
+    OrderDirection["Desc"] = "desc";
+})(OrderDirection || (exports.OrderDirection = OrderDirection = {}));

package/dist/enums/upload-status.d.ts

@@ -0,0 +1,13 @@
+export declare enum UploadStatus {
+    Unknown = "0",
+    Ready = "2",
+    UploadInProgress = "3",
+    UploadCompleted = "4",
+    WaitingForVerification = "5",
+    VerifyingFile = "6",
+    FinishedVerification = "11",
+    UploadInProgressSecondary = "17",
+    WaitingForAssembly = "18",
+    AssemblingFile = "19",
+    NoMoreRequests = "99"
+}

package/dist/enums/upload-status.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UploadStatus = void 0;
+var UploadStatus;
+(function (UploadStatus) {
+    UploadStatus["Unknown"] = "0";
+    UploadStatus["Ready"] = "2";
+    UploadStatus["UploadInProgress"] = "3";
+    UploadStatus["UploadCompleted"] = "4";
+    UploadStatus["WaitingForVerification"] = "5";
+    UploadStatus["VerifyingFile"] = "6";
+    UploadStatus["FinishedVerification"] = "11";
+    UploadStatus["UploadInProgressSecondary"] = "17";
+    UploadStatus["WaitingForAssembly"] = "18";
+    UploadStatus["AssemblingFile"] = "19";
+    UploadStatus["NoMoreRequests"] = "99";
+})(UploadStatus || (exports.UploadStatus = UploadStatus = {}));

package/dist/error.d.ts

@@ -0,0 +1,3 @@
+export declare class MediafireError extends Error {
+    constructor(message: string);
+}

package/dist/error.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediafireError = void 0;
+class MediafireError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MediafireError";
+    }
+}
+exports.MediafireError = MediafireError;

package/dist/files-service.d.ts

@@ -0,0 +1,154 @@
+import { ActionOnDuplicateFile } from "./enums/action-on-duplicate-file";
+import { Mediafire } from "./mediafire";
+export type UploadOptions = {
+    file: Buffer | NodeJS.ReadableStream;
+    fileName: string;
+    folderKey?: string;
+    actionOnDuplicate?: ActionOnDuplicateFile | `${ActionOnDuplicateFile}`;
+};
+export type FileActionOptions = {
+    quickKey: string;
+};
+export type MoveFileOptions = {
+    quickKey: string;
+    folderKey: string;
+};
+export type GetInfoByPathOptions = {
+    filePath: string;
+};
+export type PollUploadOptions = {
+    uploadKey: string;
+};
+export type UploadToPathOptions = Omit<UploadOptions & {
+    filePath: string;
+}, "folderKey" | "fileName">;
+export declare class FilesService {
+    private readonly mediafire;
+    private readonly pollDelay;
+    constructor(mediafire: Mediafire, pollDelay: number);
+    upload({ file, fileName, folderKey, actionOnDuplicate }: UploadOptions): Promise<{
+        doupload: {
+            result: string;
+            upload_key: string;
+            quick_key: string;
+            download_links: {
+                quickkey: string;
+                normal_download: string;
+                one_time: {
+                    download: string;
+                };
+            }[];
+        };
+        action: string;
+        server: string;
+        result: string;
+        new_key: string;
+        current_api_version: string;
+    }>;
+    pollUpload({ uploadKey }: PollUploadOptions): Promise<{
+        action: string;
+        doupload: {
+            result: string;
+            status: string;
+            description: string;
+            quickkey: string;
+            hash: string;
+            filename: string;
+            size: string;
+            created: string;
+            revision: string;
+            created_utc: string;
+        };
+        result: string;
+        current_api_version: string;
+        new_key?: undefined;
+    }>;
+    getInfo({ quickKey }: FileActionOptions): Promise<{
+        action: string;
+        file_info: {
+            quickkey: string;
+            filename: string;
+            ready: string;
+            created: string;
+            downloads: string;
+            description: string;
+            size: string;
+            privacy: string;
+            password_protected: string;
+            hash: string;
+            filetype: string;
+            mimetype: string;
+            owner_name: string;
+            flag: string;
+            parent_folderkey: string;
+            revision: string;
+            view: string;
+            edit: string;
+            links: {
+                normal_download: string;
+            };
+            created_utc: string;
+        };
+        result: string;
+        new_key: string;
+        current_api_version: string;
+    }>;
+    getInfoByPath({ filePath }: GetInfoByPathOptions): Promise<{
+        quickkey: string;
+        hash: string;
+        filename: string;
+        description: string;
+        size: string;
+        privacy: string;
+        created: string;
+        password_protected: string;
+        mimetype: string;
+        filetype: string;
+        view: string;
+        edit: string;
+        revision: string;
+        flag: string;
+        downloads: string;
+        views: string;
+        links: {
+            normal_download: string;
+        };
+        created_utc: string;
+    }>;
+    uploadToPath({ filePath, file, actionOnDuplicate }: UploadToPathOptions): Promise<{
+        doupload: {
+            result: string;
+            upload_key: string;
+            quick_key: string;
+            download_links: {
+                quickkey: string;
+                normal_download: string;
+                one_time: {
+                    download: string;
+                };
+            }[];
+        };
+        action: string;
+        server: string;
+        result: string;
+        new_key: string;
+        current_api_version: string;
+    }>;
+    move({ quickKey, folderKey }: MoveFileOptions): Promise<any>;
+    getLinks({ quickKey }: FileActionOptions): Promise<{
+        action: string;
+        links: {
+            quickkey: string;
+            normal_download: string;
+            one_time: {
+                download: string;
+            };
+        }[];
+        one_time_key_request_count: string;
+        one_time_key_request_max_count: string;
+        result: string;
+        new_key: string;
+        current_api_version: string;
+    }>;
+    delete({ quickKey }: FileActionOptions): Promise<any>;
+}

package/dist/files-service.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilesService = void 0;
+const form_data_1 = __importDefault(require("form-data"));
+const node_path_1 = __importDefault(require("node:path"));
+const content_type_1 = require("./enums/content-type");
+const error_1 = require("./error");
+class FilesService {
+    constructor(mediafire, pollDelay) {
+        this.mediafire = mediafire;
+        this.pollDelay = pollDelay;
+    }
+    async upload({ file, fileName, folderKey, actionOnDuplicate }) {
+        const action = "upload/simple";
+        const form = new form_data_1.default();
+        form.append("Filedata", file, { filename: fileName });
+        const data = await this.mediafire.request(action, {
+            folder_key: folderKey,
+            action_on_duplicate: actionOnDuplicate,
+        }, form);
+        const resonseData = data.response;
+        const uploadKey = resonseData.doupload.key;
+        const pollUploadInfo = await this.pollUpload({ uploadKey: uploadKey });
+        const quickKey = pollUploadInfo.doupload.quickkey;
+        const linksInfo = await this.getLinks({ quickKey: quickKey });
+        const downloadLinks = linksInfo.links;
+        return {
+            ...resonseData,
+            doupload: {
+                result: resonseData.doupload.result,
+                upload_key: resonseData.doupload.key,
+                quick_key: quickKey,
+                download_links: downloadLinks
+            }
+        };
+    }
+    async pollUpload({ uploadKey }) {
+        const action = "upload/poll_upload";
+        const data = await this.mediafire.request(action, {
+            key: uploadKey
+        });
+        const responseData = data.response;
+        if (!responseData.doupload.quickkey) {
+            throw new error_1.MediafireError("Not found quick_key in poll upload");
+        }
+        return responseData;
+    }
+    async getInfo({ quickKey }) {
+        const action = "file/get_info";
+        const data = await this.mediafire.request(action, {
+            quick_key: quickKey
+        });
+        return data.response;
+    }
+    async getInfoByPath({ filePath }) {
+        const parts = node_path_1.default.parse(filePath);
+        const dirPath = parts.dir;
+        const fileName = parts.base;
+        const folderContents = await this.mediafire.folders.getContentsByPath({
+            folderPath: dirPath,
+            contentType: content_type_1.ContentType.Files
+        });
+        const file = folderContents.folder_content.files?.find(file => file.filename === fileName);
+        if (!file) {
+            throw new error_1.MediafireError(`File not found: ${fileName} at ${filePath}`);
+        }
+        return file;
+    }
+    async uploadToPath({ filePath, file, actionOnDuplicate }) {
+        const parts = node_path_1.default.parse(filePath);
+        const dirPath = parts.dir;
+        const fileName = parts.base;
+        const folderInfo = await this.mediafire.folders.getInfoByPath({ folderPath: dirPath });
+        const folderKey = folderInfo.folder_info.folderkey;
+        return await this.upload({
+            file: file,
+            fileName: fileName,
+            folderKey: folderKey,
+            actionOnDuplicate: actionOnDuplicate
+        });
+    }
+    async move({ quickKey, folderKey }) {
+        const action = "file/move";
+        return await this.mediafire.request(action, {
+            quick_key: quickKey,
+            folder_key: folderKey
+        });
+    }
+    async getLinks({ quickKey }) {
+        const action = "file/get_links";
+        const data = await this.mediafire.request(action, {
+            quick_key: quickKey
+        });
+        return data.response;
+    }
+    async delete({ quickKey }) {
+        const action = "file/delete";
+        const data = await this.mediafire.request(action, {
+            quick_key: quickKey
+        });
+        return data;
+    }
+}
+exports.FilesService = FilesService;