@stage-labs/metro 0.1.0-beta.4 → 0.1.0-beta.41

package/runtime/node_modules/@metro-labs/telegram/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_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,
+  });
+}

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

@@ -0,0 +1,87 @@
+import type { Message } from '@mtcute/bun';
+import { FileLocation } from '@mtcute/bun';
+import {
+  saveBufferToCache,
+  type SavedAttachment,
+} from '@metro-labs/mcp/stations/attachments';
+import type { UserClient } from './client.js';
+
+type Media = NonNullable<Message['media']>;
+export type DownloadableMedia = Media & FileLocation;
+
+export function isDownloadable(media: Media): media is DownloadableMedia {
+  return media instanceof FileLocation;
+}
+
+interface MediaMeta {
+  mime?: string;
+  name?: string;
+}
+
+function fallbackMime(media: DownloadableMedia): string | undefined {
+  const type = (media as { type?: unknown }).type;
+  if (type === 'photo') return 'image/jpeg';
+  if (type === 'sticker') return 'image/webp';
+  return undefined;
+}
+
+function metaOf(media: DownloadableMedia): MediaMeta {
+  const withMime = media as { mimeType?: unknown };
+  const withName = media as { fileName?: unknown };
+  const mime =
+    (typeof withMime.mimeType === 'string' ? withMime.mimeType : undefined) ??
+    fallbackMime(media);
+  const name =
+    typeof withName.fileName === 'string' ? withName.fileName : undefined;
+  return {
+    ...(mime ? { mime } : {}),
+    ...(name ? { name } : {}),
+  };
+}
+
+export interface PendingDescriptor {
+  kind: string;
+  name?: string;
+}
+
+const KIND_BY_TYPE: Record<string, string> = {
+  photo: 'image',
+  sticker: 'image',
+  voice: 'audio',
+  audio: 'audio',
+  video: 'video',
+  video_note: 'video',
+  animation: 'video',
+};
+
+function mediaType(media: DownloadableMedia): string {
+  const type = (media as { type?: unknown }).type;
+  return typeof type === 'string' ? type : '';
+}
+
+function kindOf(media: DownloadableMedia, mime: string | undefined): string {
+  const byType = KIND_BY_TYPE[mediaType(media)];
+  if (byType) return byType;
+  if (mime?.startsWith('image/')) return 'image';
+  if (mime?.startsWith('audio/')) return 'audio';
+  if (mime?.startsWith('video/')) return 'video';
+  return 'file';
+}
+
+export function pendingDescriptorOf(media: DownloadableMedia): PendingDescriptor {
+  const meta = metaOf(media);
+  return {
+    kind: kindOf(media, meta.mime),
+    ...(meta.name ? { name: meta.name } : {}),
+  };
+}
+
+export async function downloadMedia(
+  client: UserClient,
+  media: DownloadableMedia,
+  messageId: string,
+  index = 0,
+): Promise<SavedAttachment> {
+  const buf = await client.tg.downloadAsBuffer(media);
+  return saveBufferToCache(buf, messageId, index, metaOf(media));
+}

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

@@ -0,0 +1,77 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { TelegramClient } from '@mtcute/bun';
+import { TrainError } from '@metro-labs/mcp/train-error';
+import { errMsg } from '@metro-labs/mcp/log';
+import type { UserAccount } from './types.js';
+
+const STATE_DIR =
+  process.env.METRO_STATE_DIR ?? join(homedir(), '.cache', 'metro');
+
+export interface Self {
+  username: string | null;
+  phone: string | null;
+}
+
+export interface UserClient {
+  account: UserAccount;
+  tg: TelegramClient;
+  self: () => Self | null;
+  connect: () => Promise<void>;
+  startUpdates: () => Promise<void>;
+  disconnect: () => Promise<void>;
+}
+
+function storagePath(accountId: string): string {
+  const dir = join(STATE_DIR, 'telegram');
+  mkdirSync(dir, { recursive: true });
+  return join(dir, `${accountId}.session`);
+}
+
+export function createClient(account: UserAccount): UserClient {
+  const apiId = account.apiId ?? 0;
+  const { apiHash } = account;
+  if (!Number.isInteger(apiId) || apiId <= 0 || !apiHash)
+    throw new TrainError(
+      'telegram_auth',
+      `account '${account.id}' missing apiId/apiHash`,
+    );
+  const tg = new TelegramClient({
+    apiId,
+    apiHash,
+    storage: storagePath(account.id),
+  });
+
+  let me: Self | null = null;
+
+  const connect = async (): Promise<void> => {
+    try {
+      await tg.importSession(account.session);
+      await tg.connect();
+    } catch (e) {
+      throw new TrainError(
+        'telegram_auth',
+        `account '${account.id}' connect failed: ${errMsg(e)}`,
+      );
+    }
+    try {
+      const user = await tg.getMe();
+      me = { username: user.username ?? null, phone: user.phoneNumber ?? null };
+    } catch (e) {
+      process.stderr.write(
+        `telegram[${account.id}] identity unavailable: ${errMsg(e)}\n`,
+      );
+    }
+  };
+
+  const startUpdates = async (): Promise<void> => {
+    await tg.startUpdatesLoop();
+  };
+
+  const disconnect = async (): Promise<void> => {
+    await tg.disconnect();
+  };
+
+  return { account, tg, self: () => me, connect, startUpdates, disconnect };
+}

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

@@ -0,0 +1,141 @@
+import type { Chat, Message, Peer, User } from '@mtcute/bun';
+import type { SavedAttachment } from '@metro-labs/mcp/stations/attachments';
+import { lineOf } from './accounts.js';
+import { mintId } from './wire.js';
+import { isDownloadable, pendingDescriptorOf } from './attachments.js';
+
+const isUser = (peer: Peer): peer is User => peer.type === 'user';
+const isChat = (peer: Peer): peer is Chat => peer.type === 'chat';
+
+export function senderName(peer: Peer): string | undefined {
+  if (isUser(peer)) return peer.username ? `@${peer.username}` : peer.firstName;
+  return peer.title;
+}
+
+export function displayName(peer: Peer): string | undefined {
+  if (isUser(peer)) return peer.firstName;
+  return peer.title;
+}
+
+function chatName(peer: Peer): string | undefined {
+  if (isChat(peer)) return peer.title;
+  if (isUser(peer)) return peer.username ? `@${peer.username}` : peer.firstName;
+  return undefined;
+}
+
+function topicOf(m: Message): number | undefined {
+  if (!m.isTopicMessage) return undefined;
+  const threadId = m.replyToMessage?.threadId;
+  return threadId ?? undefined;
+}
+
+function mediaTag(m: Message): string | undefined {
+  if (m.media === null) return undefined;
+  return `[${m.media.type}]`;
+}
+
+function projectText(m: Message): string {
+  const tag = mediaTag(m);
+  return [m.text, tag].filter(Boolean).join(' ');
+}
+
+export function isOwnEcho(m: Message): boolean {
+  if (m.isOutgoing) return true;
+  const { sender } = m;
+  return isUser(sender) && sender.isSelf;
+}
+
+export function envelope(
+  accountId: string,
+  m: Message,
+): Record<string, unknown> {
+  const topicId = topicOf(m);
+  const line = lineOf(accountId, m.chat.id, topicId);
+  const isPrivate = isUser(m.chat);
+  const { media } = m;
+  const attachments =
+    media !== null && isDownloadable(media)
+      ? [pendingDescriptorOf(media)]
+      : undefined;
+  return {
+    kind: 'inbound',
+    id: mintId(),
+    ts: m.date.toISOString(),
+    station: 'telegram',
+    line,
+    line_name: chatName(m.chat),
+    from: `metro://telegram/${accountId}/user/${m.sender.id}`,
+    from_name: senderName(m.sender),
+    from_display_name: displayName(m.sender),
+    message_id: String(m.id),
+    text: projectText(m),
+    is_private: isPrivate,
+    has_media: media !== null,
+    payload: {
+      account: accountId,
+      message_id: String(m.id),
+      ...(attachments ? { attachments } : {}),
+    },
+  };
+}
+
+export function attachmentSavedEnvelope(
+  accountId: string,
+  line: string,
+  sourceEnvId: string,
+  saved: SavedAttachment,
+  index = 0,
+): Record<string, unknown> {
+  return {
+    kind: 'inbound',
+    id: mintId(),
+    ts: new Date().toISOString(),
+    station: 'telegram',
+    line,
+    from: `metro://telegram/${accountId}/self`,
+    text: `📎 saved: ${saved.path}`,
+    payload: {
+      account: accountId,
+      contentType: 'attachmentSaved',
+      attachmentFor: sourceEnvId,
+      index,
+      attachmentPath: saved.path,
+      localPath: saved.path,
+      mime: saved.mime,
+      name: saved.name,
+    },
+  };
+}
+
+export interface ReactionInput {
+  accountId: string;
+  chatId: number;
+  messageId: number;
+  emoji: string;
+  senderId: number;
+  date: Date;
+  isPrivate: boolean;
+  senderName?: string;
+  removed?: boolean;
+}
+
+export function reactionEnvelope(r: ReactionInput): Record<string, unknown> {
+  return {
+    kind: 'react',
+    id: mintId(),
+    ts: r.date.toISOString(),
+    station: 'telegram',
+    line: lineOf(r.accountId, r.chatId),
+    from: `metro://telegram/${r.accountId}/user/${r.senderId}`,
+    from_name: r.senderName,
+    message_id: String(r.messageId),
+    emoji: r.emoji,
+    event: { type: 'react', emoji: r.emoji, targetId: String(r.messageId) },
+    is_private: r.isPrivate,
+    payload: {
+      account: r.accountId,
+      message_id: String(r.messageId),
+      removed: r.removed === true,
+    },
+  };
+}