@bruch/max-client 0.1.0

package/src/api/users.ts

@@ -0,0 +1,68 @@
+import { Opcode } from "../protocol/index.ts";
+import { User, asRecord, type MaxId, type UserActions } from "../types/index.ts";
+import { listItem, requiredItem } from "./response.ts";
+import type { ApiRuntime } from "./runtime.ts";
+
+export interface ContactInfo {
+  phone: string;
+  firstName: string;
+  lastName?: string | null;
+}
+
+export class UserApi implements UserActions {
+  private readonly cache = new Map<MaxId, User>();
+  constructor(private readonly app: ApiRuntime) {}
+
+  seed(users: Array<User | null>): void {
+    for (const user of users) if (user) this.cacheUser(user);
+  }
+  getCachedUser(userId: MaxId): User | null {
+    return this.cache.get(userId) ?? null;
+  }
+  async getUsers(userIds: MaxId[]): Promise<User[]> {
+    const missing = userIds.filter((id) => !this.cache.has(id));
+    if (missing.length > 0)
+      for (const user of await this.fetchUsers(missing)) this.cache.set(user.id, user);
+    return userIds.flatMap((id) => (this.cache.has(id) ? [this.cache.get(id) as User] : []));
+  }
+  async getUser(userId: MaxId): Promise<User | null> {
+    return (await this.getUsers([userId]))[0] ?? null;
+  }
+  async fetchUsers(userIds: MaxId[]): Promise<User[]> {
+    const frame = await this.app.invoke(Opcode.CONTACT_INFO, { contactIds: userIds });
+    return listItem(frame, "contacts").map((raw) => this.cacheUser(User.fromPayload(raw)));
+  }
+  async searchByPhone(phone: string): Promise<User> {
+    const frame = await this.app.invoke(Opcode.CONTACT_INFO_BY_PHONE, { phone });
+    return this.cacheUser(User.fromPayload(requiredItem(frame, "contact")));
+  }
+  async getSessions(): Promise<Record<string, unknown>[]> {
+    return listItem(await this.app.invoke(Opcode.SESSIONS_INFO, {}), "sessions").map((item) =>
+      asRecord(item),
+    );
+  }
+  async addContact(contactId: MaxId): Promise<User> {
+    const frame = await this.app.invoke(Opcode.CONTACT_UPDATE, { contactId, action: "add" });
+    return this.cacheUser(User.fromPayload(requiredItem(frame, "contact")));
+  }
+  async removeContact(contactId: MaxId): Promise<boolean> {
+    await this.app.invoke(Opcode.CONTACT_UPDATE, { contactId, action: "remove" });
+    this.cache.delete(contactId);
+    return true;
+  }
+  async importContacts(contacts: ContactInfo[]): Promise<User[]> {
+    const contactList = Object.fromEntries(
+      contacts.map((item) => [item.phone, { firstName: item.firstName }]),
+    );
+    const frame = await this.app.invoke(Opcode.SYNC, { contactList });
+    return listItem(frame, "contacts").map((raw) => this.cacheUser(User.fromPayload(raw)));
+  }
+  getChatId(firstUserId: MaxId, secondUserId: MaxId): MaxId {
+    return firstUserId ^ secondUserId;
+  }
+  private cacheUser(user: User): User {
+    const bound = this.app.bindUser(user);
+    this.cache.set(bound.id, bound);
+    return bound;
+  }
+}

package/src/app.ts

@@ -0,0 +1,271 @@
+import { ApiFacade, type ApiRuntime } from "./api/index.ts";
+import type { AuthFlow } from "./auth/index.ts";
+import type { ResolvedConfig } from "./config.ts";
+import { Dispatcher, type Router } from "./dispatch/index.ts";
+import { ApiError } from "./errors.ts";
+import { getLogger } from "./logging.ts";
+import { Command, Opcode, type InboundFrame, type OutboundFrame } from "./protocol/index.ts";
+import {
+  SqliteSessionStore,
+  defaultSyncState,
+  type SessionInfo,
+  type SessionStore,
+} from "./session/index.ts";
+import { TelemetryService } from "./telemetry/index.ts";
+import type {
+  Chat,
+  ChatActions,
+  Message,
+  MessageActions,
+  Profile,
+  User,
+  UserActions,
+} from "./types/index.ts";
+
+export interface ConnectionContract {
+  readonly protocol: { readonly version: number };
+  readonly isOpen?: boolean;
+  onEvent: ((frame: InboundFrame) => void | Promise<void>) | null;
+  onClose: ((error: Error | null) => void) | null;
+  open(): Promise<void>;
+  close(): Promise<void>;
+  request(frame: OutboundFrame, timeoutSeconds?: number): Promise<InboundFrame>;
+  waitClosed(): Promise<void>;
+  nextSequence(): number;
+}
+
+export class App<Client extends MessageActions & ChatActions & UserActions> implements ApiRuntime {
+  readonly dispatcher: Dispatcher<Client>;
+  readonly api: ApiFacade;
+  readonly telemetry: TelemetryService;
+  readonly store: SessionStore;
+  session: SessionInfo | null = null;
+  me: Profile | null = null;
+  chats: Chat[] = [];
+  contacts: Array<User | null> = [];
+  messages = new Map<bigint, Message[]>();
+  started = false;
+  private pingController: AbortController | null = null;
+  private readonly attachmentWaiters = new Map<
+    string,
+    Set<{ resolve(): void; reject(error: Error): void }>
+  >();
+
+  constructor(
+    readonly connection: ConnectionContract,
+    readonly config: ResolvedConfig,
+    readonly authFlow: AuthFlow,
+    rootRouter: Router<Client>,
+  ) {
+    this.dispatcher = new Dispatcher(rootRouter);
+    this.store = config.store ?? new SqliteSessionStore(config.workDir, config.sessionName);
+    this.api = new ApiFacade(this);
+    this.telemetry = new TelemetryService(this);
+    this.connection.onEvent = async (frame) => {
+      this.resolveAttachmentWaiters(frame);
+      await this.dispatcher.dispatch(frame);
+    };
+    this.connection.onClose = (error) => this.connectionLost(error);
+  }
+
+  bindClient(client: Client): void {
+    this.dispatcher.bindClient(client);
+  }
+
+  async start(): Promise<void> {
+    if (this.started) return;
+    let saved = await this.store.loadSession();
+    if (saved?.mtInstanceId) this.config.device.mtInstanceId = saved.mtInstanceId;
+    await this.connection.open();
+    await this.api.auth.handshake(saved?.deviceId ?? this.config.device.deviceId);
+    this.startPing();
+
+    if (!saved) {
+      const token = this.config.token ?? (await this.authFlow.authenticate(this)).token;
+      if (!token) throw new Error("Authentication failed: no token returned");
+      saved = {
+        token,
+        deviceId: this.config.device.deviceId,
+        phone: this.config.phone ?? "",
+        mtInstanceId: this.config.device.mtInstanceId,
+        sync: defaultSyncState(),
+      };
+      await this.store.saveSession(saved);
+    }
+    this.session = saved;
+    const login = await this.api.auth.login();
+    let activeSession = this.session ?? saved;
+    if (login.token && login.token !== activeSession.token) {
+      await this.store.updateToken(activeSession.token, login.token);
+      activeSession = { ...activeSession, token: login.token };
+    }
+    this.session = activeSession;
+    this.me = login.profile;
+    this.chats = login.chats;
+    this.contacts = login.contacts;
+    this.messages = login.messages;
+    this.api.chats.seed(this.chats);
+    this.api.users.seed([...this.contacts, this.me.contact]);
+    this.bindUser(this.me.contact);
+    this.started = true;
+    if (this.config.telemetry) this.telemetry.start();
+    getLogger().info("client started", {
+      profileId: this.me.contact.id.toString(),
+      chats: this.chats.length,
+    });
+  }
+
+  async close(): Promise<void> {
+    this.pingController?.abort();
+    this.pingController = null;
+    await this.telemetry.stop();
+    for (const entries of this.attachmentWaiters.values()) {
+      for (const entry of entries)
+        entry.reject(new Error("Client closed before upload processing completed"));
+    }
+    this.attachmentWaiters.clear();
+    await this.connection.close();
+    await this.store.close();
+    this.started = false;
+  }
+
+  async invoke(
+    opcode: number,
+    payload: Record<string, unknown> = {},
+    timeout?: number,
+  ): Promise<InboundFrame> {
+    const frame: OutboundFrame = {
+      ver: this.connection.protocol.version,
+      opcode,
+      cmd: Command.REQUEST,
+      seq: this.connection.nextSequence(),
+      payload,
+    };
+    const response = await this.connection.request(frame, timeout ?? this.config.requestTimeout);
+    if (response.cmd === Command.ERROR) throw buildApiError(response);
+    return response;
+  }
+
+  bindMessage(message: Message): Message {
+    return message.bind(this.api.messages);
+  }
+  bindChat(chat: Chat): Chat {
+    return chat.bind(this.api.messages, this.api.chats);
+  }
+  bindUser(user: User): User {
+    return user.bind(this.api.users);
+  }
+
+  createAttachmentWaiter(
+    field: "fileId" | "videoId",
+    id: number,
+    timeoutSeconds = 60,
+  ): { promise: Promise<void>; cancel(): void } {
+    const key = `${field}:${id}`;
+    const entries = this.attachmentWaiters.get(key) ?? new Set();
+    let active = true;
+    let resolvePromise: () => void = () => undefined;
+    let rejectPromise: (error: Error) => void = () => undefined;
+    const promise = new Promise<void>((resolve, reject) => {
+      resolvePromise = resolve;
+      rejectPromise = reject;
+    });
+    const entry = {
+      resolve: () => {
+        if (!active) return;
+        active = false;
+        clearTimeout(timer);
+        entries.delete(entry);
+        resolvePromise();
+      },
+      reject: (error: Error) => {
+        if (!active) return;
+        active = false;
+        clearTimeout(timer);
+        entries.delete(entry);
+        rejectPromise(error);
+      },
+    };
+    entries.add(entry);
+    this.attachmentWaiters.set(key, entries);
+    const timer = setTimeout(
+      () => entry.reject(new Error(`Timed out waiting for ${field}=${id} processing`)),
+      timeoutSeconds * 1000,
+    );
+    return {
+      promise,
+      cancel: () => {
+        if (!active) return;
+        active = false;
+        clearTimeout(timer);
+        entries.delete(entry);
+        if (entries.size === 0) this.attachmentWaiters.delete(key);
+        promise.catch(() => undefined);
+      },
+    };
+  }
+
+  private startPing(): void {
+    const controller = new AbortController();
+    this.pingController = controller;
+    void this.pingLoop(controller.signal);
+  }
+
+  private async pingLoop(signal: AbortSignal): Promise<void> {
+    try {
+      while (!signal.aborted) {
+        await this.invoke(Opcode.PING, { interactive: true });
+        await sleep(30_000, signal);
+      }
+    } catch (error) {
+      if (!signal.aborted) {
+        getLogger().warn("ping failed", { error: String(error) });
+        await this.connection.close();
+      }
+    }
+  }
+
+  private connectionLost(error: Error | null): void {
+    this.started = false;
+    this.pingController?.abort();
+    if (error) getLogger().warn("connection lost", { error: error.message });
+  }
+
+  private resolveAttachmentWaiters(frame: InboundFrame): void {
+    if (frame.opcode !== Opcode.NOTIF_ATTACH || !frame.payload) return;
+    for (const field of ["fileId", "videoId"] as const) {
+      const value = frame.payload[field];
+      if (typeof value !== "number" || !Number.isSafeInteger(value)) continue;
+      const key = `${field}:${value}`;
+      const entries = this.attachmentWaiters.get(key);
+      if (!entries) continue;
+      this.attachmentWaiters.delete(key);
+      for (const entry of entries) entry.resolve();
+    }
+  }
+}
+
+function buildApiError(frame: InboundFrame): ApiError {
+  const data = frame.payload ?? {};
+  return new ApiError(frame.opcode, {
+    error: typeof data.error === "string" ? data.error : null,
+    title: typeof data.title === "string" ? data.title : null,
+    message: typeof data.message === "string" ? data.message : null,
+    localizedMessage: typeof data.localizedMessage === "string" ? data.localizedMessage : null,
+    payload: data,
+  });
+}
+
+async function sleep(milliseconds: number, signal: AbortSignal): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, milliseconds);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}

package/src/auth/flows.ts

@@ -0,0 +1,103 @@
+import type { ApiFacade } from "../api/index.ts";
+import type { ResolvedConfig } from "../config.ts";
+import {
+  consolePasswordProvider,
+  consoleQrHandler,
+  consoleSmsCodeProvider,
+  type PasswordProvider,
+  type QrHandler,
+  type SmsCodeProvider,
+} from "./providers.ts";
+
+export interface AuthResult {
+  token: string | null;
+}
+
+export interface AuthRuntime {
+  readonly api: ApiFacade;
+  readonly config: ResolvedConfig;
+}
+
+export interface AuthFlow {
+  authenticate(app: AuthRuntime): Promise<AuthResult>;
+}
+
+export class SmsAuthFlow implements AuthFlow {
+  constructor(
+    readonly codeProvider: SmsCodeProvider = consoleSmsCodeProvider,
+    readonly passwordProvider: PasswordProvider = consolePasswordProvider,
+  ) {}
+
+  async authenticate(app: AuthRuntime): Promise<AuthResult> {
+    const phone = app.config.phone;
+    if (!phone) throw new Error("Phone is required for SMS authentication");
+    const start = await app.api.auth.requestCode(phone);
+    const token = typeof start.token === "string" ? start.token : "";
+    if (!token) throw new Error("SMS request returned no token");
+    const result = await app.api.auth.sendCode(token, await this.codeProvider(phone));
+    if (result.loginToken) return { token: result.loginToken };
+    if (result.passwordChallenge) {
+      return {
+        token: await this.passwordLogin(
+          app,
+          result.passwordChallenge.trackId,
+          result.passwordChallenge.hint,
+        ),
+      };
+    }
+    if (result.registerToken) {
+      const registration = app.config.registrationConfig;
+      if (!registration) throw new Error("registrationConfig is required for a new account");
+      return {
+        token: await app.api.auth.confirmRegistration(
+          registration.firstName,
+          registration.lastName ?? null,
+          result.registerToken,
+        ),
+      };
+    }
+    throw new Error("Authentication returned no login, registration, or password challenge");
+  }
+
+  private async passwordLogin(
+    app: AuthRuntime,
+    trackId: string,
+    hint: string | null,
+  ): Promise<string> {
+    for (;;) {
+      const result = await app.api.auth.checkPassword(trackId, await this.passwordProvider(hint));
+      if (result.loginToken) return result.loginToken;
+    }
+  }
+}
+
+export class QrAuthFlow implements AuthFlow {
+  constructor(
+    readonly qrHandler: QrHandler = consoleQrHandler,
+    readonly passwordProvider: PasswordProvider = consolePasswordProvider,
+  ) {}
+
+  async authenticate(app: AuthRuntime): Promise<AuthResult> {
+    const request = await app.api.auth.requestQr();
+    await this.qrHandler(request.qrLink);
+    while (Date.now() < request.expiresAt) {
+      const status = await app.api.auth.checkQr(request.trackId);
+      if (status.loginAvailable) {
+        const result = await app.api.auth.confirmQr(request.trackId);
+        if (result.loginToken) return { token: result.loginToken };
+        if (result.passwordChallenge) {
+          for (;;) {
+            const checked = await app.api.auth.checkPassword(
+              result.passwordChallenge.trackId,
+              await this.passwordProvider(result.passwordChallenge.hint),
+            );
+            if (checked.loginToken) return { token: checked.loginToken };
+          }
+        }
+        break;
+      }
+      await Bun.sleep(request.pollingInterval);
+    }
+    throw new Error("QR authentication expired");
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,2 @@
+export * from "./flows.ts";
+export * from "./providers.ts";

package/src/auth/providers.ts

@@ -0,0 +1,30 @@
+import QRCode from "qrcode";
+
+type MaybePromise<T> = T | Promise<T>;
+export type SmsCodeProvider = (phone: string) => MaybePromise<string>;
+export type PasswordProvider = (hint: string | null) => MaybePromise<string>;
+export type EmailCodeProvider = (email: string) => MaybePromise<string>;
+export type QrHandler = (link: string) => MaybePromise<void>;
+
+export const consoleSmsCodeProvider: SmsCodeProvider = (phone) => {
+  const code = prompt(`SMS code for ${phone}:`);
+  if (!code) throw new Error("SMS code is required");
+  return code;
+};
+
+export const consolePasswordProvider: PasswordProvider = (hint) => {
+  const password = prompt(`2FA password${hint ? ` (${hint})` : ""}:`);
+  if (!password) throw new Error("2FA password is required");
+  return password;
+};
+
+export const consoleEmailCodeProvider: EmailCodeProvider = (email) => {
+  const code = prompt(`Email code for ${email}:`);
+  if (!code) throw new Error("Email code is required");
+  return code;
+};
+
+export const consoleQrHandler: QrHandler = async (link) => {
+  console.log(await QRCode.toString(link, { type: "terminal", small: true }));
+  console.log(link);
+};