supertelegram 0.1.3 → 0.3.0

package/README.md

@@ -8,41 +8,63 @@ telegram cli for ai to read/write messages using gramjs.
 npm install -g supertelegram
 ```
 
-## setup
+## quick start
 
-create `.env` file in your current directory:
-```bash
-TELEGRAM_APP_ID="your_app_id"
-TELEGRAM_APP_HASH="your_app_hash"
-```
-
-get credentials from https://my.telegram.org/apps
-
-## login
+just run login and follow the prompts:
 
 ```bash
 telegram login
 ```
 
-session is saved to `session.txt` in current directory.
+if you don't have API credentials configured, it will:
+1. prompt you to get them from https://my.telegram.org/apps
+2. ask for your app_id and app_hash
+3. save them to `~/.supertelegram/config.json`
+4. continue with telegram phone/code login
+5. save session to `~/.supertelegram/session.txt`
+
+that's it! now you're ready to use telegram from the cli.
 
 ## usage
 
+### messages
+
 ```bash
 # send a message
-telegram send <username> <message>
+telegram send @username "hello there"
 
-# read messages
-telegram read <username> [limit]
+# read messages (shows [photo], [video], [file] indicators)
+telegram read @username 10
 
 # reply to latest message
-telegram reply <username> <message>
+telegram reply "John" "hey back!"
 
-# get unread messages (json output)
-telegram unread [limit]
+# get unread messages (json output with media info)
+telegram unread 20
 
 # list dialogs
-telegram dialogs [limit]
+telegram dialogs 10
+```
+
+### media (images/videos/files)
+
+```bash
+# send a file with optional caption
+telegram send-file @username photo.jpg
+telegram send-file @username video.mp4 "check this out!"
+
+# download media from a message
+# (use 'read' command to get message IDs)
+telegram download @username 12345 ./downloaded.jpg
+telegram download @username 12346  # auto-named file
+```
+
+### config
+
+manually set API credentials (optional):
+```bash
+telegram config set appId "12345678"
+telegram config set appHash "abc123..."
 ```
 
 ### flags
@@ -51,6 +73,27 @@ telegram dialogs [limit]
 - `--help` - show help
 - `--version` - show version
 
+### advanced
+
+**multi-account / custom session location:**
+```bash
+# use env var
+TELEGRAM_SESSION=./custom.txt telegram send @friend "hey"
+
+# or pass flag (todo)
+telegram send @friend "hey" --session ./custom.txt
+```
+
+**precedence for API credentials:**
+1. `TELEGRAM_APP_ID` and `TELEGRAM_APP_HASH` env vars
+2. `~/.supertelegram/config.json` (global)
+3. `.env` file in current directory (for dev)
+
+**precedence for session file:**
+1. `TELEGRAM_SESSION` env var
+2. `~/.supertelegram/session.txt` (global default)
+3. `./session.txt` (backwards compat)
+
 ## development
 
 clone repo and install:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supertelegram",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "telegram cli for humans and bots",
   "module": "index.ts",
   "type": "module",

package/src/cli/commands.ts

@@ -6,8 +6,12 @@ import {
   disconnect,
   getClient,
   login as telegramLogin,
+  sendFile as telegramSendFile,
+  downloadMedia as telegramDownloadMedia,
 } from "../client/telegram";
-import { askPhoneNumber, askPhoneCode, askPassword } from "./prompts";
+import { askPhoneNumber, askPhoneCode, askPassword, askAppId, askAppHash } from "./prompts";
+import { getApiCredentials, setConfig } from "../config/manager";
+import { Api } from "telegram";
 
 export async function send(username: string, message: string) {
   if (!(await isLoggedIn())) {
@@ -20,6 +24,29 @@ export async function send(username: string, message: string) {
   await disconnect();
 }
 
+function getMediaInfo(msg: Api.Message): string {
+  if (!msg.media) return "";
+  
+  if (msg.media instanceof Api.MessageMediaPhoto) {
+    return " [photo]";
+  }
+  if (msg.media instanceof Api.MessageMediaDocument) {
+    const doc = msg.media.document;
+    if (doc instanceof Api.Document) {
+      const attrs = doc.attributes;
+      const filenameAttr = attrs.find((a) => "fileName" in a && a.fileName);
+      const filename = filenameAttr && "fileName" in filenameAttr ? filenameAttr.fileName : undefined;
+      const isVideo = attrs.some((a) => a instanceof Api.DocumentAttributeVideo);
+      const isAudio = attrs.some((a) => a instanceof Api.DocumentAttributeAudio);
+      
+      if (isVideo) return ` [video${filename ? `: ${filename}` : ""}]`;
+      if (isAudio) return ` [audio${filename ? `: ${filename}` : ""}]`;
+      return ` [file${filename ? `: ${filename}` : ""}]`;
+    }
+  }
+  return " [media]";
+}
+
 export async function read(username: string, limit = 10) {
   if (!(await isLoggedIn())) {
     console.error("not logged in. run: telegram login");
@@ -30,7 +57,8 @@ export async function read(username: string, limit = 10) {
   for (const msg of messages.reverse()) {
     const sender = msg.senderId?.toString() ?? "unknown";
     const date = msg.date ? new Date(msg.date * 1000).toISOString() : "";
-    console.log(`[${date}] [${sender}]: ${msg.message}`);
+    const mediaInfo = getMediaInfo(msg);
+    console.log(`[${date}] [${sender}]: ${msg.message}${mediaInfo}`);
   }
   await disconnect();
 }
@@ -87,6 +115,7 @@ export async function unread(limit = 20) {
       messages: fromOthers.map((m) => ({
         id: m.id,
         text: m.message,
+        media: m.media ? getMediaInfo(m).trim() : null,
         date: m.date ? new Date(m.date * 1000).toISOString() : null,
       })),
     });
@@ -124,6 +153,18 @@ export async function reply(chatName: string, message: string) {
 }
 
 export async function login() {
+  // check if API credentials are configured
+  const creds = getApiCredentials();
+  if (!creds) {
+    console.log("no API credentials found. let's set them up first.");
+    const appId = await askAppId();
+    const appHash = await askAppHash();
+    
+    setConfig("appId", appId);
+    setConfig("appHash", appHash);
+    console.log("credentials saved to ~/.supertelegram/config.json\n");
+  }
+
   const loggedIn = await isLoggedIn();
   if (loggedIn) {
     console.log("already logged in!");
@@ -141,3 +182,66 @@ export async function login() {
   console.log("login complete!");
   await disconnect();
 }
+
+export async function config(action?: string, key?: string, value?: string) {
+  if (action === "set" && key && value) {
+    setConfig(key, value);
+    console.log(`set ${key} = ${value}`);
+    return;
+  }
+  
+  if (action === "get" && key) {
+    const cfg = getApiCredentials();
+    if (key === "appId" && cfg) {
+      console.log(cfg.appId);
+    } else if (key === "appHash" && cfg) {
+      console.log(cfg.appHash);
+    } else {
+      console.log("not found");
+    }
+    return;
+  }
+  
+  console.log("usage:");
+  console.log("  telegram config set appId <id>");
+  console.log("  telegram config set appHash <hash>");
+  console.log("  telegram config get appId");
+}
+
+export async function sendFile(username: string, filePath: string, caption?: string) {
+  if (!(await isLoggedIn())) {
+    console.error("not logged in. run: telegram login");
+    process.exit(1);
+  }
+
+  const result = await telegramSendFile(username, filePath, caption);
+  console.log(`sent file id: ${result.id}`);
+  await disconnect();
+}
+
+export async function downloadMedia(username: string, messageId: number, outputPath?: string) {
+  if (!(await isLoggedIn())) {
+    console.error("not logged in. run: telegram login");
+    process.exit(1);
+  }
+
+  const messages = await getMessages(username, 100);
+  const msg = messages.find((m) => m.id === messageId);
+  
+  if (!msg) {
+    console.error(`message ${messageId} not found`);
+    await disconnect();
+    process.exit(1);
+  }
+  
+  if (!msg.media) {
+    console.error(`message ${messageId} has no media`);
+    await disconnect();
+    process.exit(1);
+  }
+
+  console.log("downloading media...");
+  const path = await telegramDownloadMedia(msg, outputPath);
+  console.log(`saved to: ${path || outputPath || "unknown"}`);
+  await disconnect();
+}

package/src/cli/prompts.ts

@@ -23,3 +23,12 @@ export async function askUsername(): Promise<string> {
 export async function askCommand(): Promise<string> {
   return input.text("command (send/read/dialogs/quit):");
 }
+
+export async function askAppId(): Promise<string> {
+  console.log("\nget your API credentials from: https://my.telegram.org/apps\n");
+  return input.text("enter TELEGRAM_APP_ID:");
+}
+
+export async function askAppHash(): Promise<string> {
+  return input.text("enter TELEGRAM_APP_HASH:");
+}

package/src/cli/run.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
-import { send, read, dialogs, unread, reply, login } from "./commands";
-import { setVerbose } from "../client/telegram";
+import { send, read, dialogs, unread, reply, login, config, sendFile, downloadMedia } from "./commands";
+import { setVerbose, setSessionPath } from "../client/telegram";
 
 const VERSION = "0.1.0";
 const NAME = "telegram";
@@ -12,12 +12,15 @@ usage:
   ${NAME} <command> [options]
 
 commands:
-  send <chat> <message>    send a message to a chat
-  read <chat> [limit]      read messages from a chat (default: 10)
-  reply <chat> <message>   reply to a chat by name (partial match)
-  dialogs [limit]          list recent dialogs (default: 10)
-  unread [limit]           show unread messages as json (default: 20)
-  login                    authenticate with telegram (run separately)
+  send <chat> <message>      send a message to a chat
+  send-file <chat> <path>    send a file/image/video (optional: caption)
+  read <chat> [limit]        read messages from a chat (default: 10)
+  download <chat> <id> [out] download media from message id
+  reply <chat> <message>     reply to a chat by name (partial match)
+  dialogs [limit]            list recent dialogs (default: 10)
+  unread [limit]             show unread messages as json (default: 20)
+  login                      authenticate with telegram
+  config set <key> <val>     set API credentials (appId, appHash)
 
 options:
   -v, --verbose            show debug logs
@@ -26,7 +29,9 @@ options:
 
 examples:
   ${NAME} send @username "hello there"
+  ${NAME} send-file @username photo.jpg "check this out"
   ${NAME} read @username 5
+  ${NAME} download @username 12345 ./photo.jpg
   ${NAME} reply "John" "hey!"
   ${NAME} unread
   ${NAME} dialogs 20
@@ -56,7 +61,7 @@ if (verbose) {
 async function main() {
   switch (command) {
     case "send":
-      if (rest.length < 2) {
+      if (rest.length < 2 || !rest[0]) {
         console.error("usage: telegram send <chat> <message>");
         process.exit(1);
       }
@@ -64,7 +69,7 @@ async function main() {
       break;
 
     case "read":
-      if (rest.length < 1) {
+      if (rest.length < 1 || !rest[0]) {
         console.error("usage: telegram read <chat> [limit]");
         process.exit(1);
       }
@@ -80,17 +85,37 @@ async function main() {
       break;
 
     case "reply":
-      if (rest.length < 2) {
+      if (rest.length < 2 || !rest[0]) {
         console.error("usage: telegram reply <chat> <message>");
         process.exit(1);
       }
       await reply(rest[0], rest.slice(1).join(" "));
       break;
 
+    case "send-file":
+      if (rest.length < 2 || !rest[0] || !rest[1]) {
+        console.error("usage: telegram send-file <chat> <path> [caption]");
+        process.exit(1);
+      }
+      await sendFile(rest[0], rest[1], rest.slice(2).join(" ") || undefined);
+      break;
+
+    case "download":
+      if (rest.length < 2 || !rest[0] || !rest[1]) {
+        console.error("usage: telegram download <chat> <message-id> [output-path]");
+        process.exit(1);
+      }
+      await downloadMedia(rest[0], Number.parseInt(rest[1]), rest[2]);
+      break;
+
     case "login":
       await login();
       break;
 
+    case "config":
+      await config(rest[0], rest[1], rest[2]);
+      break;
+
     case "help":
       console.log(HELP);
       break;

package/src/client/telegram.ts

@@ -3,6 +3,7 @@ import { StringSession } from "telegram/sessions";
 import { Logger } from "telegram/extensions/Logger";
 import type { LogLevel } from "telegram/extensions/Logger";
 import { loadSession, saveSession } from "../session/storage";
+import { getApiCredentials } from "../config/manager";
 
 let verbose = false;
 
@@ -11,25 +12,38 @@ export function setVerbose(v: boolean) {
 }
 
 class SilentLogger extends Logger {
-  log(_level: LogLevel, _message: string, _color: string): void {
+  override log(_level: LogLevel, _message: string, _color: string): void {
     if (verbose) {
       super.log(_level, _message, _color);
     }
   }
 }
 
-const API_ID = Number(process.env.TELEGRAM_APP_ID);
-const API_HASH = process.env.TELEGRAM_APP_HASH ?? "";
-
 let client: TelegramClient | null = null;
+let customSessionPath: string | undefined;
+
+export function setSessionPath(path: string) {
+  customSessionPath = path;
+}
 
 export async function getClient(): Promise<TelegramClient> {
   if (client) return client;
 
-  const sessionStr = loadSession();
+  const creds = getApiCredentials();
+  if (!creds) {
+    throw new Error(
+      "telegram API credentials not found.\n" +
+      "get them from: https://my.telegram.org/apps\n" +
+      "then run: telegram config set appId <id>\n" +
+      "         telegram config set appHash <hash>\n" +
+      "or set env vars: TELEGRAM_APP_ID, TELEGRAM_APP_HASH"
+    );
+  }
+
+  const sessionStr = loadSession(customSessionPath);
   const session = new StringSession(sessionStr);
 
-  client = new TelegramClient(session, API_ID, API_HASH, {
+  client = new TelegramClient(session, creds.appId, creds.appHash, {
     connectionRetries: 5,
     baseLogger: new SilentLogger(),
   });
@@ -58,7 +72,7 @@ export async function login(callbacks: {
   });
 
   const sessionStr = c.session.save() as unknown as string;
-  saveSession(sessionStr);
+  saveSession(sessionStr, customSessionPath);
   console.log("session saved!");
 }
 
@@ -70,6 +84,34 @@ export async function sendMessage(
   return c.sendMessage(username, { message });
 }
 
+export async function sendFile(
+  username: string,
+  filePath: string,
+  caption?: string
+): Promise<Api.Message> {
+  const c = await getClient();
+  return c.sendFile(username, {
+    file: filePath,
+    caption: caption,
+  });
+}
+
+export async function downloadMedia(
+  message: Api.Message,
+  outputPath?: string
+): Promise<string | undefined> {
+  const c = await getClient();
+  if (!message.media) {
+    return undefined;
+  }
+  
+  const buffer = await c.downloadMedia(message, {
+    outputFile: outputPath,
+  });
+  
+  return buffer as string | undefined;
+}
+
 export async function getMessages(
   username: string,
   limit = 10

package/src/config/manager.ts

@@ -0,0 +1,95 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CONFIG_DIR = join(homedir(), ".supertelegram");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+const SESSION_FILE = join(CONFIG_DIR, "session.txt");
+
+export interface Config {
+  appId?: string;
+  appHash?: string;
+}
+
+function ensureConfigDir() {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+export function getConfig(): Config {
+  ensureConfigDir();
+  
+  if (!existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  
+  try {
+    const content = readFileSync(CONFIG_FILE, "utf-8");
+    return JSON.parse(content);
+  } catch (err) {
+    console.error("failed to read config:", err);
+    return {};
+  }
+}
+
+export function setConfig(key: string, value: string) {
+  ensureConfigDir();
+  
+  const config = getConfig();
+  config[key as keyof Config] = value;
+  
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+export function getSessionPath(customPath?: string): string {
+  // precedence:
+  // 1. custom path from flag
+  // 2. TELEGRAM_SESSION env var
+  // 3. global ~/.supertelegram/session.txt
+  // 4. local ./session.txt (backwards compat)
+  
+  if (customPath) {
+    return customPath;
+  }
+  
+  if (process.env.TELEGRAM_SESSION) {
+    return process.env.TELEGRAM_SESSION;
+  }
+  
+  // check if local session.txt exists (backwards compat)
+  if (existsSync("./session.txt")) {
+    return "./session.txt";
+  }
+  
+  return SESSION_FILE;
+}
+
+export function getApiCredentials(): { appId: number; appHash: string } | null {
+  // precedence:
+  // 1. env vars
+  // 2. global config
+  // 3. local .env (handled by process.env already)
+  
+  const envAppId = process.env.TELEGRAM_APP_ID;
+  const envAppHash = process.env.TELEGRAM_APP_HASH;
+  
+  if (envAppId && envAppHash) {
+    return {
+      appId: Number.parseInt(envAppId),
+      appHash: envAppHash,
+    };
+  }
+  
+  const config = getConfig();
+  if (config.appId && config.appHash) {
+    return {
+      appId: Number.parseInt(config.appId),
+      appHash: config.appHash,
+    };
+  }
+  
+  return null;
+}
+
+export { CONFIG_DIR, CONFIG_FILE, SESSION_FILE };

package/src/session/storage.ts

@@ -1,14 +1,24 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { getSessionPath } from "../config/manager";
 
-const SESSION_FILE = "./session.txt";
-
-export function loadSession(): string {
-  if (existsSync(SESSION_FILE)) {
-    return readFileSync(SESSION_FILE, "utf-8").trim();
+export function loadSession(customPath?: string): string {
+  const sessionFile = getSessionPath(customPath);
+  
+  if (existsSync(sessionFile)) {
+    return readFileSync(sessionFile, "utf-8").trim();
   }
   return "";
 }
 
-export function saveSession(session: string): void {
-  writeFileSync(SESSION_FILE, session, "utf-8");
+export function saveSession(session: string, customPath?: string): void {
+  const sessionFile = getSessionPath(customPath);
+  
+  // ensure directory exists
+  const dir = dirname(sessionFile);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  
+  writeFileSync(sessionFile, session, "utf-8");
 }