@stage-labs/metro 0.1.0-beta.7 → 0.1.0-beta.70

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

@@ -0,0 +1,261 @@
+import type {
+  GroupResult,
+  MemberOutcome,
+} from '@metro-labs/mcp/stations/types';
+import { TrainError } from '@metro-labs/mcp/train-error';
+import { errMsg } from '@metro-labs/mcp/log';
+import type { UserClient } from './client.js';
+import { lineOf } from './accounts.js';
+
+export interface MissingInvitee {
+  userId: number;
+}
+
+interface CreateGroupResponse {
+  chat: { id: number };
+  missing: MissingInvitee[];
+}
+
+interface InviteLink {
+  link: string;
+}
+
+interface TgGroup {
+  createGroup: (p: {
+    title: string;
+    users: string[];
+  }) => Promise<CreateGroupResponse>;
+  addChatMembers: (
+    chatId: number,
+    users: string[],
+    params: { forwardCount: number },
+  ) => Promise<MissingInvitee[]>;
+  kickChatMember: (p: { chatId: number; userId: string }) => Promise<unknown>;
+  exportInviteLink: (chatId: number) => Promise<InviteLink>;
+  resolvePeer: (peer: string) => Promise<{
+    userId?: number;
+    channelId?: number;
+    chatId?: number;
+  }>;
+}
+
+const tgGroup = (client: UserClient): TgGroup => {
+  const tg: unknown = client.tg;
+  return tg as TgGroup;
+};
+
+const INVITE_REASON =
+  'could not be direct-added (not a mutual contact or privacy-restricted); share the invite link';
+
+const ADD_FAILURE_CODES = [
+  'CHAT_MEMBER_ADD_FAILED',
+  'USER_PRIVACY_RESTRICTED',
+  'USER_NOT_MUTUAL_CONTACT',
+  'USER_CHANNELS_TOO_MUCH',
+  'USER_ALREADY_PARTICIPANT',
+  'USER_BLOCKED',
+  'USER_BOT',
+  'USER_KICKED',
+  'PEER_FLOOD',
+  'USERS_TOO_MUCH',
+];
+
+function isAddFailure(e: unknown): boolean {
+  const msg = errMsg(e).toUpperCase();
+  return ADD_FAILURE_CODES.some((code) => msg.includes(code));
+}
+
+const added = (id: string): MemberOutcome => ({ id, status: 'added' });
+const invited = (id: string): MemberOutcome => ({
+  id,
+  status: 'invited',
+  reason: INVITE_REASON,
+});
+
+function membersOf(args: Record<string, unknown>): string[] {
+  const raw = args.members;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((v) => typeof v === 'string' && v.length > 0) as string[];
+}
+
+async function addOne(
+  client: UserClient,
+  chatId: number,
+  member: string,
+): Promise<MemberOutcome> {
+  try {
+    const missing = await tgGroup(client).addChatMembers(chatId, [member], {
+      forwardCount: 0,
+    });
+    return missing.length ? invited(member) : added(member);
+  } catch (e) {
+    if (isAddFailure(e)) return invited(member);
+    throw e;
+  }
+}
+
+interface CreatedChat {
+  chatId: number;
+  outcomes: MemberOutcome[];
+}
+
+async function createWithAll(
+  client: UserClient,
+  title: string,
+  members: string[],
+): Promise<CreatedChat> {
+  const res = await tgGroup(client).createGroup({ title, users: members });
+  const missing = new Set(res.missing.map((m) => m.userId));
+  const outcomes: MemberOutcome[] = [];
+  for (const m of members) {
+    const uid = await idOf(client, m);
+    outcomes.push(
+      uid !== null && missing.has(Number(uid)) ? invited(m) : added(m),
+    );
+  }
+  return { chatId: res.chat.id, outcomes };
+}
+
+async function createPerMember(
+  client: UserClient,
+  title: string,
+  members: string[],
+): Promise<CreatedChat> {
+  let chatId: number | null = null;
+  const outcomes: MemberOutcome[] = [];
+  const pending: string[] = [];
+  for (const m of members) {
+    if (chatId !== null) {
+      pending.push(m);
+      continue;
+    }
+    try {
+      const res = await tgGroup(client).createGroup({ title, users: [m] });
+      chatId = res.chat.id;
+      outcomes.push(res.missing.length ? invited(m) : added(m));
+    } catch (e) {
+      if (!isAddFailure(e)) throw e;
+      outcomes.push(invited(m));
+    }
+  }
+  if (chatId === null)
+    throw new TrainError(
+      'telegram_call',
+      'could not create group: no requested member could be added',
+    );
+  for (const m of pending) outcomes.push(await addOne(client, chatId, m));
+  return { chatId, outcomes };
+}
+
+async function createChat(
+  client: UserClient,
+  title: string,
+  members: string[],
+): Promise<CreatedChat> {
+  try {
+    return await createWithAll(client, title, members);
+  } catch (e) {
+    if (!isAddFailure(e)) throw e;
+    return createPerMember(client, title, members);
+  }
+}
+
+async function finalize(
+  client: UserClient,
+  base: GroupResult,
+  chatId: number,
+  outcomes: MemberOutcome[],
+): Promise<GroupResult> {
+  const result: GroupResult = { ...base, members: outcomes };
+  if (outcomes.some((o) => o.status === 'invited'))
+    result.inviteLink = (await tgGroup(client).exportInviteLink(chatId)).link;
+  return result;
+}
+
+async function idOf(client: UserClient, member: string): Promise<string | null> {
+  const trimmed = member.replace(/^@/, '');
+  if (/^-?\d+$/.test(trimmed)) return trimmed;
+  try {
+    const peer = await tgGroup(client).resolvePeer(member);
+    const uid = peer.userId ?? peer.channelId ?? peer.chatId;
+    return uid !== undefined ? String(uid) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function groupCreate(
+  client: UserClient,
+  accountId: string,
+  args: Record<string, unknown>,
+): Promise<GroupResult> {
+  const name = typeof args.name === 'string' ? args.name : '';
+  if (!name) throw new TrainError('bad_request', 'groupCreate requires a `name`');
+  const members = membersOf(args);
+  if (!members.length)
+    throw new TrainError('bad_request', 'groupCreate requires `members`');
+  const { chatId, outcomes } = await createChat(client, name, members);
+  return finalize(
+    client,
+    {
+      capability: { supported: true },
+      line: lineOf(accountId, chatId),
+      id: String(chatId),
+      name,
+    },
+    chatId,
+    outcomes,
+  );
+}
+
+export async function groupAddMembers(
+  client: UserClient,
+  chatId: number,
+  line: string,
+  args: Record<string, unknown>,
+): Promise<GroupResult> {
+  const members = membersOf(args);
+  if (!members.length)
+    throw new TrainError('bad_request', 'groupAddMembers requires `members`');
+  const outcomes: MemberOutcome[] = [];
+  for (const m of members) outcomes.push(await addOne(client, chatId, m));
+  return finalize(
+    client,
+    { capability: { supported: true }, line, id: String(chatId) },
+    chatId,
+    outcomes,
+  );
+}
+
+export async function groupRemoveMembers(
+  client: UserClient,
+  chatId: number,
+  line: string,
+  args: Record<string, unknown>,
+): Promise<GroupResult> {
+  const members = membersOf(args);
+  if (!members.length)
+    throw new TrainError('bad_request', 'groupRemoveMembers requires `members`');
+  for (const m of members)
+    await tgGroup(client).kickChatMember({ chatId, userId: m });
+  return {
+    capability: { supported: true },
+    line,
+    id: String(chatId),
+    members: members.map((id) => ({ id, status: 'removed' as const })),
+  };
+}
+
+export async function groupInviteLink(
+  client: UserClient,
+  chatId: number,
+  line: string,
+): Promise<GroupResult> {
+  const link = await tgGroup(client).exportInviteLink(chatId);
+  return {
+    capability: { supported: true },
+    line,
+    id: String(chatId),
+    inviteLink: link.link,
+  };
+}

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

@@ -0,0 +1,52 @@
+import type { Message } from '@mtcute/bun';
+import { lineOf } from './accounts.js';
+import { displayName, senderName } from './format.js';
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+
+export function clampLimit(limit: unknown): number {
+  const n = typeof limit === 'number' ? limit : Number(limit);
+  if (!Number.isFinite(n)) return DEFAULT_LIMIT;
+  return Math.min(Math.max(1, Math.trunc(n)), MAX_LIMIT);
+}
+
+function senderUri(accountId: string, m: Message): string {
+  return `metro://telegram/${accountId}/user/${m.sender.id}`;
+}
+
+function textOf(m: Message): string {
+  if (m.text) return m.text;
+  if (m.media !== null) return `[${m.media.type}]`;
+  return '';
+}
+
+export interface ReadMessage {
+  id: string;
+  ts: string;
+  from: string;
+  from_name?: string;
+  from_display_name?: string;
+  text: string;
+}
+
+export function shapeHistory(
+  accountId: string,
+  chatId: number,
+  messages: readonly Message[],
+): { line: string; count: number; messages: ReadMessage[] } {
+  const ordered = [...messages].reverse();
+  const shaped = ordered.map((m) => ({
+    id: String(m.id),
+    ts: m.date.toISOString(),
+    from: senderUri(accountId, m),
+    from_name: senderName(m.sender),
+    from_display_name: displayName(m.sender),
+    text: textOf(m),
+  }));
+  return {
+    line: lineOf(accountId, chatId),
+    count: shaped.length,
+    messages: shaped,
+  };
+}

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

@@ -0,0 +1,78 @@
+import type { Message } from '@mtcute/bun';
+import { errMsg, log } from '@metro-labs/mcp/log';
+import { emit } from './wire.js';
+import { envelope, isOwnEcho, attachmentSavedEnvelope } from './format.js';
+import { downloadMedia, isDownloadable } from './attachments.js';
+import { subscribeReactions } from './reactions.js';
+import type { UserClient } from './client.js';
+
+async function saveMediaAndEmit(
+  client: UserClient,
+  m: Message,
+  env: Record<string, unknown>,
+): Promise<void> {
+  const { media } = m;
+  if (media === null || !isDownloadable(media)) return;
+  const accountId = client.account.id;
+  try {
+    const saved = await downloadMedia(client, media, String(m.id), 0);
+    emit(
+      attachmentSavedEnvelope(
+        accountId,
+        env.line as string,
+        env.id as string,
+        saved,
+      ),
+    );
+  } catch (e) {
+    process.stderr.write(
+      `telegram[${accountId}] media save failed: ${errMsg(e)}\n`,
+    );
+  }
+}
+
+function emitMessage(client: UserClient, m: Message): void {
+  log.debug(
+    { train: 'telegram', account: client.account.id, messageId: m.id },
+    'inbound message received',
+  );
+  if (isOwnEcho(m)) return;
+  const env = envelope(client.account.id, m);
+  emit(env);
+  if (m.media !== null)
+    saveMediaAndEmit(client, m, env).catch((err: unknown) => {
+      process.stderr.write(
+        `telegram[${client.account.id}] media save failed: ${errMsg(err)}\n`,
+      );
+    });
+}
+
+function subscribe(client: UserClient): void {
+  const accountId = client.account.id;
+  const onMessage = (m: Message): void => {
+    try {
+      emitMessage(client, m);
+    } catch (e) {
+      process.stderr.write(
+        `telegram[${accountId}] normalize failed: ${errMsg(e)}\n`,
+      );
+    }
+  };
+  client.tg.onNewMessage.add(onMessage);
+  client.tg.onEditMessage.add(onMessage);
+  subscribeReactions(client);
+}
+
+export async function startInbound(client: UserClient): Promise<void> {
+  const accountId = client.account.id;
+  try {
+    subscribe(client);
+    await client.connect();
+    await client.startUpdates();
+    process.stderr.write(`telegram[${accountId}] inbound connected\n`);
+  } catch (e) {
+    process.stderr.write(
+      `telegram[${accountId}] connect failed: ${errMsg(e)}\n`,
+    );
+  }
+}

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

@@ -0,0 +1,46 @@
+import { TrainError } from '@metro-labs/mcp/train-error';
+import { errMsg } from '@metro-labs/mcp/log';
+import { readCalls } from '@metro-labs/mcp/trains/protocol';
+import {
+  accounts,
+  loadAccounts,
+  accountFor,
+  lineOf,
+  targetOf,
+} from './accounts.js';
+import { createClient, type UserClient } from './client.js';
+import { startInbound } from './inbound.js';
+import { makeHandleCall } from './actions.js';
+
+const clients = new Map<string, UserClient>();
+
+function clientFor(accountId: string): UserClient {
+  let client = clients.get(accountId);
+  if (!client) {
+    const account = accounts.get(accountId);
+    if (!account)
+      throw new TrainError('not_implemented', `unknown account '${accountId}'`);
+    client = createClient(account);
+    clients.set(accountId, client);
+  }
+  return client;
+}
+
+const handleCall = makeHandleCall(clientFor);
+
+readCalls('telegram', handleCall);
+
+function boot(): void {
+  for (const cfg of loadAccounts()) accounts.set(cfg.id, cfg);
+  for (const id of accounts.keys())
+    startInbound(clientFor(id)).catch((err: unknown) => {
+      process.stderr.write(`telegram[${id}] inbound failed: ${errMsg(err)}\n`);
+    });
+  process.stderr.write(
+    `telegram train ready (inbound+outbound) — ${accounts.size} account(s): ${[...accounts.keys()].join(', ')}\n`,
+  );
+}
+
+boot();
+
+export { clients, accounts, clientFor, accountFor, lineOf, targetOf };

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

@@ -0,0 +1,166 @@
+import { TelegramClient } from '@mtcute/bun';
+
+export class TelegramLoginError extends Error {}
+
+export interface TelegramCredentials {
+  apiId: number;
+  apiHash: string;
+  phone: string;
+}
+
+export interface TelegramSignedIn {
+  config: { session: string; apiId: number; apiHash: string };
+  identity: { userId: string; displayName: string };
+}
+
+export type TelegramStep = 'code' | 'password';
+
+const PHONE_RE = /^[0-9]{6,15}$/;
+const API_HASH_RE = /^[a-f0-9]{32}$/i;
+
+export function rpcErrorText(err: unknown): string {
+  if (typeof err !== 'object' || err === null) return '';
+  const text = (err as { text?: unknown }).text;
+  return typeof text === 'string' ? text : '';
+}
+
+export function needsPassword(err: unknown): boolean {
+  return rpcErrorText(err) === 'SESSION_PASSWORD_NEEDED';
+}
+
+export function readableAuthError(err: unknown): string {
+  const text = rpcErrorText(err);
+  if (text.startsWith('PHONE_CODE_INVALID')) return 'that login code is not right';
+  if (text.startsWith('PHONE_CODE_EXPIRED'))
+    return 'that login code has expired, start again';
+  if (text.startsWith('PHONE_NUMBER_INVALID'))
+    return 'Telegram does not recognise that phone number';
+  if (text.startsWith('PHONE_NUMBER_BANNED'))
+    return 'Telegram has banned that phone number';
+  if (text.startsWith('PASSWORD_HASH_INVALID'))
+    return 'that two-step verification password is not right';
+  if (text.startsWith('FLOOD_WAIT'))
+    return 'Telegram is rate-limiting this number, try again later';
+  return text === '' ? 'Telegram refused the sign-in' : `Telegram said ${text}`;
+}
+
+export function validateCredentials(raw: {
+  apiId: unknown;
+  apiHash: unknown;
+  phone: unknown;
+}): TelegramCredentials {
+  const apiId = Number(raw.apiId);
+  if (!Number.isInteger(apiId) || apiId <= 0)
+    throw new TelegramLoginError(
+      'api id must be the integer from my.telegram.org',
+    );
+  const apiHash = typeof raw.apiHash === 'string' ? raw.apiHash.trim() : '';
+  if (!API_HASH_RE.test(apiHash))
+    throw new TelegramLoginError(
+      'api hash must be the 32-character hash from my.telegram.org',
+    );
+  const phone =
+    typeof raw.phone === 'string' ? raw.phone.replace(/[^0-9]/g, '') : '';
+  if (!PHONE_RE.test(phone))
+    throw new TelegramLoginError(
+      'phone must be an international number, digits only',
+    );
+  return { apiId, apiHash, phone };
+}
+
+interface SentCodeLike {
+  phoneCodeHash: string;
+  length: number;
+  type: string;
+}
+
+const isSentCode = (v: unknown): v is SentCodeLike =>
+  typeof v === 'object' &&
+  v !== null &&
+  typeof (v as { phoneCodeHash?: unknown }).phoneCodeHash === 'string';
+
+interface UserLike {
+  id: number;
+  displayName: string;
+}
+
+export class TelegramLogin {
+  private tg: TelegramClient;
+  private phoneCodeHash = '';
+  private closed = false;
+
+  constructor(private creds: TelegramCredentials) {
+    this.tg = new TelegramClient({
+      apiId: creds.apiId,
+      apiHash: creds.apiHash,
+      storage: ':memory:',
+    });
+  }
+
+  async requestCode(): Promise<{ step: TelegramStep; length: number }> {
+    await this.tg.connect();
+    const sent = await this.tg
+      .sendCode({ phone: this.creds.phone })
+      .catch((err: unknown) => {
+        throw new TelegramLoginError(readableAuthError(err));
+      });
+    if (!isSentCode(sent))
+      throw new TelegramLoginError(
+        'Telegram signed this number in without a code, which Metro cannot use',
+      );
+    this.phoneCodeHash = sent.phoneCodeHash;
+    return { step: 'code', length: sent.length };
+  }
+
+  async submitCode(raw: string): Promise<TelegramSignedIn | 'password'> {
+    const phoneCode = raw.replace(/[^0-9]/g, '');
+    if (phoneCode === '')
+      throw new TelegramLoginError('enter the login code Telegram sent you');
+    try {
+      const user = await this.tg.signIn({
+        phone: this.creds.phone,
+        phoneCodeHash: this.phoneCodeHash,
+        phoneCode,
+      });
+      return await this.exportFor(user);
+    } catch (err) {
+      if (needsPassword(err)) return 'password';
+      throw new TelegramLoginError(readableAuthError(err));
+    }
+  }
+
+  async submitPassword(password: string): Promise<TelegramSignedIn> {
+    if (password === '')
+      throw new TelegramLoginError(
+        'enter your Telegram two-step verification password',
+      );
+    try {
+      const user = await this.tg.checkPassword(password);
+      return await this.exportFor(user);
+    } catch (err) {
+      throw new TelegramLoginError(readableAuthError(err));
+    }
+  }
+
+  private async exportFor(user: UserLike): Promise<TelegramSignedIn> {
+    const session = await this.tg.exportSession();
+    await this.close();
+    return {
+      config: {
+        session,
+        apiId: this.creds.apiId,
+        apiHash: this.creds.apiHash,
+      },
+      identity: {
+        userId: String(user.id),
+        displayName: user.displayName,
+      },
+    };
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.tg.destroy().catch(() => undefined);
+  }
+}

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

@@ -0,0 +1,80 @@
+import type { InputMediaLike, Message } from '@mtcute/bun';
+import { InputMedia } from '@mtcute/bun';
+import { isImageMime, isImageExt } from '@metro-labs/mcp/stations/attachments';
+import type { UserClient } from './client.js';
+
+export interface CanonicalAttachment {
+  kind?: string;
+  path?: string;
+  url?: string;
+  mime?: string;
+  name?: string;
+}
+
+const srcOf = (att: CanonicalAttachment): string => att.path ?? att.url ?? '';
+
+function isImage(att: CanonicalAttachment): boolean {
+  if (att.kind === 'image') return true;
+  if (att.mime !== undefined) return isImageMime(att.mime);
+  const src = srcOf(att);
+  return src !== '' && isImageExt(src);
+}
+
+function fileRef(att: CanonicalAttachment): string {
+  const src = srcOf(att);
+  if (src === '' || /^https?:\/\//i.test(src)) return src;
+  return src.startsWith('file:') ? src : `file:${src}`;
+}
+
+export interface OutgoingMedia {
+  media: InputMediaLike;
+  kind: string;
+}
+
+export function buildInputMedia(
+  att: CanonicalAttachment,
+  caption: string | undefined,
+): OutgoingMedia {
+  const file = fileRef(att);
+  const params = {
+    ...(caption ? { caption } : {}),
+    ...(att.name ? { fileName: att.name } : {}),
+  };
+  return isImage(att)
+    ? { media: InputMedia.photo(file, params), kind: 'image' }
+    : { media: InputMedia.document(file, params), kind: 'file' };
+}
+
+interface SendMediaTarget {
+  client: UserClient;
+  chatId: number;
+  replyTo?: number;
+}
+
+export interface SentMedia {
+  message: Message;
+  delivered: string[];
+}
+
+export async function sendAttachments(
+  target: SendMediaTarget,
+  attachments: CanonicalAttachment[],
+  text: string,
+): Promise<SentMedia> {
+  const { client, chatId, replyTo } = target;
+  const peer = await client.tg.resolvePeer(chatId);
+  let last: Message | undefined;
+  const delivered: string[] = [];
+  for (let i = 0; i < attachments.length; i++) {
+    const att = attachments[i];
+    if (!att || srcOf(att) === '') continue;
+    const caption = i === 0 ? text : undefined;
+    const out = buildInputMedia(att, caption);
+    last = await client.tg.sendMedia(peer, out.media, {
+      ...(replyTo !== undefined ? { replyTo } : {}),
+    });
+    delivered.push(out.kind);
+  }
+  if (!last) throw new Error('no attachments were sent');
+  return { message: last, delivered };
+}