supertelegram 0.3.2 → 0.5.0

package/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: publish
+
+# publishes to npm when you push a version tag (e.g. v0.5.0) or cut a GitHub release.
+# tag the current version with:  git tag v$(node -p "require('./package.json').version") && git push --tags
+# auth is via npm OIDC trusted publishing (no NPM_TOKEN) — configure a trusted
+# publisher for this package on npmjs.com pointing at this repo + workflow.
+
+on:
+  push:
+    tags:
+      - "v*"
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # enables npm provenance
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: install deps
+        run: bun install --frozen-lockfile
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+
+      # OIDC trusted publishing needs a recent npm (node 24 ships one, but pin latest)
+      - name: upgrade npm
+        run: npm install -g npm@latest
+
+      - name: guard — tag matches package.json version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          PKG_VERSION="v$(node -p "require('./package.json').version")"
+          if [ "$PKG_VERSION" != "${GITHUB_REF_NAME}" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} does not match package.json ($PKG_VERSION)"
+            exit 1
+          fi
+
+      # no NODE_AUTH_TOKEN: npm authenticates via OIDC (id-token: write above)
+      - name: publish
+        run: npm publish --access public --provenance

package/PUBLISHING.md

@@ -1,6 +1,23 @@
 # publishing guide
 
-## setup
+## automated (github actions) — preferred
+
+CI publishes to npm on every version tag. auth is via **OIDC trusted
+publishing** — no `NPM_TOKEN` secret. one-time setup: on npmjs.com, open the
+package → Settings → Trusted Publishing, and add a GitHub Actions publisher
+pointing at `caffeinum/supertelegram`, workflow `publish.yml`.
+
+then to release:
+```bash
+# bump version in package.json first, commit, then:
+git tag "v$(node -p "require('./package.json').version")"
+git push --tags
+```
+the `.github/workflows/publish.yml` workflow checks the tag matches
+package.json, installs, and runs `npm publish --access public --provenance`.
+you can also trigger it manually from the Actions tab (workflow_dispatch).
+
+## manual setup
 
 1. login to npm:
 ```bash

package/README.md

@@ -32,9 +32,11 @@ that's it! now you're ready to use telegram from the cli.
 ### messages
 
 ```bash
-# send a message
+# send a message — chat can be @username, a numeric id, or a name
 telegram send @username "hello there"
-telegram send "me" "note to self"  # use "me" for saved messages
+telegram send 7069934904 "hey"      # by id (for chats with no username)
+telegram send "Ben YC" "hello"      # by name (partial, case-insensitive)
+telegram send "me" "note to self"   # use "me" for saved messages
 
 # read messages (shows [photo], [video], [file] indicators)
 telegram read @username 10
@@ -45,7 +47,7 @@ telegram reply "John" "hey back!"
 # get unread messages (json output with media info)
 telegram unread 20
 
-# list dialogs
+# list dialogs (shows @username and [id: ...] for each chat)
 telegram dialogs 10
 ```
 
@@ -76,15 +78,42 @@ telegram config set appHash "abc123..."
 - `--help` - show help
 - `--version` - show version
 
+### multiple accounts
+
+log in to as many accounts as you want, each stored under a name, and switch
+between them:
+
+```bash
+# log into named accounts (prompts phone/code the first time)
+telegram login personal
+telegram login work
+
+# see them (* marks the active one)
+telegram accounts
+# * work — @yourworkhandle
+#   personal — @yourhandle
+
+# switch the active account (all later commands use it)
+telegram switch personal
+telegram whoami            # personal — @yourhandle
+
+# or run a single command as another account without switching
+telegram -a work send @boss "on it"
+
+# remove an account
+telegram logout work
+```
+
+sessions live in `~/.supertelegram/accounts/<name>.txt`; the active account is
+tracked in `~/.supertelegram/accounts.json`. API credentials (appId/appHash)
+are shared across accounts. upgrading from an older version? your existing
+login is migrated automatically into an account named `default`.
+
 ### advanced
 
-**multi-account / custom session location:**
+**custom session location (one-off / scripting):**
 ```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:**
@@ -93,9 +122,11 @@ telegram send @friend "hey" --session ./custom.txt
 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)
+1. `--account <name>` flag
+2. `TELEGRAM_SESSION` env var
+3. active account (`~/.supertelegram/accounts/<name>.txt`)
+4. `./session.txt` (backwards compat)
+5. `~/.supertelegram/session.txt` (legacy default)
 
 ## development
 

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "supertelegram",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "telegram cli for humans and bots",
   "module": "index.ts",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caffeinum/supertelegram.git"
+  },
+  "homepage": "https://github.com/caffeinum/supertelegram#readme",
+  "bugs": {
+    "url": "https://github.com/caffeinum/supertelegram/issues"
+  },
   "bin": {
     "telegram": "src/cli/run.ts"
   },

package/src/cli/commands.ts

@@ -11,6 +11,15 @@ import {
 } from "../client/telegram";
 import { askPhoneNumber, askPhoneCode, askPassword, askAppId, askAppHash } from "./prompts";
 import { getApiCredentials, setConfig } from "../config/manager";
+import {
+  listAccounts,
+  setCurrentAccount,
+  registerAccount,
+  removeAccount,
+  getCurrentAccount,
+  accountSessionPath,
+} from "../config/accounts";
+import { setSessionPath } from "../client/telegram";
 import { Api } from "telegram";
 
 export async function send(username: string, message: string) {
@@ -71,8 +80,16 @@ export async function dialogs(limit = 10) {
 
   const dialogList = await getDialogs(limit);
   for (const dialog of dialogList) {
-    console.log(`- ${dialog.title}`);
+    const entity = dialog.entity;
+    const username =
+      entity && "username" in entity && entity.username
+        ? ` @${entity.username}`
+        : "";
+    const id = dialog.id?.toString() ?? entity?.id?.toString() ?? "?";
+    const unread = dialog.unreadCount > 0 ? ` (${dialog.unreadCount} unread)` : "";
+    console.log(`- ${dialog.title}${username} [id: ${id}]${unread}`);
   }
+  console.log("\nsend with: telegram send <@username|id> \"your message\"");
   await disconnect();
 }
 
@@ -152,37 +169,118 @@ export async function reply(chatName: string, message: string) {
   await disconnect();
 }
 
-export async function login() {
-  // check if API credentials are configured
+export async function login(accountName?: string) {
+  const name = accountName || getCurrentAccount() || "default";
+  // isolate this login to the named account's own session file
+  setSessionPath(accountSessionPath(name));
+
+  // check if API credentials are configured (shared across accounts)
   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!");
-    await disconnect();
-    return;
+  if (!loggedIn) {
+    console.log(`starting login for account "${name}"...`);
+    await telegramLogin({
+      phoneNumber: askPhoneNumber,
+      phoneCode: askPhoneCode,
+      password: askPassword,
+    });
+  } else {
+    console.log(`account "${name}" already has a session, refreshing details...`);
   }
 
-  console.log("starting login...");
-  await telegramLogin({
-    phoneNumber: askPhoneNumber,
-    phoneCode: askPhoneCode,
-    password: askPassword,
+  // capture identity + register (and make current)
+  const client = await getClient();
+  const me = await client.getMe();
+  const fullName = [me.firstName, me.lastName].filter(Boolean).join(" ");
+  registerAccount(name, {
+    username: me.username ?? undefined,
+    userId: me.id?.toString(),
+    name: fullName || undefined,
   });
 
-  console.log("login complete!");
+  const label = me.username ? `@${me.username}` : fullName || name;
+  console.log(`logged in as ${label} — account "${name}" is now active`);
   await disconnect();
 }
 
+export async function accounts() {
+  const list = listAccounts();
+  if (list.length === 0) {
+    console.log("no accounts yet. run: telegram login <name>");
+    return;
+  }
+  for (const { name, meta, current } of list) {
+    const marker = current ? "*" : " ";
+    const who = meta.username
+      ? `@${meta.username}`
+      : meta.name || (meta.userId ? `id ${meta.userId}` : "");
+    console.log(`${marker} ${name}${who ? ` — ${who}` : ""}`);
+  }
+  console.log("\nswitch with: telegram switch <name>");
+}
+
+export async function switchAccount(name?: string) {
+  if (!name) {
+    console.error("usage: telegram switch <name>");
+    console.error("see accounts with: telegram accounts");
+    process.exit(1);
+  }
+  setCurrentAccount(name);
+  console.log(`switched to account "${name}"`);
+}
+
+export async function logout(name?: string) {
+  const target = name || getCurrentAccount();
+  if (!target) {
+    console.error("no account to log out. see: telegram accounts");
+    process.exit(1);
+  }
+  removeAccount(target);
+  const now = getCurrentAccount();
+  console.log(
+    `logged out of "${target}"` + (now ? `. active account is now "${now}"` : ". no accounts left")
+  );
+}
+
+export async function whoami() {
+  const current = getCurrentAccount();
+  if (!current) {
+    console.log("not logged in. run: telegram login");
+    return;
+  }
+
+  let meta = listAccounts().find((a) => a.name === current)?.meta;
+
+  // backfill identity for accounts migrated without metadata
+  if (meta && !meta.username && !meta.name && (await isLoggedIn())) {
+    const client = await getClient();
+    const me = await client.getMe();
+    const fullName = [me.firstName, me.lastName].filter(Boolean).join(" ");
+    meta = {
+      username: me.username ?? undefined,
+      userId: me.id?.toString(),
+      name: fullName || undefined,
+    };
+    registerAccount(current, meta, false);
+    await disconnect();
+  }
+
+  const who = meta?.username
+    ? `@${meta.username}`
+    : meta?.name || (meta?.userId ? `id ${meta.userId}` : "unknown");
+  console.log(`${current} — ${who}`);
+}
+
 export async function config(action?: string, key?: string, value?: string) {
   if (action === "set" && key && value) {
     setConfig(key, value);

package/src/cli/run.ts

@@ -1,8 +1,10 @@
 #!/usr/bin/env bun
-import { send, read, dialogs, unread, reply, login, config, sendFile, downloadMedia } from "./commands";
+import { send, read, dialogs, unread, reply, login, config, sendFile, downloadMedia, accounts, switchAccount, logout, whoami } from "./commands";
 import { setVerbose, setSessionPath } from "../client/telegram";
+import { migrateLegacyIfNeeded, accountSessionPath } from "../config/accounts";
+import pkg from "../../package.json";
 
-const VERSION = "0.1.0";
+const VERSION = pkg.version;
 const NAME = "telegram";
 
 const HELP = `
@@ -12,17 +14,22 @@ usage:
   ${NAME} <command> [options]
 
 commands:
-  send <chat> <message>      send a message to a chat
+  send <chat> <message>      send a message (chat = @username, id, or name)
   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
+  login [name]               authenticate with telegram (into a named account)
+  accounts                   list logged-in accounts (* = current)
+  switch <name>              switch the active account
+  whoami                     show the active account
+  logout [name]              remove an account (default: current)
   config set <key> <val>     set API credentials (appId, appHash)
 
 options:
+  -a, --account <name>     run this command as a specific account
   -v, --verbose            show debug logs
   -h, --help               show this help
   --version                show version
@@ -35,6 +42,9 @@ examples:
   ${NAME} reply "John" "hey!"
   ${NAME} unread
   ${NAME} dialogs 20
+  ${NAME} login work            # log into a second account named "work"
+  ${NAME} switch work           # make it active
+  ${NAME} -a personal unread    # run one command as another account
 `.trim();
 
 const rawArgs = process.argv.slice(2);
@@ -51,6 +61,15 @@ if (rawArgs.includes("--version")) {
 }
 
 const verbose = rawArgs.includes("--verbose") || rawArgs.includes("-v");
+
+// pull out --account/-a <name> before positional parsing
+let accountFlag: string | undefined;
+const accIdx = rawArgs.findIndex((a) => a === "--account" || a === "-a");
+if (accIdx !== -1) {
+  accountFlag = rawArgs[accIdx + 1];
+  rawArgs.splice(accIdx, accountFlag ? 2 : 1);
+}
+
 const args = rawArgs.filter((a) => !a.startsWith("-"));
 const [command, ...rest] = args;
 
@@ -58,6 +77,14 @@ if (verbose) {
   setVerbose(true);
 }
 
+// fold a pre-multi-account session.txt into account "default" (one-time, no-op after)
+migrateLegacyIfNeeded();
+
+// an explicit --account pins this invocation to that account's session
+if (accountFlag) {
+  setSessionPath(accountSessionPath(accountFlag));
+}
+
 async function main() {
   switch (command) {
     case "send":
@@ -109,7 +136,23 @@ async function main() {
       break;
 
     case "login":
-      await login();
+      await login(rest[0]);
+      break;
+
+    case "accounts":
+      await accounts();
+      break;
+
+    case "switch":
+      await switchAccount(rest[0]);
+      break;
+
+    case "whoami":
+      await whoami();
+      break;
+
+    case "logout":
+      await logout(rest[0]);
       break;
 
     case "config":

package/src/client/telegram.ts

@@ -76,12 +76,60 @@ export async function login(callbacks: {
   console.log("session saved!");
 }
 
+// a chat can be addressed by @username, "me", phone (+123), t.me link,
+// or a numeric id copied from `telegram dialogs`. usernames/links resolve
+// natively; numeric ids and bare names need the dialog entity cache, so we
+// look them up here.
+export async function resolveEntity(
+  identifier: string
+): Promise<string | Api.TypeEntityLike> {
+  const c = await getClient();
+  const id = identifier.trim();
+
+  // things gramjs resolves on its own
+  if (
+    id === "me" ||
+    id.startsWith("@") ||
+    id.startsWith("+") ||
+    id.startsWith("http")
+  ) {
+    return id;
+  }
+
+  // numeric id (users positive, chats/channels may be negative)
+  if (/^-?\d+$/.test(id)) {
+    try {
+      // fast path: entity already in the session cache
+      return await c.getInputEntity(id);
+    } catch {
+      // slow path: fetch dialogs to populate + match the entity
+      const match = (await c.getDialogs({ limit: 200 })).find(
+        (d) => d.id?.toString() === id || d.entity?.id?.toString() === id
+      );
+      if (match?.entity) return match.entity;
+      throw new Error(
+        `chat with id ${id} not found in your dialogs. run: telegram dialogs 200`
+      );
+    }
+  }
+
+  // bare name: partial, case-insensitive match against dialog titles
+  const match = (await c.getDialogs({ limit: 200 })).find((d) =>
+    d.title?.toLowerCase().includes(id.toLowerCase())
+  );
+  if (match?.entity) return match.entity;
+
+  // let gramjs take a final shot (e.g. a username without the @)
+  return id;
+}
+
 export async function sendMessage(
   username: string,
   message: string
 ): Promise<Api.Message> {
   const c = await getClient();
-  return c.sendMessage(username, { message });
+  const entity = await resolveEntity(username);
+  return c.sendMessage(entity, { message });
 }
 
 export async function sendFile(
@@ -90,7 +138,8 @@ export async function sendFile(
   caption?: string
 ): Promise<Api.Message> {
   const c = await getClient();
-  return c.sendFile(username, {
+  const entity = await resolveEntity(username);
+  return c.sendFile(entity, {
     file: filePath,
     caption: caption,
   });
@@ -117,7 +166,8 @@ export async function getMessages(
   limit = 10
 ): Promise<Api.Message[]> {
   const c = await getClient();
-  const messages = await c.getMessages(username, { limit });
+  const entity = await resolveEntity(username);
+  const messages = await c.getMessages(entity, { limit });
   return messages as Api.Message[];
 }
 

package/src/config/accounts.ts

@@ -0,0 +1,113 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  copyFileSync,
+  rmSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// kept in sync with manager.ts; recomputed here to avoid a circular import
+const CONFIG_DIR = join(homedir(), ".supertelegram");
+const ACCOUNTS_DIR = join(CONFIG_DIR, "accounts");
+const ACCOUNTS_FILE = join(CONFIG_DIR, "accounts.json");
+const LEGACY_SESSION_FILE = join(CONFIG_DIR, "session.txt");
+
+export interface AccountMeta {
+  username?: string;
+  userId?: string;
+  name?: string;
+}
+
+export interface AccountsRegistry {
+  current?: string;
+  accounts: Record<string, AccountMeta>;
+}
+
+function readRegistry(): AccountsRegistry {
+  if (!existsSync(ACCOUNTS_FILE)) return { accounts: {} };
+  try {
+    return JSON.parse(readFileSync(ACCOUNTS_FILE, "utf-8"));
+  } catch {
+    return { accounts: {} };
+  }
+}
+
+function writeRegistry(reg: AccountsRegistry): void {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(ACCOUNTS_FILE, JSON.stringify(reg, null, 2));
+}
+
+export function accountSessionPath(name: string): string {
+  return join(ACCOUNTS_DIR, `${name}.txt`);
+}
+
+export function getCurrentAccount(): string | undefined {
+  return readRegistry().current;
+}
+
+export function listAccounts(): {
+  name: string;
+  meta: AccountMeta;
+  current: boolean;
+}[] {
+  const reg = readRegistry();
+  return Object.entries(reg.accounts).map(([name, meta]) => ({
+    name,
+    meta,
+    current: name === reg.current,
+  }));
+}
+
+export function setCurrentAccount(name: string): void {
+  const reg = readRegistry();
+  if (!reg.accounts[name]) {
+    const known = Object.keys(reg.accounts);
+    throw new Error(
+      `account "${name}" not found.` +
+        (known.length ? ` known accounts: ${known.join(", ")}` : " run: telegram login <name>")
+    );
+  }
+  reg.current = name;
+  writeRegistry(reg);
+}
+
+export function registerAccount(
+  name: string,
+  meta: AccountMeta,
+  makeCurrent = true
+): void {
+  if (!existsSync(ACCOUNTS_DIR)) mkdirSync(ACCOUNTS_DIR, { recursive: true });
+  const reg = readRegistry();
+  reg.accounts[name] = meta;
+  if (makeCurrent) reg.current = name;
+  writeRegistry(reg);
+}
+
+export function removeAccount(name: string): void {
+  const reg = readRegistry();
+  if (!reg.accounts[name]) {
+    throw new Error(`account "${name}" not found`);
+  }
+  delete reg.accounts[name];
+  if (reg.current === name) reg.current = Object.keys(reg.accounts)[0];
+  writeRegistry(reg);
+
+  const sessionFile = accountSessionPath(name);
+  if (existsSync(sessionFile)) rmSync(sessionFile);
+}
+
+// one-time migration: fold a pre-multi-account session.txt into account "default"
+// so existing installs keep their login after upgrading.
+export function migrateLegacyIfNeeded(): void {
+  const reg = readRegistry();
+  if (Object.keys(reg.accounts).length > 0) return; // already on the accounts system
+
+  if (existsSync(LEGACY_SESSION_FILE) && readFileSync(LEGACY_SESSION_FILE, "utf-8").trim()) {
+    if (!existsSync(ACCOUNTS_DIR)) mkdirSync(ACCOUNTS_DIR, { recursive: true });
+    copyFileSync(LEGACY_SESSION_FILE, accountSessionPath("default"));
+    registerAccount("default", {}, true);
+  }
+}

package/src/config/manager.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { getCurrentAccount, accountSessionPath } from "./accounts";
 
 const CONFIG_DIR = join(homedir(), ".supertelegram");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
@@ -44,24 +45,30 @@ export function setConfig(key: string, value: string) {
 
 export function getSessionPath(customPath?: string): string {
   // precedence:
-  // 1. custom path from flag
+  // 1. custom path from flag (--account resolves to one of these)
   // 2. TELEGRAM_SESSION env var
-  // 3. global ~/.supertelegram/session.txt
+  // 3. current account's session (~/.supertelegram/accounts/<name>.txt)
   // 4. local ./session.txt (backwards compat)
-  
+  // 5. global ~/.supertelegram/session.txt (legacy default)
+
   if (customPath) {
     return customPath;
   }
-  
+
   if (process.env.TELEGRAM_SESSION) {
     return process.env.TELEGRAM_SESSION;
   }
-  
+
+  const current = getCurrentAccount();
+  if (current) {
+    return accountSessionPath(current);
+  }
+
   // check if local session.txt exists (backwards compat)
   if (existsSync("./session.txt")) {
     return "./session.txt";
   }
-  
+
   return SESSION_FILE;
 }
 

package/tsconfig.json

@@ -11,6 +11,7 @@
     // Bundler mode
     "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
     "verbatimModuleSyntax": true,
     "noEmit": true,