tgbox 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# TgBox
+
+TgBox is a lightweight cloud storage service for Node.js that uses Telegram as
+its storage medium. It lets you use Telegram chats and channels as personal or
+shared cloud storage for uploading, downloading, searching, and managing files.
+
+Telegram provides the storage infrastructure, while TgBox provides a simple
+programmatic interface for using it like a cloud drive.
+
+## Installation
+
+[![npm package](https://img.shields.io/npm/v/tgbox)](https://www.npmjs.com/package/tgbox)
+
+The package is available on [npm](https://www.npmjs.com/package/tgbox).
+
+```bash
+npm install tgbox
+```
+
+## How it works
+
+TgBox stores files as Telegram document messages in a chat or channel. The
+Telegram message ID acts as the file ID, so files can later be listed, searched,
+downloaded, or deleted through the TgBox API.
+
+The target can be:
+
+- `me` for Telegram Saved Messages
+- a username such as `@mychannel`
+- another Telegram chat or channel the account can access
+
+## Telegram API credentials
+
+You need a Telegram `apiId` and `apiHash` to connect. You can get both values
+from [my.telegram.org](https://my.telegram.org).
+
+```js
+const TgBox = require('tgbox');
+
+const storage = new TgBox(
+  process.env.TELEGRAM_API_ID,
+  process.env.TELEGRAM_API_HASH,
+);
+
+await storage.init();
+```
+
+On the first start, TgBox asks for your phone number, login code, and, if
+configured, your 2FA password. The session is then stored locally in
+`session.txt`. Never publish or share this file.
+
+## Upload files
+
+```js
+const result = await storage.upload('./documents/report.pdf', '@mychannel');
+
+if (result.success) {
+  console.log(result.messageId);
+  console.log(result.fileName);
+} else {
+  console.error(result.error);
+}
+```
+
+The default chat is `me` (Saved Messages). Telegram file sizes are returned in
+`size` as bytes.
+
+## List files
+
+```js
+const result = await storage.listFiles('@mychannel');
+
+if (result.success) {
+  result.files.forEach((file) => {
+    console.log(file.messageId, file.fileName, file.size, file.mimeType);
+  });
+}
+```
+
+Each file object contains, among other fields:
+
+- `messageId`
+- `fileName`
+- `size` in bytes
+- `mimeType`
+- `date`
+- `caption`
+- `telegram` with the complete Telegram message and document data
+
+## Search files
+
+The search checks the file name, caption, and message ID:
+
+```js
+const result = await storage.searchFiles('report', '@mychannel');
+
+result.files.forEach((file) => {
+  console.log(file);
+});
+```
+
+For an exact search by ID or file name:
+
+```js
+const result = await storage.findFile('report.pdf', '@mychannel');
+
+result.files.forEach((file) => {
+  console.log(file.messageId, file.fileName);
+});
+```
+
+All files with the same name are returned.
+
+## Download files
+
+```js
+const result = await storage.download(
+  123,
+  './downloads/report.pdf',
+  '@mychannel',
+);
+
+if (!result.success) {
+  console.error(result.error);
+}
+```
+
+## Delete files
+
+You can delete one or more files by their Telegram message IDs:
+
+```js
+await storage.deleteFile(123, '@mychannel');
+await storage.deleteFile([123, 124], '@mychannel');
+```
+
+Deletion is permanent and uses `revoke: true`. Your Telegram account needs the
+required permissions in the target chat or channel.
+
+## Send messages
+
+```js
+const result = await storage.writeMessage(
+  'Backup completed successfully.',
+  '@mychannel',
+);
+
+console.log(result.messageId);
+```
+
+## Error handling
+
+File operations return a result object:
+
+```js
+{
+  success: true,
+  files: []
+}
+```
+
+If an operation fails, `success` is set to `false` and the error message is
+available in `error`.
+
+## Security
+
+Never commit your API hash, API ID, or `session.txt` to Git or publish them in
+an npm package. Use environment variables and add local files to `.gitignore`.
+
+## License
+
+MIT

package/fileService.js

@@ -0,0 +1,155 @@
+const fs = require('fs');
+
+class FileService {
+  constructor(client) {
+    this.client = client;
+  }
+
+  async upload(filePath, targetChat = 'me') {
+    try {
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found at path: ${filePath}`);
+      }
+
+      const result = await this.client.sendFile(targetChat, {
+        file: filePath,
+        workers: 2,
+      });
+
+      return {
+        success: true,
+        messageId: result.id,
+        fileName: filePath.split(/[\\/]/).pop(),
+      };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  async download(messageId, outputPath, targetChat = 'me') {
+    try {
+      const messages = await this.client.getMessages(targetChat, {
+        ids: [messageId],
+      });
+
+      if (!messages || messages.length === 0) {
+        throw new Error('Message not found.');
+      }
+
+      await this.client.downloadMedia(messages[0], {
+        outputFile: outputPath,
+      });
+
+      return { success: true, path: outputPath };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  async deleteFile(messageId, targetChat = 'me') {
+    const messageIds = Array.isArray(messageId) ? messageId : [messageId];
+    if (
+      messageIds.length === 0 ||
+      messageIds.some((id) => !Number.isInteger(Number(id)) || Number(id) <= 0)
+    ) {
+      return { success: false, error: 'A valid file message ID is required.' };
+    }
+
+    try {
+      await this.client.deleteMessages(
+        targetChat,
+        messageIds.map(Number),
+        { revoke: true },
+      );
+
+      return { success: true, messageIds: messageIds.map(Number) };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  async listFiles(targetChat = 'me') {
+    try {
+      const files = [];
+
+      for await (const message of this.client.iterMessages(targetChat, {
+        limit: 0,
+      })) {
+        if (!message.document) {
+          continue;
+        }
+
+        const fileNameAttribute = message.document.attributes.find(
+          (attribute) => attribute.className === 'DocumentAttributeFilename',
+        );
+
+        files.push({
+          messageId: message.id,
+          fileName: fileNameAttribute ? fileNameAttribute.fileName : null,
+          size: Number(message.document.size),
+          mimeType: message.document.mimeType,
+          date: message.date,
+          caption: message.message || null,
+          telegram: {
+            message: message.toJSON(),
+            document: message.document.toJSON(),
+          },
+        });
+      }
+
+      return { success: true, files };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  async searchFiles(query, targetChat = 'me') {
+    if (typeof query !== 'string' || query.trim() === '') {
+      return { success: false, error: 'Search query must not be empty.' };
+    }
+
+    const result = await this.listFiles(targetChat);
+    if (!result.success) {
+      return result;
+    }
+
+    const normalizedQuery = query.trim().toLowerCase();
+    const files = result.files.filter((file) => {
+      const fileName = file.fileName || '';
+      const caption = file.caption || '';
+      const messageId = String(file.messageId);
+      return (
+        messageId === normalizedQuery ||
+        `${fileName} ${caption}`.toLowerCase().includes(normalizedQuery)
+      );
+    });
+
+    return { success: true, files };
+  }
+
+  async findFile(identifier, targetChat = 'me') {
+    if (typeof identifier !== 'string' && typeof identifier !== 'number') {
+      return { success: false, error: 'File ID or name is required.' };
+    }
+
+    const query = String(identifier).trim();
+    if (!query) {
+      return { success: false, error: 'File ID or name must not be empty.' };
+    }
+
+    const result = await this.listFiles(targetChat);
+    if (!result.success) {
+      return result;
+    }
+
+    const files = result.files.filter(
+      (item) =>
+        String(item.messageId) === query ||
+        (item.fileName && item.fileName.toLowerCase() === query.toLowerCase()),
+    );
+
+    return { success: true, files };
+  }
+}
+
+module.exports = FileService;

package/index.js

@@ -0,0 +1,69 @@
+const { TelegramClient } = require('telegram');
+const { StringSession } = require('telegram/sessions');
+const input = require('input');
+const fs = require('fs');
+const FileService = require('./fileService');
+
+class TgBox {
+  constructor(apiId, apiHash, sessionFilePath = 'session.txt') {
+    if (!apiId || !apiHash) {
+      throw new Error('TgBox requires apiId and apiHash.');
+    }
+    this.apiId = Number(apiId);
+    this.apiHash = apiHash;
+    this.sessionFilePath = sessionFilePath;
+    this.fileService = null;
+
+    let savedSession = '';
+    if (fs.existsSync(this.sessionFilePath)) {
+      savedSession = fs.readFileSync(this.sessionFilePath, 'utf8').trim();
+    }
+
+    this.stringSession = new StringSession(savedSession);
+  }
+
+  async init() {
+    this.client = new TelegramClient(this.stringSession, this.apiId, this.apiHash, {
+      connectionRetries: 5,
+    });
+    this.fileService = new FileService(this.client);
+
+    await this.client.start({
+      phoneNumber: async () => await input.text('[INFO] Type your phonenumber in: '),
+      password: async () => await input.text('[INFO] 2FA Code: '),
+      phoneCode: async () => await input.text('[INFO] Telegram code: '),
+      onError: (err) => console.log("[ERROR] " + err),
+    });
+
+    console.log('[INFO] Successfully logged in!');
+
+
+    const currentSession = this.client.session.save();
+    fs.writeFileSync(this.sessionFilePath, currentSession);
+  }
+  async upload(filePath, targetChat = 'me') {
+    return this.fileService.upload(filePath, targetChat);
+  }
+  
+  async download(messageId, outputPath, targetChat = 'me') {
+    return this.fileService.download(messageId, outputPath, targetChat);
+  }
+
+  async deleteFile(messageId, targetChat = 'me') {
+    return this.fileService.deleteFile(messageId, targetChat);
+  }
+
+  async listFiles(targetChat = 'me') {
+    return this.fileService.listFiles(targetChat);
+  }
+
+  async searchFiles(query, targetChat = 'me') {
+    return this.fileService.searchFiles(query, targetChat);
+  }
+
+  async findFile(identifier, targetChat = 'me') {
+    return this.fileService.findFile(identifier, targetChat);
+  }
+}
+
+module.exports = TgBox;

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "tgbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "A lightweight free cloud storage solution using Telegram as backend.",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/johanneshehl/tgBox.git"
+  },
+  "homepage": "https://github.com/johanneshehl/tgBox#readme",
+  "bugs": {
+    "url": "https://github.com/johanneshehl/tgBox/issues"
+  },
+  "files": [
+    "index.js",
+    "fileService.js"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "telegram",
+    "storage",
+    "cloud",
+    "backup",
+    "files"
+  ],
+  "author": "Dein Name",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.7.9",
+    "form-data": "^4.0.1",
+    "input": "^1.0.1",
+    "telegram": "^2.26.22",
+    "tgbox": "^1.0.0"
+  }
+}