@bruch/max-client 0.1.0

package/dist/types/utils.d.ts

@@ -0,0 +1,10 @@
+export type MaxId = bigint;
+export declare function toMaxId(value: unknown, field?: string): MaxId;
+export declare function optionalMaxId(value: unknown, field?: string): MaxId | null;
+export declare function asRecord(value: unknown, field?: string): Record<string, unknown>;
+export declare function optionalRecord(value: unknown): Record<string, unknown> | null;
+export declare function asString(value: unknown, fallback?: string): string;
+export declare function asNumber(value: unknown, fallback?: number): number;
+export declare function asBoolean(value: unknown, fallback?: boolean): boolean;
+export declare function asArray(value: unknown): unknown[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/types/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/types/utils.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC;AAE3B,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAO,GAAG,KAAK,CAK3D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAO,GAAG,KAAK,GAAG,IAAI,CAExE;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKnF;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAI7E;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,MAAM,CAE9D;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,MAAM,CAM7D;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAEnE;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,CAEjD"}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@bruch/max-client",
+  "version": "0.1.0",
+  "description": "Unofficial Bun/TypeScript client for the Max messenger internal API",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "packageManager": "bun@1.3.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "bun": "./src/auth/index.ts",
+      "default": "./dist/auth/index.js"
+    },
+    "./files": {
+      "types": "./dist/files/index.d.ts",
+      "bun": "./src/files/index.ts",
+      "default": "./dist/files/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol/index.d.ts",
+      "bun": "./src/protocol/index.ts",
+      "default": "./dist/protocol/index.js"
+    },
+    "./session": {
+      "types": "./dist/session/index.d.ts",
+      "bun": "./src/session/index.ts",
+      "default": "./dist/session/index.js"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.ts",
+      "bun": "./src/telemetry/index.ts",
+      "default": "./dist/telemetry/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "bun": "./src/types/index.ts",
+      "default": "./dist/types/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "UPSTREAM.md"
+  ],
+  "scripts": {
+    "build": "bun run clean && bun build src/index.ts src/auth/index.ts src/files/index.ts src/protocol/index.ts src/session/index.ts src/telemetry/index.ts src/types/index.ts --outdir dist --target bun --format esm --packages external --sourcemap=external && tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "bun test --coverage",
+    "test:unit": "bun test",
+    "test:real": "bun run scripts/real-test.ts",
+    "pack:check": "bun pm pack --dry-run",
+    "check": "bun run lint && bun run format:check && bun run typecheck && bun run test && bun run build && bun run pack:check"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.3",
+    "lossless-json": "^4.3.0",
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/bun": "^1.3.14",
+    "@types/qrcode": "^1.5.6",
+    "eslint": "^10.7.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.9.5",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.64.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "max",
+    "messenger",
+    "api",
+    "bun",
+    "typescript",
+    "websocket",
+    "tcp"
+  ]
+}

package/src/api/account.ts

@@ -0,0 +1,93 @@
+import type { Photo } from "../files/index.ts";
+import { Opcode } from "../protocol/index.ts";
+import { Profile, asString, type MaxId } from "../types/index.ts";
+import { payload, requiredItem } from "./response.ts";
+import type { ApiRuntime } from "./runtime.ts";
+import type { UploadApi } from "./uploads.ts";
+
+export class AccountApi {
+  constructor(
+    private readonly app: ApiRuntime,
+    private readonly uploads: UploadApi,
+  ) {}
+
+  async requestProfilePhotoUploadUrl(): Promise<string> {
+    return asString(
+      requiredItem(await this.app.invoke(Opcode.PHOTO_UPLOAD, { count: 1, profile: true }), "url"),
+    );
+  }
+
+  async changeProfile(options: {
+    firstName: string;
+    lastName?: string | null;
+    description?: string | null;
+    photo?: Photo | null;
+    photoToken?: string | null;
+  }): Promise<boolean> {
+    let photoToken = options.photoToken ?? null;
+    if (options.photo) {
+      const uploaded = await this.uploads.uploadPhoto(options.photo, true);
+      if (uploaded._type === "PHOTO") photoToken = uploaded.photoToken;
+    }
+    const frame = await this.app.invoke(Opcode.PROFILE, {
+      firstName: options.firstName,
+      lastName: options.lastName ?? null,
+      description: options.description ?? null,
+      photoToken,
+      avatarType: "USER_AVATAR",
+    });
+    this.app.me = Profile.fromPayload(requiredItem(frame, "profile"));
+    return true;
+  }
+
+  async createFolder(
+    title: string,
+    chatInclude: MaxId[],
+    filters: unknown[] = [],
+  ): Promise<Record<string, unknown>> {
+    return payload(
+      await this.app.invoke(Opcode.FOLDERS_UPDATE, {
+        id: crypto.randomUUID(),
+        title,
+        include: chatInclude,
+        filters,
+      }),
+    );
+  }
+  async getFolders(folderSync = 0): Promise<Record<string, unknown>> {
+    return payload(await this.app.invoke(Opcode.FOLDERS_GET, { folderSync }));
+  }
+  async updateFolder(
+    folderId: string,
+    title: string,
+    chatInclude: MaxId[] = [],
+    filters: unknown[] = [],
+    options: unknown[] = [],
+  ): Promise<Record<string, unknown>> {
+    return payload(
+      await this.app.invoke(Opcode.FOLDERS_UPDATE, {
+        id: folderId,
+        title,
+        include: chatInclude,
+        filters,
+        options,
+      }),
+    );
+  }
+  async deleteFolder(folderId: string): Promise<Record<string, unknown>> {
+    return payload(await this.app.invoke(Opcode.FOLDERS_DELETE, { folderIds: [folderId] }));
+  }
+  async closeAllSessions(): Promise<boolean> {
+    if (!this.app.session) return false;
+    const data = payload(await this.app.invoke(Opcode.SESSIONS_CLOSE, {}));
+    const token = asString(data.token);
+    if (!token) return false;
+    await this.app.store.updateToken(this.app.session.token, token);
+    this.app.session = { ...this.app.session, token };
+    return true;
+  }
+  async logout(): Promise<boolean> {
+    await this.app.invoke(Opcode.LOGOUT, {});
+    return true;
+  }
+}

package/src/api/auth.ts

@@ -0,0 +1,312 @@
+import { DeviceType, type UserAgent } from "../config.ts";
+import { Opcode } from "../protocol/index.ts";
+import { defaultSyncState, resolveSync, type SyncState } from "../session/index.ts";
+import {
+  Chat,
+  Message,
+  Profile,
+  User,
+  asArray,
+  asNumber,
+  asRecord,
+  asString,
+  toMaxId,
+} from "../types/index.ts";
+import { payload, requiredItem } from "./response.ts";
+import type { ApiRuntime } from "./runtime.ts";
+
+export interface PasswordChallenge {
+  trackId: string;
+  hint: string | null;
+}
+export interface CodeResult {
+  loginToken: string | null;
+  registerToken: string | null;
+  passwordChallenge: PasswordChallenge | null;
+}
+export interface QrRequest {
+  expiresAt: number;
+  pollingInterval: number;
+  qrLink: string;
+  trackId: string;
+  ttl: number;
+}
+export interface LoginResult {
+  chats: Chat[];
+  profile: Profile;
+  messages: Map<bigint, Message[]>;
+  contacts: Array<User | null>;
+  token: string | null;
+  time: number | null;
+  configHash: string | number | null;
+}
+
+export class AuthApi {
+  constructor(private readonly app: ApiRuntime) {}
+
+  async requestCode(phone: string): Promise<Record<string, unknown>> {
+    const frame = await this.app.invoke(Opcode.AUTH_REQUEST, {
+      phone,
+      type: "START_AUTH",
+      language: "ru",
+    });
+    return payload(frame);
+  }
+
+  async sendCode(token: string, verifyCode: string): Promise<CodeResult> {
+    const frame = await this.app.invoke(Opcode.AUTH, {
+      token,
+      verifyCode,
+      authTokenType: "CHECK_CODE",
+    });
+    return parseCodeResult(payload(frame));
+  }
+
+  async checkPassword(
+    trackId: string,
+    password: string,
+  ): Promise<CodeResult & { error: string | null }> {
+    const frame = await this.app.invoke(Opcode.AUTH_LOGIN_CHECK_PASSWORD, { trackId, password });
+    const data = payload(frame);
+    return { ...parseCodeResult(data), error: typeof data.error === "string" ? data.error : null };
+  }
+
+  async requestQr(): Promise<QrRequest> {
+    const data = payload(await this.app.invoke(Opcode.GET_QR, {}));
+    return {
+      expiresAt: asNumber(data.expiresAt),
+      pollingInterval: asNumber(data.pollingInterval),
+      qrLink: asString(data.qrLink),
+      trackId: asString(data.trackId),
+      ttl: asNumber(data.ttl),
+    };
+  }
+
+  async checkQr(trackId: string): Promise<{ expiresAt: number; loginAvailable: boolean }> {
+    const data = asRecord(
+      requiredItem(await this.app.invoke(Opcode.GET_QR_STATUS, { trackId }), "status"),
+    );
+    return { expiresAt: asNumber(data.expiresAt), loginAvailable: data.loginAvailable === true };
+  }
+
+  async confirmQr(trackId: string): Promise<CodeResult> {
+    return parseCodeResult(payload(await this.app.invoke(Opcode.LOGIN_BY_QR, { trackId })));
+  }
+
+  async confirmRegistration(
+    firstName: string,
+    lastName: string | null,
+    token: string,
+  ): Promise<string> {
+    const data = payload(
+      await this.app.invoke(Opcode.AUTH_CONFIRM, {
+        firstName,
+        lastName,
+        token,
+        tokenType: "REGISTER",
+      }),
+    );
+    return asString(data.token);
+  }
+
+  async handshake(deviceId: string): Promise<void> {
+    const { userAgent, mtInstanceId, clientSessionId } = this.app.config.device;
+    if (userAgent.deviceType === DeviceType.WEB) {
+      await this.app.invoke(Opcode.SESSION_INIT, {
+        userAgent: webUserAgent(userAgent),
+        deviceId,
+      });
+    } else {
+      await this.app.invoke(Opcode.SESSION_INIT, {
+        mt_instanceid: mtInstanceId,
+        userAgent,
+        clientSessionId,
+        deviceId,
+      });
+    }
+  }
+
+  async login(): Promise<LoginResult> {
+    const session = this.app.session;
+    if (!session) throw new Error("No session available for login");
+    const sync = resolveSync(session.sync, this.app.config.sync);
+    const userAgent = this.app.config.device.userAgent;
+    const loginPayload =
+      userAgent.deviceType === DeviceType.WEB
+        ? {
+            token: session.token,
+            chatsCount: 40,
+            interactive: true,
+            chatsSync: sync.chatsSync,
+            contactsSync: sync.contactsSync,
+            presenceSync: sync.presenceSync,
+            draftsSync: sync.draftsSync,
+          }
+        : {
+            userAgent,
+            token: session.token,
+            chatsSync: sync.chatsSync,
+            contactsSync: sync.contactsSync,
+            draftsSync: sync.draftsSync,
+            presenceSync: sync.presenceSync,
+            interactive: true,
+            exp: { chatsCountGroups: Uint8Array.from([0x0a, 0x32]) },
+            configHash: sync.configHash,
+          };
+    const result = parseLogin(payload(await this.app.invoke(Opcode.LOGIN, loginPayload)), this.app);
+    const updatedSync: SyncState = defaultSyncState({
+      chatsSync: result.time ?? session.sync.chatsSync,
+      contactsSync: result.time ?? session.sync.contactsSync,
+      draftsSync: result.time ?? session.sync.draftsSync,
+      presenceSync: result.time ?? session.sync.presenceSync,
+      configHash: result.configHash ?? session.sync.configHash,
+    });
+    this.app.session = {
+      ...session,
+      mtInstanceId: this.app.config.device.mtInstanceId,
+      sync: updatedSync,
+    };
+    await this.app.store.saveSession(this.app.session);
+    return result;
+  }
+
+  async createTrack(): Promise<string> {
+    const data = payload(await this.app.invoke(Opcode.AUTH_CREATE_TRACK, { type: 0 }));
+    const trackId = asString(data.trackId);
+    if (!trackId) throw new Error("Failed to create auth track");
+    return trackId;
+  }
+
+  async setTwoFactor(options: {
+    password: string;
+    hint?: string;
+    email?: string;
+    emailCodeProvider?: (email: string) => string | Promise<string>;
+  }): Promise<boolean> {
+    const trackId = await this.createTrack();
+    await this.app.invoke(Opcode.AUTH_VALIDATE_PASSWORD, { trackId, password: options.password });
+    const capabilities = [1];
+    if (options.email !== undefined) {
+      await this.app.invoke(Opcode.AUTH_VERIFY_EMAIL, { trackId, email: options.email });
+      if (!options.emailCodeProvider) throw new Error("emailCodeProvider is required");
+      const verifyCode = await options.emailCodeProvider(options.email);
+      await this.app.invoke(Opcode.AUTH_CHECK_EMAIL, { trackId, verifyCode });
+      capabilities.push(3);
+    }
+    if (options.hint !== undefined) {
+      await this.app.invoke(Opcode.AUTH_VALIDATE_HINT, { trackId, hint: options.hint });
+      capabilities.push(2);
+    }
+    await this.app.invoke(Opcode.AUTH_SET_2FA, {
+      trackId,
+      password: options.password,
+      hint: options.hint ?? null,
+      expectedCapabilities: capabilities,
+    });
+    return true;
+  }
+
+  async removeTwoFactor(password: string): Promise<boolean> {
+    const trackId = await this.createTrack();
+    await this.app.invoke(Opcode.AUTH_CHECK_PASSWORD, { trackId, password });
+    await this.app.invoke(Opcode.AUTH_SET_2FA, {
+      trackId,
+      remove2fa: true,
+      expectedCapabilities: [4],
+    });
+    return true;
+  }
+
+  async changePassword(oldPassword: string, newPassword: string): Promise<boolean> {
+    const trackId = await this.createTrack();
+    await this.app.invoke(Opcode.AUTH_CHECK_PASSWORD, { trackId, password: oldPassword });
+    await this.app.invoke(Opcode.AUTH_VALIDATE_PASSWORD, { trackId, password: newPassword });
+    await this.app.invoke(Opcode.AUTH_SET_2FA, {
+      trackId,
+      password: newPassword,
+      hint: null,
+      expectedCapabilities: [5],
+    });
+    return true;
+  }
+
+  async authorizeQrLogin(qrLink: string): Promise<boolean> {
+    await this.app.invoke(Opcode.AUTH_QR_APPROVE, { qrLink });
+    return true;
+  }
+
+  async checkTwoFactor(): Promise<boolean> {
+    return this.app.me?.profileOptions?.includes(2) ?? false;
+  }
+}
+
+function parseCodeResult(data: Record<string, unknown>): CodeResult {
+  const attrs = data.tokenAttrs ? asRecord(data.tokenAttrs) : {};
+  const login = attrs.LOGIN ? asRecord(attrs.LOGIN) : null;
+  const register = attrs.REGISTER ? asRecord(attrs.REGISTER) : null;
+  const challenge = data.passwordChallenge ? asRecord(data.passwordChallenge) : null;
+  return {
+    loginToken: login ? asString(login.token) || null : null,
+    registerToken: register ? asString(register.token) || null : null,
+    passwordChallenge: challenge
+      ? {
+          trackId: asString(challenge.trackId),
+          hint: typeof challenge.hint === "string" ? challenge.hint : null,
+        }
+      : null,
+  };
+}
+
+function parseLogin(data: Record<string, unknown>, app: ApiRuntime): LoginResult {
+  const profile = Profile.fromPayload(data.profile);
+  app.bindUser(profile.contact);
+  const chats = asArray(data.chats).map((item) => app.bindChat(Chat.fromPayload(item)));
+  const contacts = asArray(data.contacts).map((item) =>
+    item ? app.bindUser(User.fromPayload(item)) : null,
+  );
+  const messages = new Map<bigint, Message[]>();
+  if (data.messages && typeof data.messages === "object") {
+    for (const [chatId, items] of Object.entries(data.messages)) {
+      messages.set(
+        toMaxId(chatId),
+        asArray(items).map((item) => app.bindMessage(Message.fromPayload(item))),
+      );
+    }
+  }
+  const config = data.config ? asRecord(data.config) : null;
+  return {
+    chats,
+    profile,
+    messages,
+    contacts,
+    token: typeof data.token === "string" ? data.token : null,
+    time: data.time === null || data.time === undefined ? null : asNumber(data.time),
+    configHash:
+      typeof config?.hash === "string" || typeof config?.hash === "number" ? config.hash : null,
+  };
+}
+
+function webUserAgent(agent: UserAgent): Partial<UserAgent> {
+  const {
+    deviceType,
+    locale,
+    deviceLocale,
+    osVersion,
+    deviceName,
+    headerUserAgent,
+    appVersion,
+    screen,
+    timezone,
+  } = agent;
+  return {
+    deviceType,
+    locale,
+    deviceLocale,
+    osVersion,
+    deviceName,
+    appVersion,
+    screen,
+    timezone,
+    ...(headerUserAgent ? { headerUserAgent } : {}),
+  };
+}

package/src/api/bots.ts

@@ -0,0 +1,21 @@
+import { Opcode } from "../protocol/index.ts";
+import type { MaxId } from "../types/index.ts";
+import { payload } from "./response.ts";
+import type { ApiRuntime } from "./runtime.ts";
+
+export class BotsApi {
+  constructor(private readonly app: ApiRuntime) {}
+  async getBotInitData(
+    botId: MaxId,
+    chatId?: MaxId | null,
+    startParam?: string | null,
+  ): Promise<Record<string, unknown>> {
+    return payload(
+      await this.app.invoke(Opcode.WEB_APP_INIT_DATA, {
+        botId,
+        chatId: chatId ?? null,
+        startParam: startParam ?? null,
+      }),
+    );
+  }
+}