@stage-labs/metro 0.1.0-beta.2 → 0.1.0-beta.21

package/runtime/node_modules/@metro-labs/telegram/src/media-actions.ts

@@ -0,0 +1,166 @@
+import { tg, tgForm, targetOf } from './accounts.js';
+import { emit, mintId, respond, SELF_URI } from './wire.js';
+import { appendFile } from '@metro-labs/mcp/stations/attachments';
+
+export function emitOutbound(
+  accountId: string,
+  line: string,
+  messageId: string,
+  text: string,
+  replyTo?: string,
+): void {
+  emit({
+    kind: 'outbound',
+    id: mintId(),
+    ts: new Date().toISOString(),
+    station: 'telegram',
+    line,
+    from: SELF_URI,
+    to: line,
+    message_id: messageId,
+    text,
+    reply_to: replyTo,
+    ...(replyTo ? { event: { type: 'reply', replyTo } } : {}),
+    account: accountId,
+    payload: { account: accountId },
+  });
+}
+
+export function finishSend(
+  id: string,
+  accountId: string,
+  line: string,
+  messageId: string,
+  label: string,
+  replyTo?: string,
+  extra?: Record<string, unknown>,
+): void {
+  emitOutbound(accountId, line, messageId, label, replyTo);
+  respond(id, {
+    result: { messageId, account: accountId, ...extra },
+  });
+}
+
+interface MediaArgs {
+  line: string;
+  path: string;
+  caption?: string;
+  replyTo?: string;
+  parseMode?: string;
+  account?: string;
+  name?: string;
+}
+
+export async function sendMedia(
+  method: string,
+  fieldName: string,
+  args: Record<string, unknown>,
+): Promise<{ accountId: string; message_id: number }> {
+  const {
+    line,
+    path,
+    caption,
+    replyTo,
+    parseMode,
+    account,
+    name: fileName,
+  } = args as unknown as MediaArgs;
+  const { accountId, chatId, topicId } = targetOf(line, account);
+  const form = new FormData();
+  form.append('chat_id', String(chatId));
+  if (topicId !== undefined) form.append('message_thread_id', String(topicId));
+  if (caption) form.append('caption', caption);
+  if (parseMode) form.append('parse_mode', parseMode);
+  if (replyTo)
+    form.append(
+      'reply_parameters',
+      JSON.stringify({ message_id: Number(replyTo) }),
+    );
+  const name = fileName ?? path.split('/').pop() ?? fieldName;
+  await appendFile(form, fieldName, path, name);
+  const r = await tgForm<{ message_id: number }>(accountId, method, form);
+  return { accountId, message_id: r.message_id };
+}
+
+export async function media(
+  id: string,
+  method: string,
+  field: string,
+  label: string,
+  args: Record<string, unknown>,
+): Promise<void> {
+  const { accountId, message_id } = await sendMedia(method, field, args);
+  const line = (args as { line: string }).line;
+  finishSend(
+    id,
+    accountId,
+    line,
+    String(message_id),
+    label,
+    args.replyTo as string | undefined,
+  );
+}
+
+export const MEDIA_METHOD_FIELD: Record<
+  string,
+  { method: string; field: string }
+> = {
+  image: { method: 'sendPhoto', field: 'photo' },
+  voice: { method: 'sendVoice', field: 'voice' },
+  audio: { method: 'sendAudio', field: 'audio' },
+  video: { method: 'sendVideo', field: 'video' },
+  document: { method: 'sendDocument', field: 'document' },
+};
+
+export async function sendDice(
+  id: string,
+  args: Record<string, unknown>,
+): Promise<void> {
+  const {
+    line,
+    emoji = '\U0001F3B2',
+    account,
+  } = args as { line: string; emoji?: string; account?: string };
+  const { accountId, chatId, topicId } = targetOf(line, account);
+  const body: Record<string, unknown> = { chat_id: chatId, emoji };
+  if (topicId !== undefined) body.message_thread_id = topicId;
+  const r = await tg<{ message_id: number; dice?: { value: number } }>(
+    accountId,
+    'sendDice',
+    body,
+  );
+  finishSend(
+    id,
+    accountId,
+    line,
+    String(r.message_id),
+    `[dice ${emoji} = ${r.dice?.value ?? '?'}]`,
+    undefined,
+    { value: r.dice?.value },
+  );
+}
+
+export async function sendLocation(
+  id: string,
+  args: Record<string, unknown>,
+): Promise<void> {
+  const { line, latitude, longitude, account } = args as {
+    line: string;
+    latitude: number;
+    longitude: number;
+    account?: string;
+  };
+  const { accountId, chatId } = targetOf(line, account);
+  const r = await tg<{ message_id: number }>(accountId, 'sendLocation', {
+    chat_id: chatId,
+    latitude,
+    longitude,
+  });
+  finishSend(
+    id,
+    accountId,
+    line,
+    String(r.message_id),
+    `[location: ${latitude}, ${longitude}]`,
+  );
+}

package/runtime/node_modules/@metro-labs/telegram/src/members.ts

@@ -0,0 +1,47 @@
+import type { MemberList, MetroMember } from '@metro-labs/mcp/stations/types';
+
+export interface TgUser {
+  id: number;
+  username?: string;
+  first_name?: string;
+  last_name?: string;
+  is_bot?: boolean;
+}
+
+export interface TgChatMember {
+  user: TgUser;
+  status: string;
+}
+
+export function mapTgMember(m: TgChatMember): MetroMember {
+  const u = m.user;
+  const member: MetroMember = { id: String(u.id) };
+  if (u.username) member.name = u.username;
+  const display = [u.first_name, u.last_name].filter(Boolean).join(' ');
+  if (display) member.display_name = display;
+  member.is_admin = m.status === 'creator' || m.status === 'administrator';
+  member.is_bot = Boolean(u.is_bot);
+  return member;
+}
+
+const BOT_LIMIT_REASON =
+  'Telegram Bot API cannot enumerate full membership; returning administrators only.';
+
+export function adminMemberList(
+  admins: TgChatMember[],
+  total: number | null,
+): MemberList {
+  return {
+    members: admins.map(mapTgMember),
+    capability: {
+      supported: true,
+      complete: false,
+      reason: BOT_LIMIT_REASON,
+      ...(total != null ? { total } : {}),
+    },
+  };
+}
+
+export function inaccessibleMemberList(reason: string): MemberList {
+  return { members: [], capability: { supported: false, complete: false, reason } };
+}

package/runtime/node_modules/@metro-labs/telegram/src/station.ts

@@ -0,0 +1,17 @@
+import type { Station, Verb } from '@metro-labs/mcp/stations/types';
+
+export const telegramStation: Station = {
+  name: 'telegram',
+  hasAccounts: true,
+  hasTrain: true,
+  messageVerbs: new Set<Verb>([
+    'send',
+    'reply',
+    'react',
+    'unreact',
+    'edit',
+    'delete',
+  ]),
+  attachmentMode: 'canonical',
+  tools: [],
+};

package/runtime/node_modules/@metro-labs/telegram/src/types.ts

@@ -0,0 +1,48 @@
+export interface TgMsg {
+  message_id: number;
+  date: number;
+  chat: { id: number; type: string; title?: string; first_name?: string };
+  from?: {
+    id: number;
+    username?: string;
+    first_name?: string;
+    is_bot?: boolean;
+  };
+  text?: string;
+  caption?: string;
+  message_thread_id?: number;
+  is_topic_message?: boolean;
+  photo?: { file_id: string; file_size?: number }[];
+  document?: { file_name?: string; file_id?: string; mime_type?: string };
+  voice?: { file_id?: string; duration?: number; mime_type?: string };
+  audio?: { file_id?: string; file_name?: string; mime_type?: string };
+  video?: { file_id?: string; file_name?: string; mime_type?: string };
+  animation?: { file_id?: string; file_name?: string; mime_type?: string };
+  sticker?: { file_id?: string; emoji?: string; set_name?: string };
+  location?: { latitude: number; longitude: number };
+  dice?: { emoji: string; value: number };
+}
+
+export interface TgReaction {
+  chat: { id: number; type: string };
+  message_id: number;
+  user?: {
+    id: number;
+    username?: string;
+    first_name?: string;
+    is_bot?: boolean;
+  };
+  date: number;
+  old_reaction: { type: string; emoji?: string }[];
+  new_reaction: { type: string; emoji?: string }[];
+}
+
+export interface TgReactionCount {
+  chat: { id: number; type: string };
+  message_id: number;
+  date: number;
+  reactions: {
+    type: { type: string; emoji?: string };
+    total_count: number;
+  }[];
+}

package/runtime/node_modules/@metro-labs/telegram/src/verify.ts

@@ -0,0 +1,38 @@
+export class TelegramTokenError extends Error {}
+
+export interface TelegramBotIdentity {
+  botId: number;
+  username: string;
+}
+
+const API = 'https://api.telegram.org';
+const TIMEOUT_MS = 10_000;
+
+interface GetMe {
+  ok?: unknown;
+  result?: { id?: unknown; username?: unknown; is_bot?: unknown };
+}
+
+export async function verifyTelegramBotToken(
+  token: string,
+): Promise<TelegramBotIdentity> {
+  let res: Response;
+  try {
+    res = await fetch(`${API}/bot${token}/getMe`, {
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch {
+    throw new TelegramTokenError(
+      'could not reach the Telegram API to check that bot token',
+    );
+  }
+  const body = (await res.json().catch(() => null)) as GetMe | null;
+  const me = body?.ok === true ? body.result : undefined;
+  if (!me) throw new TelegramTokenError('Telegram rejected that bot token');
+  if (typeof me.id !== 'number' || me.is_bot !== true)
+    throw new TelegramTokenError('that token does not belong to a Telegram bot');
+  return {
+    botId: me.id,
+    username: typeof me.username === 'string' ? me.username : '',
+  };
+}

package/runtime/node_modules/@metro-labs/telegram/src/wire.ts

@@ -0,0 +1,3 @@
+export { emit, respond, mintId } from '@metro-labs/mcp/stations/station-runtime';
+
+export const SELF_URI = process.env.METRO_SELF_URI ?? '';

package/runtime/node_modules/@metro-labs/telegram-user/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@metro-labs/telegram-user",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/station.ts",
+    "./train": "./src/index.ts",
+    "./login": "./src/login.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit && bun test test/"
+  },
+  "dependencies": {
+    "@metro-labs/mcp": "workspace:*",
+    "@mtcute/bun": "0.30.1"
+  },
+  "devDependencies": {
+    "@stage-labs/config": "0.1.0-beta.2",
+    "@types/qrcode-terminal": "^0.12.2",
+    "eslint": "^10.3.0",
+    "knip": "^6.15.0",
+    "madge": "^8.0.0",
+    "qrcode-terminal": "^0.12.0",
+    "typescript": "^5"
+  }
+}

package/runtime/node_modules/@metro-labs/telegram-user/src/accounts.ts

@@ -0,0 +1,81 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  makeAccountStore,
+  resolveAccountId,
+  type Die,
+} from '@metro-labs/mcp/stations/account-store';
+import type { UserAccount } from './types.js';
+
+const ACCOUNTS_FILE =
+  process.env.TELEGRAM_USER_ACCOUNTS_FILE ??
+  join(homedir(), '.metro', 'telegram-user-accounts.json');
+
+const isSignedInt = (s: string): boolean => /^-?\d+$/.test(s);
+const isTopic = (s: string): boolean => /^\d+$/.test(s);
+
+function validateAccount(a: UserAccount, seen: Set<string>, die: Die): void {
+  if (!a.id) die('account missing id');
+  if (!a.session || typeof a.session !== 'string')
+    die(`account '${a.id}' missing session`);
+  if (!Number.isInteger(a.apiId) || (a.apiId ?? 0) <= 0)
+    die(`account '${a.id}' missing apiId`);
+  if (!a.apiHash || typeof a.apiHash !== 'string')
+    die(`account '${a.id}' missing apiHash`);
+  if (seen.has(a.id)) die(`duplicate account id '${a.id}'`);
+  seen.add(a.id);
+}
+
+export const { loadAccounts } = makeAccountStore<UserAccount>({
+  prefix: 'telegram-user',
+  file: ACCOUNTS_FILE,
+  allowlistEnv: ['TELEGRAM_USER_ONLY_ACCOUNTS', 'TELEGRAM_USER_ACCOUNTS'],
+  validate(raw, die) {
+    const seen = new Set<string>();
+    for (const a of raw) validateAccount(a, seen, die);
+  },
+});
+
+export const accounts = new Map<string, UserAccount>();
+
+export function accountFor(args: { account?: string; line?: string }): string {
+  return resolveAccountId(accounts, args, (line) => targetOf(line)?.accountId);
+}
+
+export function lineOf(
+  accountId: string,
+  chatId: number | string,
+  topicId?: number,
+): string {
+  const tail = topicId !== undefined ? `${chatId}/${topicId}` : `${chatId}`;
+  return `metro://telegram-user/${accountId}/${tail}`;
+}
+
+interface Target {
+  accountId: string;
+  chatId: number;
+  topicId?: number;
+}
+
+function splitScoped(path: string[]): { accountId: string; rest: string[] } {
+  const first = path[0];
+  if (path.length >= 2 && first !== undefined && !isSignedInt(first))
+    return { accountId: first, rest: path.slice(1) };
+  return { accountId: 'default', rest: path };
+}
+
+export function targetOf(line: string): Target | undefined {
+  const prefix = 'metro://telegram-user/';
+  if (!line.startsWith(prefix)) return undefined;
+  const path = line.slice(prefix.length).split('/').filter(Boolean);
+  const { accountId, rest } = splitScoped(path);
+  const [chatId, topicId] = rest;
+  if (rest.length < 1 || rest.length > 2 || chatId === undefined) return undefined;
+  if (!isSignedInt(chatId)) return undefined;
+  if (topicId !== undefined && !isTopic(topicId)) return undefined;
+  return {
+    accountId,
+    chatId: Number(chatId),
+    ...(topicId !== undefined ? { topicId: Number(topicId) } : {}),
+  };
+}

package/runtime/node_modules/@metro-labs/telegram-user/src/actions.ts

@@ -0,0 +1,254 @@
+import { TrainError } from '@metro-labs/mcp/train-error';
+import { errMsg } from '@metro-labs/mcp/log';
+import {
+  makeStation,
+  respond,
+  type CallMsg,
+  type StationHandler,
+} from '@metro-labs/mcp/stations/station-runtime';
+import { accountFor, accounts, targetOf } from './accounts.js';
+import type { UserClient } from './client.js';
+import { normalizeTelegramUser } from './normalize.js';
+import {
+  sendAttachments,
+  type CanonicalAttachment,
+} from './media-actions.js';
+import { clampLimit, shapeHistory } from './history.js';
+import { fetchMembers, isRestricted, restrictedMemberList } from './members.js';
+import {
+  groupAddMembers,
+  groupCreate,
+  groupInviteLink,
+  groupRemoveMembers,
+} from './group.js';
+
+type Args = Record<string, unknown>;
+
+interface Resolved {
+  accountId: string;
+  client: UserClient;
+  chatId: number;
+  topicId?: number;
+}
+
+type ClientFor = (accountId: string) => UserClient;
+
+function str(v: unknown): string | undefined {
+  return typeof v === 'string' ? v : undefined;
+}
+
+function lineOfArgs(args: Args): string {
+  const line = str(args.line);
+  if (!line) throw new TrainError('bad_request', 'missing line');
+  return line;
+}
+
+function resolve(args: Args, clientFor: ClientFor): Resolved {
+  const line = lineOfArgs(args);
+  const target = targetOf(line);
+  if (!target) throw new TrainError('bad_request', `bad line '${line}'`);
+  const accountId = accountFor({ account: str(args.account), line });
+  return {
+    accountId,
+    client: clientFor(accountId),
+    chatId: target.chatId,
+    ...(target.topicId !== undefined ? { topicId: target.topicId } : {}),
+  };
+}
+
+async function guard<T>(run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (e) {
+    const msg = errMsg(e);
+    if (/FLOOD_WAIT|SLOWMODE_WAIT/i.test(msg))
+      throw new TrainError('rate_limited', msg);
+    throw new TrainError('telegram_user_call', msg);
+  }
+}
+
+function attachmentsOf(args: Args): CanonicalAttachment[] {
+  const raw = args.attachments;
+  return Array.isArray(raw) ? (raw as CanonicalAttachment[]) : [];
+}
+
+function makeSend(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const { accountId, client, chatId, topicId } = resolve(args, clientFor);
+    const text = str(args.text) ?? '';
+    const replyTo = str(args.replyTo);
+    const explicitReplyTo = replyTo ? Number(replyTo) : undefined;
+    const replyParam = explicitReplyTo ?? topicId;
+    const attachments = attachmentsOf(args);
+    if (attachments.length) {
+      const sent = await guard(() =>
+        sendAttachments({ client, chatId, replyTo: replyParam }, attachments, text),
+      );
+      respond(id, {
+        result: {
+          messageId: String(sent.message.id),
+          account: accountId,
+          attachments: sent.delivered,
+        },
+      });
+      return;
+    }
+    const peer = await guard(() => client.tg.resolvePeer(chatId));
+    const sent = await guard(() =>
+      client.tg.sendText(
+        peer,
+        text,
+        replyParam !== undefined ? { replyTo: replyParam } : undefined,
+      ),
+    );
+    respond(id, {
+      result: { messageId: String(sent.id), account: accountId },
+    });
+  };
+}
+
+function makeReact(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const { accountId, client, chatId } = resolve(args, clientFor);
+    const message = Number(str(args.messageId));
+    const raw = str(args.emoji);
+    const emoji = raw === undefined || raw === '' ? null : raw;
+    await guard(() =>
+      client.tg.sendReaction({ chatId, message, emoji }),
+    );
+    respond(id, { result: { ok: true, account: accountId } });
+  };
+}
+
+function makeEdit(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const { accountId, client, chatId } = resolve(args, clientFor);
+    const message = Number(str(args.messageId));
+    const text = str(args.text) ?? '';
+    await guard(() => client.tg.editMessage({ chatId, message, text }));
+    respond(id, { result: { ok: true, account: accountId } });
+  };
+}
+
+function makeDelete(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const { accountId, client, chatId } = resolve(args, clientFor);
+    const message = Number(str(args.messageId));
+    await guard(() =>
+      client.tg.deleteMessagesById(chatId, [message], { revoke: true }),
+    );
+    respond(id, { result: { ok: true, account: accountId } });
+  };
+}
+
+function makeRead(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const { accountId, client, chatId } = resolve(args, clientFor);
+    const limit = clampLimit(args.limit);
+    const before = str(args.before);
+    const beforeId = before ? Number(before) : undefined;
+    const offset =
+      beforeId !== undefined && Number.isFinite(beforeId)
+        ? { offset: { id: beforeId, date: 0 } }
+        : {};
+    const page = await guard(() =>
+      client.tg.getHistory(chatId, { limit, ...offset }),
+    );
+    respond(id, { result: shapeHistory(accountId, chatId, page) });
+  };
+}
+
+function makeListMembers(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const { client, chatId } = resolve(args, clientFor);
+    const limit = typeof args.limit === 'number' ? args.limit : undefined;
+    try {
+      respond(id, { result: await fetchMembers(client, chatId, limit) });
+    } catch (e) {
+      const msg = errMsg(e);
+      if (isRestricted(msg)) {
+        respond(id, { result: restrictedMemberList(msg) });
+        return;
+      }
+      throw e;
+    }
+  };
+}
+
+function makeGroupCreate(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const accountId = accountFor({ account: str(args.account) });
+    const client = clientFor(accountId);
+    respond(id, {
+      result: await guard(() => groupCreate(client, accountId, args)),
+    });
+  };
+}
+
+function makeGroupAdd(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const { client, chatId } = resolve(args, clientFor);
+    const line = lineOfArgs(args);
+    respond(id, {
+      result: await guard(() => groupAddMembers(client, chatId, line, args)),
+    });
+  };
+}
+
+function makeGroupRemove(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const { client, chatId } = resolve(args, clientFor);
+    const line = lineOfArgs(args);
+    respond(id, {
+      result: await guard(() => groupRemoveMembers(client, chatId, line, args)),
+    });
+  };
+}
+
+function makeGroupInvite(clientFor: ClientFor): StationHandler {
+  return async (id, args) => {
+    const { client, chatId } = resolve(args, clientFor);
+    const line = lineOfArgs(args);
+    respond(id, {
+      result: await guard(() => groupInviteLink(client, chatId, line)),
+    });
+  };
+}
+
+function makeAccounts(clientFor: ClientFor): StationHandler {
+  return (id) => {
+    const list = [...accounts.values()].map((a) => {
+      const me = clientFor(a.id).self();
+      const username = me?.username ?? null;
+      return {
+        id: a.id,
+        handle: username === null ? me?.phone ?? null : `@${username}`,
+        url: username === null ? null : `https://t.me/${username}`,
+        owner: a.owner ?? null,
+      };
+    });
+    respond(id, { result: { accounts: list } });
+    return Promise.resolve();
+  };
+}
+
+export function makeHandleCall(
+  clientFor: ClientFor,
+): (msg: CallMsg) => Promise<void> {
+  return makeStation({
+    handlers: {
+      accounts: makeAccounts(clientFor),
+      send: makeSend(clientFor),
+      react: makeReact(clientFor),
+      edit: makeEdit(clientFor),
+      delete: makeDelete(clientFor),
+      read: makeRead(clientFor),
+      listMembers: makeListMembers(clientFor),
+      groupCreate: makeGroupCreate(clientFor),
+      groupAddMembers: makeGroupAdd(clientFor),
+      groupRemoveMembers: makeGroupRemove(clientFor),
+      groupInviteLink: makeGroupInvite(clientFor),
+    },
+    normalize: normalizeTelegramUser,
+  });
+}