@bruch/max-client 0.1.0

package/src/connection/connection.ts

@@ -0,0 +1,93 @@
+import {
+  Command,
+  type InboundFrame,
+  type OutboundFrame,
+  type Protocol,
+} from "../protocol/index.ts";
+import { ConnectionError } from "../errors.ts";
+import type { Transport } from "../transport/index.ts";
+import { PendingRequests } from "./pending.ts";
+import type { Reader } from "./readers.ts";
+
+export class ConnectionManager<Raw extends string | Uint8Array> {
+  readonly requests = new PendingRequests();
+  onEvent: ((frame: InboundFrame) => void | Promise<void>) | null = null;
+  onClose: ((error: Error | null) => void) | null = null;
+  private sequence = -1;
+  private receiveTask: Promise<void> | null = null;
+  private abortController: AbortController | null = null;
+
+  constructor(
+    readonly reader: Reader<Raw>,
+    readonly transport: Transport<Raw>,
+    readonly protocol: Protocol<Raw>,
+  ) {}
+
+  get isOpen(): boolean {
+    return this.transport.connected;
+  }
+
+  async open(): Promise<void> {
+    if (this.isOpen) return;
+    await this.transport.connect();
+    this.abortController = new AbortController();
+    this.receiveTask = this.receiveLoop(this.abortController.signal);
+  }
+
+  async close(): Promise<void> {
+    this.abortController?.abort();
+    this.abortController = null;
+    this.requests.cancelAll();
+    await this.transport.close();
+    try {
+      await this.receiveTask;
+    } catch {
+      // Closing intentionally interrupts recv().
+    }
+    this.receiveTask = null;
+  }
+
+  async send(frame: OutboundFrame): Promise<void> {
+    if (!this.isOpen) throw new ConnectionError("Connection is not open");
+    await this.transport.send(this.protocol.encode(frame));
+  }
+
+  async request(frame: OutboundFrame, timeoutSeconds?: number): Promise<InboundFrame> {
+    const response = this.requests.create(frame.seq, timeoutSeconds);
+    try {
+      await this.send(frame);
+      return await response;
+    } catch (error) {
+      this.requests.discard(frame.seq);
+      throw error;
+    }
+  }
+
+  async waitClosed(): Promise<void> {
+    await this.receiveTask;
+  }
+
+  nextSequence(): number {
+    this.sequence = (this.sequence + 1) & 0xffff;
+    return this.sequence;
+  }
+
+  private async receiveLoop(signal: AbortSignal): Promise<void> {
+    try {
+      while (!signal.aborted) {
+        const raw = await this.reader.read();
+        const frame = this.protocol.decode(raw);
+        if ((frame.cmd === Command.RESPONSE || frame.cmd === Command.ERROR) && frame.seq !== null) {
+          this.requests.resolve(frame.seq, frame);
+        }
+        if (this.onEvent) void Promise.resolve(this.onEvent(frame));
+      }
+    } catch (error) {
+      if (signal.aborted) return;
+      const failure = error instanceof Error ? error : new ConnectionError(String(error));
+      this.requests.cancelAll(failure);
+      this.onClose?.(failure);
+      throw failure;
+    }
+  }
+}

package/src/connection/index.ts

@@ -0,0 +1,3 @@
+export * from "./connection.ts";
+export * from "./pending.ts";
+export * from "./readers.ts";

package/src/connection/pending.ts

@@ -0,0 +1,49 @@
+import type { InboundFrame } from "../protocol/index.ts";
+import { ConnectionError, TimeoutError } from "../errors.ts";
+
+interface PendingRequest {
+  resolve(frame: InboundFrame): void;
+  reject(reason: unknown): void;
+  timer: ReturnType<typeof setTimeout> | null;
+}
+
+export class PendingRequests {
+  private readonly requests = new Map<number, PendingRequest>();
+
+  create(sequence: number, timeoutSeconds?: number): Promise<InboundFrame> {
+    if (this.requests.has(sequence)) throw new Error(`Duplicate request sequence: ${sequence}`);
+    return new Promise<InboundFrame>((resolve, reject) => {
+      const request: PendingRequest = { resolve, reject, timer: null };
+      if (timeoutSeconds !== undefined) {
+        request.timer = setTimeout(() => {
+          this.requests.delete(sequence);
+          reject(new TimeoutError(`Request ${sequence} timed out`));
+        }, timeoutSeconds * 1000);
+      }
+      this.requests.set(sequence, request);
+    });
+  }
+
+  resolve(sequence: number, frame: InboundFrame): boolean {
+    const request = this.requests.get(sequence);
+    if (!request) return false;
+    this.requests.delete(sequence);
+    if (request.timer) clearTimeout(request.timer);
+    request.resolve(frame);
+    return true;
+  }
+
+  discard(sequence: number): void {
+    const request = this.requests.get(sequence);
+    if (request?.timer) clearTimeout(request.timer);
+    this.requests.delete(sequence);
+  }
+
+  cancelAll(reason: Error = new ConnectionError("Connection closed")): void {
+    for (const request of this.requests.values()) {
+      if (request.timer) clearTimeout(request.timer);
+      request.reject(reason);
+    }
+    this.requests.clear();
+  }
+}

package/src/connection/readers.ts

@@ -0,0 +1,33 @@
+import { TCP_HEADER_SIZE, TcpPacketFramer } from "../protocol/index.ts";
+import { ConnectionError } from "../errors.ts";
+import type { Transport } from "../transport/index.ts";
+
+export interface Reader<Raw extends string | Uint8Array> {
+  read(): Promise<Raw>;
+}
+
+export class TcpReader implements Reader<Uint8Array> {
+  constructor(
+    private readonly transport: Transport<Uint8Array>,
+    private readonly framer = new TcpPacketFramer(),
+  ) {}
+
+  async read(): Promise<Uint8Array> {
+    const header = await this.transport.recv(TCP_HEADER_SIZE);
+    const payloadLength = this.framer.unpackPayloadLength(header);
+    if (payloadLength === null) throw new ConnectionError("Incomplete TCP header");
+    if (payloadLength === 0) return header;
+    const payload = await this.transport.recv(payloadLength);
+    const result = new Uint8Array(header.byteLength + payload.byteLength);
+    result.set(header);
+    result.set(payload, header.byteLength);
+    return result;
+  }
+}
+
+export class WsReader implements Reader<string> {
+  constructor(private readonly transport: Transport<string>) {}
+  async read(): Promise<string> {
+    return await this.transport.recv();
+  }
+}

package/src/dispatch/dispatcher.ts

@@ -0,0 +1,194 @@
+import { Command, Opcode, type InboundFrame } from "../protocol/index.ts";
+import {
+  Chat,
+  Message,
+  asArray,
+  asBoolean,
+  asNumber,
+  asRecord,
+  optionalMaxId,
+  parseReactionInfo,
+  toMaxId,
+  type MessageDeleteEvent,
+  type MessageReadEvent,
+  type PresenceEvent,
+  type ReactionUpdateEvent,
+  type TypingEvent,
+} from "../types/index.ts";
+import { EventType, type EventMap, type Router } from "./router.ts";
+
+export class Dispatcher<Client> {
+  private client: Client | null = null;
+
+  constructor(readonly rootRouter: Router<Client>) {}
+
+  bindClient(client: Client): void {
+    this.client = client;
+  }
+
+  async emitStart(): Promise<void> {
+    const client = this.requireClient();
+    for (const router of this.routers()) {
+      for (const handler of router.startHandlers) {
+        try {
+          await handler(client);
+        } catch (error) {
+          await this.emitError(error, "start", null, router);
+        }
+      }
+    }
+  }
+
+  async emitDisconnect(error: Error, reconnect: boolean, delay: number): Promise<void> {
+    for (const router of this.routers()) {
+      for (const handler of router.disconnectHandlers) {
+        try {
+          await handler(error, reconnect, delay);
+        } catch {
+          // Disconnect handlers cannot make reconnect fail.
+        }
+      }
+    }
+  }
+
+  async dispatch(frame: InboundFrame): Promise<void> {
+    await this.dispatchEvent("raw", frame);
+    if (frame.cmd !== Command.REQUEST || !frame.payload) return;
+    const resolved = resolveEvent(frame);
+    if (resolved) await this.dispatchEvent(resolved.type, resolved.event);
+  }
+
+  private async dispatchEvent<Key extends keyof EventMap>(
+    type: Key,
+    event: EventMap[Key],
+  ): Promise<void> {
+    const client = this.requireClient();
+    for (const router of this.routers()) {
+      const entries = router.handlers.get(type) ?? [];
+      for (const rawEntry of entries) {
+        const entry = rawEntry as {
+          handler(event: EventMap[Key], client: Client): void | Promise<void>;
+          filters: Array<(event: EventMap[Key]) => boolean | Promise<boolean>>;
+        };
+        try {
+          let matches = true;
+          for (const filter of entry.filters) {
+            if (!(await filter(event))) {
+              matches = false;
+              break;
+            }
+          }
+          if (matches) await entry.handler(event, client);
+        } catch (error) {
+          await this.emitError(error, type, event, router);
+        }
+      }
+    }
+  }
+
+  private async emitError(
+    error: unknown,
+    eventType: keyof EventMap | "start",
+    event: unknown,
+    source: Router<Client>,
+  ): Promise<void> {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    const client = this.requireClient();
+    let handled = false;
+    for (const router of this.routers()) {
+      for (const handler of router.errorHandlers) {
+        handled = true;
+        await handler(failure, { client, eventType, event, router: source });
+      }
+    }
+    if (!handled) throw failure;
+  }
+
+  private *routers(router = this.rootRouter): Generator<Router<Client>> {
+    yield router;
+    for (const child of router.children) yield* this.routers(child);
+  }
+
+  private requireClient(): Client {
+    if (!this.client) throw new Error("Dispatcher has no bound client");
+    return this.client;
+  }
+}
+
+function resolveEvent(
+  frame: InboundFrame,
+): { type: keyof EventMap; event: EventMap[keyof EventMap] } | null {
+  const payload = frame.payload as Record<string, unknown>;
+  if (frame.opcode === Opcode.NOTIF_MESSAGE || frame.opcode === Opcode.MSG_EDIT) {
+    const messagePayload = payload.message ?? payload;
+    const message = Message.fromPayload(messagePayload);
+    if (message.status === "REMOVED")
+      return { type: EventType.MESSAGE_DELETE, event: deleteFromMessage(message, payload) };
+    return {
+      type: message.status === "EDITED" ? EventType.MESSAGE_EDIT : EventType.MESSAGE_NEW,
+      event: message,
+    };
+  }
+  if (frame.opcode === Opcode.NOTIF_CHAT) {
+    return { type: EventType.CHAT_UPDATE, event: Chat.fromPayload(payload.chat ?? payload) };
+  }
+  if (frame.opcode === Opcode.NOTIF_MSG_DELETE) {
+    const chat = payload.chat ? asRecord(payload.chat) : null;
+    const event: MessageDeleteEvent = {
+      chatId: toMaxId(payload.chatId ?? chat?.id, "delete.chatId"),
+      messageIds: asArray(payload.messageIds).map((id) => toMaxId(id)),
+      chat: chat ? Chat.fromPayload(chat) : null,
+      ttl: asBoolean(payload.ttl),
+    };
+    return { type: EventType.MESSAGE_DELETE, event };
+  }
+  if (frame.opcode === Opcode.NOTIF_TYPING) {
+    const event: TypingEvent = {
+      chatId: toMaxId(payload.chatId),
+      userId: toMaxId(payload.userId),
+      typing: asBoolean(payload.typing, true),
+    };
+    return { type: EventType.TYPING, event };
+  }
+  if (frame.opcode === Opcode.NOTIF_MARK) {
+    const event: MessageReadEvent = {
+      chatId: toMaxId(payload.chatId),
+      userId: optionalMaxId(payload.userId),
+      mark: asNumber(payload.mark),
+    };
+    return { type: EventType.MESSAGE_READ, event };
+  }
+  if (frame.opcode === Opcode.NOTIF_PRESENCE) {
+    const presence = payload.presence ? asRecord(payload.presence) : payload;
+    const event: PresenceEvent = {
+      userId: toMaxId(payload.userId),
+      online: asBoolean(presence.online ?? presence.status === "ONLINE"),
+      lastSeen: presence.lastSeen === undefined ? null : asNumber(presence.lastSeen),
+      raw: presence,
+    };
+    return { type: EventType.PRESENCE, event };
+  }
+  if (frame.opcode === Opcode.NOTIF_MSG_REACTIONS_CHANGED) {
+    const event: ReactionUpdateEvent = {
+      chatId: toMaxId(payload.chatId),
+      messageId: toMaxId(payload.messageId),
+      reactionInfo: parseReactionInfo({
+        totalCount: payload.totalCount,
+        counters: payload.counters,
+        yourReaction: payload.yourReaction,
+      }),
+    };
+    return { type: EventType.REACTION_UPDATE, event };
+  }
+  return null;
+}
+
+function deleteFromMessage(message: Message, payload: Record<string, unknown>): MessageDeleteEvent {
+  if (message.chatId === null) throw new TypeError("Removed message has no chatId");
+  return {
+    chatId: message.chatId,
+    messageIds: [message.id],
+    message,
+    ttl: asBoolean(payload.ttl),
+  };
+}

package/src/dispatch/index.ts

@@ -0,0 +1,2 @@
+export * from "./dispatcher.ts";
+export * from "./router.ts";

package/src/dispatch/router.ts

@@ -0,0 +1,149 @@
+import type { InboundFrame } from "../protocol/index.ts";
+import type {
+  Chat,
+  Message,
+  MessageDeleteEvent,
+  MessageReadEvent,
+  PresenceEvent,
+  ReactionUpdateEvent,
+  TypingEvent,
+} from "../types/index.ts";
+
+export const EventType = {
+  MESSAGE_NEW: "messageNew",
+  MESSAGE_EDIT: "messageEdit",
+  MESSAGE_DELETE: "messageDelete",
+  MESSAGE_READ: "messageRead",
+  TYPING: "typing",
+  PRESENCE: "presence",
+  REACTION_UPDATE: "reactionUpdate",
+  CHAT_UPDATE: "chatUpdate",
+  RAW: "raw",
+} as const;
+export type EventType = (typeof EventType)[keyof typeof EventType];
+
+export interface EventMap {
+  messageNew: Message;
+  messageEdit: Message;
+  messageDelete: MessageDeleteEvent;
+  messageRead: MessageReadEvent;
+  typing: TypingEvent;
+  presence: PresenceEvent;
+  reactionUpdate: ReactionUpdateEvent;
+  chatUpdate: Chat;
+  raw: InboundFrame;
+}
+
+export type MaybePromise<T> = T | Promise<T>;
+export type Handler<Event, Client> = (event: Event, client: Client) => MaybePromise<void>;
+export type Filter<Event> = (event: Event) => MaybePromise<boolean>;
+export type StartHandler<Client> = (client: Client) => MaybePromise<void>;
+export type DisconnectHandler = (
+  error: Error,
+  reconnect: boolean,
+  delay: number,
+) => MaybePromise<void>;
+
+export interface ErrorContext<Client> {
+  client: Client;
+  eventType: EventType | "start";
+  event: unknown;
+  router: Router<Client>;
+}
+export type ErrorHandler<Client> = (
+  error: Error,
+  context: ErrorContext<Client>,
+) => MaybePromise<void>;
+
+interface HandlerEntry<Event, Client> {
+  handler: Handler<Event, Client>;
+  filters: Filter<Event>[];
+}
+
+export class Router<Client> {
+  readonly children: Router<Client>[] = [];
+  readonly handlers = new Map<EventType, HandlerEntry<unknown, Client>[]>();
+  readonly startHandlers: StartHandler<Client>[] = [];
+  readonly errorHandlers: ErrorHandler<Client>[] = [];
+  readonly disconnectHandlers: DisconnectHandler[] = [];
+
+  includeRouter(router: Router<Client>): () => void {
+    this.children.push(router);
+    return () => {
+      const index = this.children.indexOf(router);
+      if (index >= 0) this.children.splice(index, 1);
+    };
+  }
+
+  on<Key extends keyof EventMap>(
+    event: Key,
+    handler: Handler<EventMap[Key], Client>,
+    ...filters: Filter<EventMap[Key]>[]
+  ): () => void {
+    const entry: HandlerEntry<EventMap[Key], Client> = { handler, filters };
+    const entries = (this.handlers.get(event) ?? []) as HandlerEntry<EventMap[Key], Client>[];
+    entries.push(entry);
+    this.handlers.set(event, entries as HandlerEntry<unknown, Client>[]);
+    return () => {
+      const index = entries.indexOf(entry);
+      if (index >= 0) entries.splice(index, 1);
+    };
+  }
+
+  onStart(handler: StartHandler<Client>): () => void {
+    this.startHandlers.push(handler);
+    return () => remove(this.startHandlers, handler);
+  }
+  onError(handler: ErrorHandler<Client>): () => void {
+    this.errorHandlers.push(handler);
+    return () => remove(this.errorHandlers, handler);
+  }
+  onDisconnect(handler: DisconnectHandler): () => void {
+    this.disconnectHandlers.push(handler);
+    return () => remove(this.disconnectHandlers, handler);
+  }
+  onMessage(handler: Handler<Message, Client>, ...filters: Filter<Message>[]): () => void {
+    return this.on("messageNew", handler, ...filters);
+  }
+  onMessageEdit(handler: Handler<Message, Client>, ...filters: Filter<Message>[]): () => void {
+    return this.on("messageEdit", handler, ...filters);
+  }
+  onMessageDelete(
+    handler: Handler<MessageDeleteEvent, Client>,
+    ...filters: Filter<MessageDeleteEvent>[]
+  ): () => void {
+    return this.on("messageDelete", handler, ...filters);
+  }
+  onMessageRead(
+    handler: Handler<MessageReadEvent, Client>,
+    ...filters: Filter<MessageReadEvent>[]
+  ): () => void {
+    return this.on("messageRead", handler, ...filters);
+  }
+  onTyping(handler: Handler<TypingEvent, Client>, ...filters: Filter<TypingEvent>[]): () => void {
+    return this.on("typing", handler, ...filters);
+  }
+  onPresence(
+    handler: Handler<PresenceEvent, Client>,
+    ...filters: Filter<PresenceEvent>[]
+  ): () => void {
+    return this.on("presence", handler, ...filters);
+  }
+  onReactionUpdate(
+    handler: Handler<ReactionUpdateEvent, Client>,
+    ...filters: Filter<ReactionUpdateEvent>[]
+  ): () => void {
+    return this.on("reactionUpdate", handler, ...filters);
+  }
+  onChatUpdate(handler: Handler<Chat, Client>, ...filters: Filter<Chat>[]): () => void {
+    return this.on("chatUpdate", handler, ...filters);
+  }
+  onRaw(handler: Handler<InboundFrame, Client>, ...filters: Filter<InboundFrame>[]): () => void {
+    return this.on("raw", handler, ...filters);
+  }
+}
+
+function remove<T>(values: T[], value: T): void {
+  const index = values.indexOf(value);
+  if (index >= 0) values.splice(index, 1);
+}

package/src/errors.ts

@@ -0,0 +1,41 @@
+export class TsMaxError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+}
+
+export class UploadError extends TsMaxError {}
+export class ConnectionError extends TsMaxError {}
+export class TimeoutError extends TsMaxError {}
+
+export class ApiError extends TsMaxError {
+  readonly payload: Record<string, unknown>;
+
+  constructor(
+    readonly opcode: number,
+    options: {
+      error?: string | null;
+      title?: string | null;
+      message?: string | null;
+      localizedMessage?: string | null;
+      payload?: Record<string, unknown> | null;
+    } = {},
+  ) {
+    const parts: string[] = [];
+    if (options.localizedMessage) parts.push(options.localizedMessage);
+    if (options.message && options.message !== options.localizedMessage)
+      parts.push(options.message);
+    if (options.title) parts.push(`(${options.title})`);
+    if (options.error) parts.push(`[${options.error}]`);
+    super(parts.join(" ") || "API request failed");
+    this.payload = options.payload ?? {};
+    this.error = options.error ?? null;
+    this.title = options.title ?? null;
+    this.localizedMessage = options.localizedMessage ?? null;
+  }
+
+  readonly error: string | null;
+  readonly title: string | null;
+  readonly localizedMessage: string | null;
+}

package/src/files/file.ts

@@ -0,0 +1,92 @@
+import { basename, extname } from "node:path";
+
+export interface FileSource {
+  raw?: Uint8Array;
+  path?: string;
+  url?: string;
+  name?: string;
+}
+
+export class MaxFile {
+  readonly raw: Uint8Array | null;
+  readonly path: string | null;
+  readonly url: string | null;
+  readonly name: string;
+
+  constructor(source: FileSource) {
+    const sources = [source.raw, source.path, source.url].filter((value) => value !== undefined);
+    if (sources.length !== 1)
+      throw new TypeError("Exactly one of raw, path, or url must be provided");
+    this.raw = source.raw ?? null;
+    this.path = source.path ?? null;
+    this.url = source.url ?? null;
+    this.name = source.name ?? inferName(source.path, source.url);
+    if (!this.name) throw new TypeError("A name is required for raw file data");
+  }
+
+  async read(): Promise<Uint8Array> {
+    if (this.raw) return this.raw;
+    if (this.path) return new Uint8Array(await Bun.file(this.path).arrayBuffer());
+    if (this.url) {
+      const response = await fetch(this.url);
+      if (!response.ok) throw new Error(`Failed to download ${this.url}: ${response.status}`);
+      return new Uint8Array(await response.arrayBuffer());
+    }
+    throw new Error("File has no source");
+  }
+
+  async size(): Promise<number> {
+    if (this.raw) return this.raw.byteLength;
+    if (this.path) return Bun.file(this.path).size;
+    if (this.url) {
+      const response = await fetch(this.url, { method: "HEAD" });
+      if (!response.ok) throw new Error(`Failed to inspect ${this.url}: ${response.status}`);
+      const length = response.headers.get("content-length");
+      if (!length) return (await this.read()).byteLength;
+      return Number(length);
+    }
+    throw new Error("File has no source");
+  }
+
+  async *chunks(chunkSize: number): AsyncGenerator<Uint8Array> {
+    if (!Number.isInteger(chunkSize) || chunkSize <= 0)
+      throw new RangeError("chunkSize must be positive");
+    const data = await this.read();
+    for (let offset = 0; offset < data.byteLength; offset += chunkSize) {
+      yield data.slice(offset, offset + chunkSize);
+    }
+  }
+}
+
+export class File extends MaxFile {}
+export class Video extends MaxFile {}
+
+const allowedPhotoExtensions = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"]);
+
+export class Photo extends MaxFile {
+  constructor(source: FileSource) {
+    super(source);
+    const extension = extname(
+      this.url ? new URL(this.url).pathname : (this.path ?? this.name),
+    ).toLowerCase();
+    if (!allowedPhotoExtensions.has(extension)) {
+      throw new TypeError(`Invalid photo extension: ${extension}`);
+    }
+  }
+
+  get format(): { extension: string; mimeType: string } {
+    const extension = extname(this.url ? new URL(this.url).pathname : (this.path ?? this.name))
+      .toLowerCase()
+      .slice(1);
+    const normalized = extension === "jpg" ? "jpeg" : extension;
+    return { extension, mimeType: `image/${normalized}` };
+  }
+}
+
+export type SendAttachment = File | Video | Photo;
+
+function inferName(path?: string, url?: string): string {
+  if (path) return basename(path);
+  if (url) return basename(new URL(url).pathname);
+  return "";
+}

package/src/files/index.ts

@@ -0,0 +1 @@
+export * from "./file.ts";

package/src/formatting/index.ts

@@ -0,0 +1 @@
+export * from "./markdown.ts";