@aspalagin/openclaw-max 0.7.2

package/src/api.ts

@@ -0,0 +1,758 @@
+/**
+ * MAX Bot API client — thin wrapper around platform-api2.max.ru
+ *
+ * API docs: https://dev.max.ru/docs-api
+ * Auth: Authorization header with bot token
+ * Rate limit: 30 rps
+ *
+ * TLS: platform-api2.max.ru serves a certificate issued by the Russian Trusted
+ * (Минцифры) CA, which is not in the default Node trust store. Requests go
+ * through a dedicated undici dispatcher whose CA set = system roots + Russian
+ * Trusted Root/Sub CA. Trust is scoped to this client only, never process-wide.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import * as tls from 'node:tls';
+
+import { retryAsync } from 'openclaw/plugin-sdk/runtime-env';
+import { Agent, buildConnector, fetch as undiciFetch } from 'undici';
+
+import { RUSSIAN_TRUSTED_ROOT_CA, RUSSIAN_TRUSTED_SUB_CA } from './russian-trusted-ca.js';
+import type {
+  MaxBotCommand,
+  MaxBotCommandsInfo,
+  MaxChat,
+  MaxChatMember,
+  MaxMessage,
+  MaxNewMessageBody,
+  MaxSenderAction,
+  MaxSendResult,
+  MaxSimpleResult,
+  MaxSubscriptionsResponse,
+  MaxUpdatesResponse,
+  MaxUpdateType,
+  MaxUploadUrlResponse,
+  MaxUser,
+  MaxVideoInfo,
+} from './types.js';
+
+export type {
+  MaxAttachment,
+  MaxBotCommand,
+  MaxBotCommandsInfo,
+  MaxCallback,
+  MaxChat,
+  MaxChatMember,
+  MaxInlineKeyboardAttachment,
+  MaxInlineKeyboardButton,
+  MaxLinkedMessage,
+  MaxMessage,
+  MaxMessageBody,
+  MaxNewMessageBody,
+  MaxRecipient,
+  MaxSenderAction,
+  MaxSendResult,
+  MaxSimpleResult,
+  MaxStickerAttachment,
+  MaxSubscription,
+  MaxSubscriptionsResponse,
+  MaxUpdate,
+  MaxUpdatesResponse,
+  MaxUpdateType,
+  MaxUploadResult,
+  MaxUploadUrlResponse,
+  MaxUser,
+  MaxVideoInfo,
+} from './types.js';
+
+/**
+ * platform-api.max.ru is shut down on 2026-07-19; platform-api2.max.ru is the
+ * canonical endpoint since June 2026.
+ */
+const BASE_URL = 'https://platform-api2.max.ru';
+
+/**
+ * Default per-request deadline. Raised from 10s after an intermittent in-process
+ * stall aborted sends at exactly 10s ("This operation was aborted") while the
+ * same request from a fresh process completed in <300ms. The long poll sets its
+ * own (longer) timeout, so this only bounds one-shot calls like send/edit/get.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** Round trips slower than this are logged, to fingerprint a stalling path. */
+const MAX_SLOW_REQUEST_MS = 5_000;
+
+/** New connections whose DNS+TCP+TLS exceeds this are logged. */
+const MAX_SLOW_CONNECT_MS = 2_000;
+
+// ────────────────────── HTTP transport ──────────────────────
+
+type FetchLike = (
+  url: string,
+  init?: Record<string, unknown>,
+) => Promise<{
+  ok: boolean;
+  status: number;
+  headers?: { get(name: string): string | null };
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}>;
+
+let testFetchOverride: FetchLike | undefined;
+
+/**
+ * Test seam: route all MAX HTTP through the given fetch (e.g. a vi.fn or a
+ * passthrough to a mocked globalThis.fetch). Pass undefined to restore.
+ */
+export function setMaxFetchForTests(fetchImpl: FetchLike | undefined): void {
+  testFetchOverride = fetchImpl;
+}
+
+let cachedDispatcher: Agent | undefined;
+
+function getMaxDispatcher(): Agent {
+  if (!cachedDispatcher) {
+    const tlsWithCaList = tls as unknown as {
+      getCACertificates?: (type: string) => readonly string[];
+    };
+    // getCACertificates("default") includes NODE_EXTRA_CA_CERTS additions when available
+    const systemCas = tlsWithCaList.getCACertificates?.('default') ?? tls.rootCertificates;
+    const ca = [...systemCas, RUSSIAN_TRUSTED_ROOT_CA, RUSSIAN_TRUSTED_SUB_CA];
+    // Wrap the TLS connector to time the DNS+TCP+TLS phase, scoped to this
+    // dispatcher only (never process-wide). Diagnosing the intermittent
+    // "This operation was aborted" needs to separate a connect stall from a
+    // response-wait stall; a slow or failed connect leaves a fingerprint here.
+    const connect = buildConnector({ ca });
+    type Connect = typeof connect;
+    const timedConnect: Connect = (options, callback) => {
+      const startedAt = Date.now();
+      connect(options, (...args: Parameters<Parameters<Connect>[1]>) => {
+        const err = args[0];
+        const elapsedMs = Date.now() - startedAt;
+        if (err || elapsedMs > MAX_SLOW_CONNECT_MS) {
+          console.error(
+            `[MAX API] connect ${options.hostname} ${err ? 'failed' : 'slow'} dns+tcp+tls=${elapsedMs}ms` +
+              (err ? ` (${err.name})` : ''),
+          );
+        }
+        callback(...args);
+      });
+    };
+    cachedDispatcher = new Agent({ connect: timedConnect });
+  }
+  return cachedDispatcher;
+}
+
+function maxFetch(url: string, init: Record<string, unknown>): ReturnType<FetchLike> {
+  if (testFetchOverride) return testFetchOverride(url, init);
+  return undiciFetch(url, {
+    ...init,
+    dispatcher: getMaxDispatcher(),
+  } as Parameters<typeof undiciFetch>[1]) as unknown as ReturnType<FetchLike>;
+}
+
+function escapeMultipartHeaderValue(value: string): string {
+  return value
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/[\r\n]/g, '_');
+}
+
+function buildMultipartFileBody(
+  fieldName: string,
+  fileName: string,
+  mimeType: string,
+  fileBuffer: Buffer,
+): { body: Buffer; contentType: string } {
+  const boundary = `----openclaw-max-${randomBytes(12).toString('hex')}`;
+  const escapedField = escapeMultipartHeaderValue(fieldName);
+  const escapedFile = escapeMultipartHeaderValue(fileName);
+  const preamble = Buffer.from(
+    `--${boundary}\r\n` +
+      `Content-Disposition: form-data; name="${escapedField}"; filename="${escapedFile}"\r\n` +
+      `Content-Type: ${mimeType}\r\n\r\n`,
+  );
+  const closing = Buffer.from(`\r\n--${boundary}--\r\n`);
+
+  return {
+    body: Buffer.concat([preamble, fileBuffer, closing]),
+    contentType: `multipart/form-data; boundary=${boundary}`,
+  };
+}
+
+// ────────────────────── API Client ──────────────────────
+
+export interface MaxApiOptions {
+  token: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  /** Retry attempts for transient errors (429 / 502-504 / network). 0 disables. Default 3. */
+  retryAttempts?: number;
+  /** Per-chat send limiter for POST /messages; defaults to the process-wide one, null disables. */
+  sendLimiter?: MaxChatSendLimiter | null;
+}
+
+/** MAX docs (POST /messages): at most 2 messages per second into one dialog, chat or channel. */
+export const MAX_SENDS_PER_CHAT_PER_SECOND = 2;
+
+/**
+ * Sliding-window limiter for sends into one chat. Callers for the same key are
+ * served in order; a caller over the limit waits until the oldest send in the
+ * window is a full window old. Keys are independent, long polling and other
+ * requests never pass through it.
+ */
+export class MaxChatSendLimiter {
+  private recent = new Map<string, number[]>();
+  private tails = new Map<string, Promise<void>>();
+
+  constructor(
+    private limit = MAX_SENDS_PER_CHAT_PER_SECOND,
+    private windowMs = 1000,
+  ) {}
+
+  acquire(key: string): Promise<void> {
+    const take = async (): Promise<void> => {
+      for (;;) {
+        const now = Date.now();
+        const times = (this.recent.get(key) ?? []).filter((t) => now - t < this.windowMs);
+        if (times.length < this.limit) {
+          times.push(now);
+          this.recent.set(key, times);
+          return;
+        }
+        this.recent.set(key, times);
+        await new Promise((resolve) => setTimeout(resolve, times[0] + this.windowMs - now));
+      }
+    };
+    const slot = (this.tails.get(key) ?? Promise.resolve()).then(take);
+    this.tails.set(key, slot);
+    void slot.finally(() => {
+      if (this.tails.get(key) === slot) this.tails.delete(key);
+    });
+    if (this.recent.size > 1000) this.prune();
+    return slot;
+  }
+
+  private prune(): void {
+    const now = Date.now();
+    for (const [key, times] of this.recent) {
+      if (!this.tails.has(key) && times.every((t) => now - t >= this.windowMs))
+        this.recent.delete(key);
+    }
+  }
+}
+
+let sharedSendLimiter = new MaxChatSendLimiter();
+
+/** @internal Fresh process-wide send limiter (test isolation). */
+export function resetMaxSendLimiterForTests(): void {
+  sharedSendLimiter = new MaxChatSendLimiter();
+}
+
+export class MaxApiError extends Error {
+  /** MAX error code from the response body, e.g. "attachment.not.ready" */
+  public code?: string;
+  /** Parsed Retry-After (ms), when the response carried one */
+  public retryAfterMs?: number;
+
+  constructor(
+    message: string,
+    public status: number,
+    public body?: unknown,
+  ) {
+    super(message);
+    this.name = 'MaxApiError';
+    if (body && typeof body === 'object') {
+      const code = (body as Record<string, unknown>).code;
+      if (typeof code === 'string') this.code = code;
+    }
+  }
+}
+
+/**
+ * A request that hit the client-side deadline (our AbortController), as opposed
+ * to a caller-supplied stop signal. Carries the stalled phase so the send path
+ * can decide whether one retry on a fresh connection is safe.
+ */
+export class MaxRequestTimeoutError extends Error {
+  constructor(
+    public method: string,
+    public path: string,
+    public elapsedMs: number,
+    public phase: 'awaiting-response' | 'reading-body',
+  ) {
+    super(`MAX API ${method} ${path} timed out after ${elapsedMs}ms (phase=${phase})`);
+    this.name = 'MaxRequestTimeoutError';
+  }
+}
+
+/**
+ * Whether an error is safe to retry. `idempotent` gates the ambiguous cases:
+ * for non-idempotent calls (POST /messages, POST /answers) a 5xx or network
+ * failure may mean the request WAS applied server-side, so retrying would
+ * duplicate the message — only a definite 429 (never applied) is retried.
+ */
+function isRetryableError(err: unknown, idempotent: boolean): boolean {
+  // A client-side timeout is safe to retry only for idempotent methods here; the
+  // send path handles its own single, duplicate-safe retry for POST /messages.
+  if (err instanceof MaxRequestTimeoutError) return idempotent;
+  if (err instanceof MaxApiError) {
+    if (err.status === 429) return true; // rate-limited: request was rejected, safe to retry
+    // 500 excluded everywhere: the request may have been applied.
+    if (err.status === 502 || err.status === 503 || err.status === 504) return idempotent;
+    return false;
+  }
+  if (err instanceof Error && err.name === 'AbortError') return false;
+  // undici network-level failure (fetch failed, ECONNRESET, socket hang up…):
+  // ambiguous — the request may have reached the server, so retry only if idempotent.
+  return idempotent && (err instanceof TypeError || err instanceof Error);
+}
+
+const IDEMPOTENT_METHODS = new Set(['GET', 'PUT', 'DELETE']);
+
+export class MaxApi {
+  private token: string;
+  private baseUrl: string;
+  private timeoutMs: number;
+  private retryAttempts: number;
+  private sendLimiter: MaxChatSendLimiter | null;
+  /** Limiter key prefix: the same chat under two bots has two budgets. */
+  private tokenKey: string;
+
+  constructor(opts: MaxApiOptions) {
+    this.token = opts.token;
+    this.sendLimiter = opts.sendLimiter === undefined ? sharedSendLimiter : opts.sendLimiter;
+    this.tokenKey = createHash('sha256').update(opts.token).digest('hex').slice(0, 12);
+    this.baseUrl = opts.baseUrl ?? BASE_URL;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const envAttempts = Number(process.env.OPENCLAW_MAX_RETRY_ATTEMPTS);
+    this.retryAttempts =
+      opts.retryAttempts ?? (Number.isFinite(envAttempts) && envAttempts >= 0 ? envAttempts : 3);
+  }
+
+  // ── HTTP helpers ──
+
+  private async requestOnce<T>(
+    method: string,
+    path: string,
+    params?: Record<string, string | number | boolean | undefined | null>,
+    body?: unknown,
+    timeoutMs?: number,
+    externalSignal?: AbortSignal,
+  ): Promise<T> {
+    const url = new URL(path, this.baseUrl);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v != null) url.searchParams.set(k, String(v));
+      }
+    }
+
+    const controller = new AbortController();
+    let timedOutByUs = false;
+    let gotResponse = false;
+    const startedAt = Date.now();
+    const timeout = setTimeout(() => {
+      timedOutByUs = true;
+      controller.abort();
+    }, timeoutMs ?? this.timeoutMs);
+    // A caller-supplied signal (the channel stop) must cancel the in-flight
+    // request, not just be polled between requests: a 35s long poll otherwise
+    // keeps running long after the gateway asked the channel to stop.
+    const signal = externalSignal
+      ? AbortSignal.any([controller.signal, externalSignal])
+      : controller.signal;
+
+    try {
+      const res = await maxFetch(url.toString(), {
+        method,
+        headers: {
+          Authorization: this.token,
+          ...(body ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal,
+      });
+      gotResponse = true;
+
+      const json = (await res.json().catch(() => null)) as T;
+
+      const elapsedMs = Date.now() - startedAt;
+      // The long poll blocks server-side for its `timeout` seconds by design, so
+      // it is excluded here; every other call reaching the server slowly is a
+      // fingerprint that points away from a connect hang.
+      if (elapsedMs > MAX_SLOW_REQUEST_MS && path !== '/updates') {
+        console.error(`[MAX API] ${method} ${path} slow: ${elapsedMs}ms (status ${res.status})`);
+      }
+
+      if (!res.ok) {
+        // Never log the request body: it may carry the webhook secret (POST
+        // /subscriptions) or private message text. Log only method+path+status.
+        console.error(`[MAX API] ${method} ${path} → ${res.status}`);
+        const error = new MaxApiError(
+          `MAX API ${method} ${path} → ${res.status}`,
+          res.status,
+          json,
+        );
+        const retryAfter = res.headers?.get?.('retry-after');
+        if (retryAfter) {
+          const seconds = Number(retryAfter);
+          if (Number.isFinite(seconds) && seconds > 0) error.retryAfterMs = seconds * 1000;
+        }
+        throw error;
+      }
+
+      return json;
+    } catch (err) {
+      const elapsedMs = Date.now() - startedAt;
+      const isAbort = err instanceof Error && err.name === 'AbortError';
+      if (timedOutByUs && isAbort) {
+        // Our own deadline fired (not the caller's stop signal). Convert the
+        // opaque "This operation was aborted" into a typed, loggable timeout
+        // that records whether a response had started.
+        const phase = gotResponse ? 'reading-body' : 'awaiting-response';
+        console.error(
+          `[MAX API] ${method} ${path} timed out after ${elapsedMs}ms (phase=${phase})`,
+        );
+        throw new MaxRequestTimeoutError(method, path, elapsedMs, phase);
+      }
+      if (!isAbort && !(err instanceof MaxApiError)) {
+        // Network-level failure (DNS/TCP/TLS/reset): record timing so a connect
+        // stall is distinguishable from a response-wait stall in the log.
+        console.error(
+          `[MAX API] ${method} ${path} failed after ${elapsedMs}ms: ${(err as Error).name}`,
+        );
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    params?: Record<string, string | number | boolean | undefined | null>,
+    body?: unknown,
+    timeoutMs?: number,
+    retryAttempts?: number,
+    externalSignal?: AbortSignal,
+  ): Promise<T> {
+    const attempts = retryAttempts ?? this.retryAttempts;
+    if (attempts <= 1) {
+      return this.requestOnce<T>(method, path, params, body, timeoutMs, externalSignal);
+    }
+    const idempotent = IDEMPOTENT_METHODS.has(method);
+    return retryAsync(
+      () => this.requestOnce<T>(method, path, params, body, timeoutMs, externalSignal),
+      {
+        attempts,
+        minDelayMs: 500,
+        maxDelayMs: 5_000,
+        label: `MAX ${method} ${path}`,
+        shouldRetry: (err) => isRetryableError(err, idempotent),
+        retryAfterMs: (err) => (err instanceof MaxApiError ? err.retryAfterMs : undefined),
+      },
+    );
+  }
+
+  // ── Bot info ──
+
+  async getMe(): Promise<MaxUser> {
+    return this.request<MaxUser>('GET', '/me');
+  }
+
+  // ── Messages ──
+
+  async sendMessage(
+    body: MaxNewMessageBody,
+    params: { chat_id?: number; user_id?: number; disable_link_preview?: boolean },
+  ): Promise<MaxSendResult> {
+    const chat = params.chat_id != null ? `c${params.chat_id}` : `u${params.user_id}`;
+    await this.sendLimiter?.acquire(`${this.tokenKey}:${chat}`);
+    return this.request<MaxSendResult>(
+      'POST',
+      '/messages',
+      params as Record<string, string | number>,
+      body,
+    );
+  }
+
+  async editMessage(messageId: string, body: MaxNewMessageBody): Promise<MaxSimpleResult> {
+    return this.request<MaxSimpleResult>('PUT', '/messages', { message_id: messageId }, body);
+  }
+
+  async deleteMessage(messageId: string): Promise<MaxSimpleResult> {
+    return this.request<MaxSimpleResult>('DELETE', '/messages', { message_id: messageId });
+  }
+
+  /**
+   * List messages in a chat, newest first (GET /messages). `before`/`after` are
+   * Unix-time bounds in ms; they replace the deprecated `from`/`to`.
+   */
+  async getMessages(
+    chatId: number,
+    params?: {
+      message_ids?: string[];
+      before?: number;
+      after?: number;
+      count?: number;
+    },
+  ): Promise<{ messages: MaxMessage[] }> {
+    const qp: Record<string, string | number> = { chat_id: chatId };
+    if (params?.message_ids) qp.message_ids = params.message_ids.join(',');
+    if (params?.before != null) qp.before = params.before;
+    if (params?.after != null) qp.after = params.after;
+    if (params?.count) qp.count = params.count;
+    return this.request('GET', '/messages', qp);
+  }
+
+  /** Get a single message by its mid (GET /messages/{messageId}); 404 if gone or inaccessible. */
+  async getMessageById(messageId: string): Promise<MaxMessage> {
+    return this.request<MaxMessage>('GET', `/messages/${encodeURIComponent(messageId)}`);
+  }
+
+  // ── Chats ──
+
+  /** Get chat info by numeric id (GET /chats/{chatId}). */
+  async getChat(chatId: number): Promise<MaxChat> {
+    return this.request('GET', `/chats/${chatId}`);
+  }
+
+  /** Bot's own membership in a chat — is_admin matters: long polling delivers group updates only to admin bots. */
+  async getMembership(chatId: number): Promise<MaxChatMember> {
+    return this.request('GET', `/chats/${chatId}/members/me`);
+  }
+
+  // ── Pinned messages ──
+
+  async getPinnedMessage(chatId: number): Promise<{ message?: MaxMessage | null }> {
+    return this.request('GET', `/chats/${chatId}/pin`);
+  }
+
+  async pinMessage(chatId: number, messageId: string, notify?: boolean): Promise<MaxSimpleResult> {
+    return this.request('PUT', `/chats/${chatId}/pin`, undefined, {
+      message_id: messageId,
+      ...(notify != null ? { notify } : {}),
+    });
+  }
+
+  async unpinMessage(chatId: number): Promise<MaxSimpleResult> {
+    return this.request('DELETE', `/chats/${chatId}/pin`);
+  }
+
+  // ── Chat actions ──
+
+  async sendAction(chatId: number, action: MaxSenderAction): Promise<MaxSimpleResult> {
+    return this.request('POST', `/chats/${chatId}/actions`, undefined, { action });
+  }
+
+  // ── Callbacks ──
+
+  async answerCallback(
+    callbackId: string,
+    body?: { message?: MaxNewMessageBody; notification?: string },
+  ): Promise<MaxSimpleResult> {
+    return this.request('POST', '/answers', { callback_id: callbackId }, body);
+  }
+
+  // ── Updates (long polling) ──
+
+  async getUpdates(params?: {
+    limit?: number;
+    timeout?: number;
+    marker?: number | null;
+    types?: MaxUpdateType[];
+    /** Channel stop signal — aborts the in-flight long poll immediately. */
+    signal?: AbortSignal;
+  }): Promise<MaxUpdatesResponse> {
+    const qp: Record<string, string | number> = {};
+    if (params?.limit) qp.limit = params.limit;
+    if (params?.timeout != null) qp.timeout = params.timeout;
+    if (params?.marker != null) qp.marker = params.marker;
+    if (params?.types?.length) qp.types = params.types.join(',');
+
+    // Long polling needs a longer timeout; the polling loop owns retries
+    const pollTimeout = ((params?.timeout ?? 30) + 5) * 1000;
+    return this.request('GET', '/updates', qp, undefined, pollTimeout, 0, params?.signal);
+  }
+
+  // ── Videos ──
+
+  /** Playback info for an inbound video attachment (GET /videos/{videoToken}). */
+  async getVideoInfo(videoToken: string): Promise<MaxVideoInfo> {
+    return this.request('GET', `/videos/${encodeURIComponent(videoToken)}`);
+  }
+
+  // ── Subscriptions (webhooks) ──
+
+  async getSubscriptions(): Promise<MaxSubscriptionsResponse> {
+    return this.request('GET', '/subscriptions');
+  }
+
+  async subscribe(params: {
+    url: string;
+    update_types?: string[];
+    secret?: string;
+  }): Promise<MaxSimpleResult> {
+    return this.request('POST', '/subscriptions', undefined, params);
+  }
+
+  async unsubscribe(subscriptionUrl: string): Promise<MaxSimpleResult> {
+    return this.request('DELETE', '/subscriptions', { url: subscriptionUrl });
+  }
+
+  // ── Commands ──
+
+  /**
+   * Replace the bot command list (PATCH /me/commands; PATCH /me answers 404).
+   * Limits: 32 commands, name ≤ 64 chars (no leading slash), description ≤ 128 chars.
+   */
+  async setMyCommands(commands: MaxBotCommand[]): Promise<MaxBotCommandsInfo> {
+    const normalized = commands
+      .map((cmd) => ({
+        name: cmd.name.replace(/^\//, '').slice(0, 64),
+        ...(cmd.description ? { description: cmd.description.slice(0, 128) } : {}),
+      }))
+      .filter((cmd) => cmd.name.length > 0)
+      .slice(0, 32);
+    return this.request<MaxBotCommandsInfo>('PATCH', '/me/commands', undefined, {
+      commands: normalized,
+    });
+  }
+
+  // ── Upload ──
+
+  async getUploadUrl(type: 'image' | 'video' | 'audio' | 'file'): Promise<MaxUploadUrlResponse> {
+    return this.request('POST', `/uploads`, { type });
+  }
+
+  /**
+   * Upload media file to MAX.
+   * MAX upload requires multipart/form-data with field "data".
+   * Response contains a token (in photos/videos/etc) to use in attachments.
+   *
+   * @param type Media type (image, video, audio, file)
+   * @param data File path (string) or buffer (Buffer/Uint8Array)
+   * @param contentType MIME type (optional, auto-detected for common types)
+   * @returns Upload result with token (for use in attachment payload)
+   */
+  async uploadMedia(
+    type: 'image' | 'video' | 'audio' | 'file',
+    data: string | Buffer | Uint8Array,
+    contentType?: string,
+  ): Promise<{ token: string; url?: string }> {
+    // Step 1: Get upload URL and attachment token.
+    // MAX returns the attachment token together with the upload URL. The
+    // following upload host may answer with XML like `<retval>1</retval>` and
+    // does not repeat that token.
+    const uploadInfo = await this.getUploadUrl(type);
+    const uploadUrl = uploadInfo.url;
+
+    // Step 2: Load file if data is a path
+    let fileBuffer: Buffer;
+    let mimeType = contentType;
+    let fileName = 'file';
+
+    if (typeof data === 'string') {
+      // File path — read from disk
+      const fs = await import('fs/promises');
+      const path = await import('path');
+      fileBuffer = await fs.readFile(data);
+      fileName = path.basename(data);
+
+      // Auto-detect MIME type if not provided
+      if (!mimeType) {
+        const ext = data.split('.').pop()?.toLowerCase();
+        const mimeMap: Record<string, string> = {
+          jpg: 'image/jpeg',
+          jpeg: 'image/jpeg',
+          png: 'image/png',
+          gif: 'image/gif',
+          webp: 'image/webp',
+          heic: 'image/heic',
+          heif: 'image/heif',
+          tif: 'image/tiff',
+          tiff: 'image/tiff',
+          bmp: 'image/bmp',
+          mp4: 'video/mp4',
+          mov: 'video/quicktime',
+          avi: 'video/x-msvideo',
+          mkv: 'video/x-matroska',
+          webm: 'video/webm',
+          mp3: 'audio/mpeg',
+          wav: 'audio/wav',
+          ogg: 'audio/ogg',
+          m4a: 'audio/mp4',
+          aac: 'audio/aac',
+          flac: 'audio/flac',
+          opus: 'audio/opus',
+          pdf: 'application/pdf',
+          txt: 'text/plain',
+        };
+        mimeType = ext ? mimeMap[ext] : 'application/octet-stream';
+      }
+    } else {
+      // Already a buffer
+      fileBuffer = Buffer.from(data);
+      mimeType = mimeType ?? 'application/octet-stream';
+    }
+
+    // Step 3: POST file as multipart/form-data to upload URL. MAX upload hosts
+    // reject Node's native FormData in some cases with 412, while curl-style
+    // multipart with a known Content-Length is accepted.
+    const multipart = buildMultipartFileBody('data', fileName, mimeType, fileBuffer);
+
+    const uploadRes = await maxFetch(uploadUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': multipart.contentType,
+        'Content-Length': String(multipart.body.byteLength),
+      },
+      body: multipart.body,
+    });
+
+    if (!uploadRes.ok) {
+      throw new MaxApiError(
+        `MAX media upload failed: ${uploadRes.status}`,
+        uploadRes.status,
+        await uploadRes.text().catch(() => null),
+      );
+    }
+
+    // Step 4: Parse response to extract token
+    // Image response: { photos: { "<id>": { token: "...", url: "..." } } }
+    // Video/audio/file may respond with a top-level token or a similar nested map
+    const result = (await uploadRes.json().catch(() => ({}))) as Record<string, unknown>;
+
+    // Try to find token from nested response structure
+    let token = typeof uploadInfo.token === 'string' ? uploadInfo.token : '';
+    let url: string | undefined;
+
+    let foundNested = false;
+    const nestedContainers = ['photos', 'videos', 'audios', 'files'] as const;
+    for (const key of nestedContainers) {
+      const container = result[key];
+      if (container && typeof container === 'object' && !Array.isArray(container)) {
+        const first = Object.values(
+          container as Record<string, { token?: string; url?: string }>,
+        )[0];
+        if (first?.token) {
+          token = first.token;
+          url = first.url;
+          foundNested = true;
+          break;
+        }
+      }
+    }
+    if (!foundNested && result.token && typeof result.token === 'string') {
+      token = result.token;
+      url = (result.url as string) ?? undefined;
+    }
+
+    if (!token) {
+      throw new MaxApiError('MAX media upload: no token in response', 200, result);
+    }
+
+    return { token, url };
+  }
+}