@aspalagin/openclaw-max 0.7.2

package/src/state.ts

@@ -0,0 +1,149 @@
+/**
+ * Persistent per-account MAX state: long-polling marker, chat registry and the
+ * auto-generated webhook secret.
+ *
+ * The marker survives gateway restarts so updates are neither replayed nor
+ * lost past the server-side retention window. The chat registry replaces the
+ * deprecated GET /chats (June 2026): chats are collected from bot_added /
+ * bot_started / chat_title_changed updates and passively from group messages.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { readJsonFileWithFallback, writeJsonFileAtomically } from 'openclaw/plugin-sdk/json-store';
+import { resolveStateDir } from 'openclaw/plugin-sdk/state-paths';
+
+export interface MaxChatRegistryEntry {
+  chatId: number;
+  /** "chat" | "channel" | "dialog" */
+  type?: string;
+  title?: string;
+  addedAt?: number;
+  /** Set when bot_removed / dialog_removed arrives; cleared on re-add */
+  removedAt?: number;
+  /** bot_stopped in a dialog: user halted the bot */
+  stopped?: boolean;
+}
+
+export interface MaxAccountState {
+  marker?: number | null;
+  chats?: Record<string, MaxChatRegistryEntry>;
+  /** Auto-generated webhook secret, kept so a restart re-subscribes with the same one */
+  webhookSecret?: string;
+}
+
+export function resolveMaxStatePath(accountId: string): string {
+  const safeId = accountId.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(resolveStateDir(), 'max', `state-${safeId}.json`);
+}
+
+export async function loadMaxAccountState(accountId: string): Promise<MaxAccountState> {
+  const { value } = await readJsonFileWithFallback<MaxAccountState>(
+    resolveMaxStatePath(accountId),
+    {},
+  );
+  return value && typeof value === 'object' ? value : {};
+}
+
+export async function saveMaxAccountState(
+  accountId: string,
+  state: MaxAccountState,
+): Promise<void> {
+  const filePath = resolveMaxStatePath(accountId);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await writeJsonFileAtomically(filePath, state);
+}
+
+/**
+ * In-memory handle over the persisted state with coalesced writes.
+ * Mutations mark the state dirty; flushes are serialized and best-effort.
+ */
+export class MaxStateStore {
+  private state: MaxAccountState = {};
+  private dirty = false;
+  private flushing: Promise<void> = Promise.resolve();
+  private loaded = false;
+
+  constructor(
+    private accountId: string,
+    private onError?: (err: unknown) => void,
+  ) {}
+
+  async load(): Promise<MaxAccountState> {
+    if (!this.loaded) {
+      this.state = await loadMaxAccountState(this.accountId);
+      this.loaded = true;
+    }
+    return this.state;
+  }
+
+  get marker(): number | null | undefined {
+    return this.state.marker;
+  }
+
+  setMarker(marker: number | null): void {
+    if (this.state.marker === marker) return;
+    this.state.marker = marker;
+    this.scheduleFlush();
+  }
+
+  get webhookSecret(): string | undefined {
+    return this.state.webhookSecret;
+  }
+
+  setWebhookSecret(secret: string): void {
+    if (this.state.webhookSecret === secret) return;
+    this.state.webhookSecret = secret;
+    this.scheduleFlush();
+  }
+
+  get chats(): Record<string, MaxChatRegistryEntry> {
+    if (!this.state.chats) this.state.chats = {};
+    return this.state.chats;
+  }
+
+  upsertChat(chatId: number, patch: Partial<MaxChatRegistryEntry>): void {
+    const key = String(chatId);
+    const existing = this.chats[key];
+    const next: MaxChatRegistryEntry = { ...existing, ...patch, chatId };
+    // A re-appearing chat is no longer removed/stopped unless the patch says so
+    if (
+      patch.removedAt === undefined &&
+      existing?.removedAt !== undefined &&
+      patch.addedAt !== undefined
+    ) {
+      delete next.removedAt;
+    }
+    this.chats[key] = next;
+    this.scheduleFlush();
+  }
+
+  hasChat(chatId: number): boolean {
+    return String(chatId) in this.chats;
+  }
+
+  /** True only if the chat is known AND not marked removed. */
+  hasActiveChat(chatId: number): boolean {
+    const entry = this.chats[String(chatId)];
+    return Boolean(entry) && entry.removedAt == null;
+  }
+
+  private scheduleFlush(): void {
+    this.dirty = true;
+    this.flushing = this.flushing.then(async () => {
+      if (!this.dirty) return;
+      this.dirty = false;
+      try {
+        await saveMaxAccountState(this.accountId, this.state);
+      } catch (err) {
+        this.onError?.(err);
+      }
+    });
+  }
+
+  /** Wait for pending writes (used on shutdown/tests). */
+  async flush(): Promise<void> {
+    await this.flushing;
+  }
+}

package/src/sticker-cache.ts

@@ -0,0 +1,28 @@
+/**
+ * Simple in-memory sticker code cache.
+ * Stores the last received sticker code per chat, so the agent can
+ * send it back without explicitly passing the code.
+ */
+
+const lastStickerByChat = new Map<string, string>();
+const lastStickerGlobal: { code: string | null } = { code: null };
+
+/**
+ * Store a sticker code received from a chat.
+ */
+export function rememberStickerCode(chatId: string | number, code: string): void {
+  const key = String(chatId);
+  lastStickerByChat.set(key, code);
+  lastStickerGlobal.code = code;
+}
+
+/**
+ * Get the last sticker code for a chat, or the last global one.
+ */
+export function getLastStickerCode(chatId?: string | number): string | null {
+  if (chatId != null) {
+    const code = lastStickerByChat.get(String(chatId));
+    if (code) return code;
+  }
+  return lastStickerGlobal.code;
+}

package/src/stream-draft.ts

@@ -0,0 +1,125 @@
+/**
+ * Edit streaming (streamMode "partial"): the first partial reply is sent as a
+ * message, later partials edit it (throttled), and the final answer replaces
+ * the draft together with its inline keyboard.
+ */
+
+import type { ChannelLogSink } from 'openclaw/plugin-sdk/channel-contract';
+
+import type { ResolvedMaxAccount } from './accounts.js';
+import { editMaxMessage, type MaxSendButton, sendMaxMessage } from './send.js';
+
+const DRAFT_THROTTLE_MS = 1200;
+const DRAFT_MAX_CHARS = 4000;
+const DRAFT_MIN_CHARS = 30; // Don't send until we have enough text
+
+export interface MaxDraftStream {
+  /** Mid of the draft message once the first partial was sent. */
+  readonly messageId: string | null;
+  /** Show a partial reply (throttled; stops on errors or past 4000 chars). */
+  update(text: string): Promise<void>;
+  /** Replace the draft with the final text; buttons go onto the same edit. */
+  finalize(text: string, buttons: MaxSendButton[][] | undefined): Promise<void>;
+  /** Cancel a pending update and stop streaming. */
+  clear(): Promise<void>;
+}
+
+/** Draft stream for edit-streaming (like Telegram's partial reply approach). */
+export function createMaxDraftStream(params: {
+  account: ResolvedMaxAccount;
+  chatId: string;
+  replyToId?: string;
+  log?: ChannelLogSink;
+  statusSink?: (patch: { lastOutboundAt?: number }) => void;
+}): MaxDraftStream {
+  const { account, chatId, log, statusSink } = params;
+  let draftMid: string | null = null;
+  let draftLastText = '';
+  let draftLastEditAt = 0;
+  let draftTimer: ReturnType<typeof setTimeout> | null = null;
+  let draftStopped = false;
+
+  const draftUpdate = async (text: string) => {
+    if (draftStopped || !text) return;
+    const trimmed = text.trimEnd();
+    if (!trimmed || trimmed === draftLastText) return;
+    if (trimmed.length > DRAFT_MAX_CHARS) {
+      draftStopped = true;
+      return;
+    }
+    if (!draftMid && trimmed.length < DRAFT_MIN_CHARS) return; // wait for more text
+
+    // Clear pending timer
+    if (draftTimer) {
+      clearTimeout(draftTimer);
+      draftTimer = null;
+    }
+
+    const now = Date.now();
+    const elapsed = now - draftLastEditAt;
+    if (elapsed < DRAFT_THROTTLE_MS) {
+      // Schedule a deferred update
+      draftTimer = setTimeout(() => {
+        draftUpdate(text);
+      }, DRAFT_THROTTLE_MS - elapsed);
+      return;
+    }
+
+    draftLastText = trimmed;
+    draftLastEditAt = now;
+
+    try {
+      if (!draftMid) {
+        // First chunk — send new message
+        const res = await sendMaxMessage(chatId, trimmed, {
+          token: account.token,
+          replyToMessageId: params.replyToId,
+          format: 'markdown',
+        });
+        draftMid = res.messageId || null;
+        statusSink?.({ lastOutboundAt: Date.now() });
+      } else {
+        // Edit existing message
+        await editMaxMessage(draftMid, trimmed, {
+          token: account.token,
+          format: 'markdown',
+        });
+      }
+    } catch (err) {
+      draftStopped = true;
+      log?.debug?.(`[${account.accountId}] MAX draft stream failed: ${String(err)}`);
+    }
+  };
+
+  return {
+    get messageId() {
+      return draftMid;
+    },
+    update: draftUpdate,
+    finalize: async (finalText, buttons) => {
+      // Final delivery replaces the draft message with final text. The
+      // keyboard (presentation buttons) goes onto the same edit, otherwise
+      // the final answer would lose its buttons.
+      if (draftMid && (finalText !== draftLastText || buttons?.length)) {
+        try {
+          await editMaxMessage(draftMid, finalText, {
+            token: account.token,
+            format: 'markdown',
+            buttons,
+          });
+          draftLastText = finalText;
+        } catch {
+          /* best effort */
+        }
+      }
+      draftStopped = true;
+    },
+    clear: async () => {
+      if (draftTimer) {
+        clearTimeout(draftTimer);
+        draftTimer = null;
+      }
+      draftStopped = true;
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,263 @@
+/**
+ * MAX Messenger Bot API — TypeScript type definitions
+ * Based on https://dev.max.ru/docs-api
+ */
+
+// ─── MAX API Client Types (для api.ts) ────────────────────────
+
+export interface MaxUser {
+  user_id: number;
+  first_name: string;
+  last_name?: string | null;
+  username?: string | null;
+  is_bot: boolean;
+  last_activity_time?: number;
+  name?: string | null;
+  description?: string | null;
+  avatar_url?: string;
+  full_avatar_url?: string;
+  commands?: MaxBotCommand[] | null;
+}
+
+export interface MaxChat {
+  chat_id: number;
+  type: 'dialog' | 'chat' | 'channel';
+  status: string;
+  title?: string | null;
+  icon?: { url?: string } | null;
+  last_event_time?: number;
+  participants_count?: number;
+  owner_id?: number;
+  participants?: Record<string, unknown>;
+  is_public?: boolean;
+  link?: string;
+  description?: string | null;
+  dialog_with_user?: MaxUser;
+  messages_count?: number;
+  chat_message_id?: string;
+  pinned_message?: MaxMessage | null;
+}
+
+export interface MaxRecipient {
+  chat_id?: number;
+  chat_type?: string;
+  user_id?: number;
+  /** Post identifier for comments */
+  post_id?: string | null;
+}
+
+export interface MaxMessageBody {
+  mid: string;
+  seq?: number;
+  text?: string | null;
+  attachments?: MaxAttachment[];
+  /** Text markup (MarkupElement[]); user mentions arrive as `user_mention` */
+  markup?: MaxMarkupElement[] | null;
+}
+
+/**
+ * MarkupElement (schema.yaml). `from`/`length` index into `text`. A
+ * `user_mention` carries `user_link` (`@username`) or, for users without a
+ * username, `user_id`; `link` carries `url`.
+ */
+export interface MaxMarkupElement {
+  type: string;
+  from: number;
+  length: number;
+  user_link?: string | null;
+  user_id?: number | null;
+  url?: string;
+}
+
+export interface MaxAttachment {
+  type: string;
+  payload?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface MaxLinkedMessage {
+  type: 'forward' | 'reply';
+  sender?: MaxUser;
+  chat_id?: number;
+  message?: MaxMessage;
+}
+
+export interface MaxUpdatesResponse {
+  updates: MaxUpdate[];
+  marker: number | null;
+}
+
+export interface MaxUploadResult {
+  [key: string]: unknown;
+}
+
+export type MaxUpdateType =
+  | 'message_created'
+  | 'message_callback'
+  | 'message_edited'
+  | 'message_removed'
+  | 'comment_created'
+  | 'comment_edited'
+  | 'comment_removed'
+  | 'bot_added'
+  | 'bot_removed'
+  | 'bot_started'
+  | 'bot_stopped'
+  | 'dialog_cleared'
+  | 'dialog_removed'
+  | 'dialog_muted'
+  | 'dialog_unmuted'
+  | 'user_added'
+  | 'user_removed'
+  | 'chat_title_changed'
+  | 'bot_admin_permissions_changed';
+
+export interface MaxUpdate {
+  update_type: MaxUpdateType;
+  timestamp: number;
+  /** message_callback: the keyboard's message, null when it was deleted */
+  message?: MaxMessage | null;
+  callback?: MaxCallback;
+  chat_id?: number;
+  user?: MaxUser;
+  user_id?: number;
+  inviter_id?: number;
+  /** bot_started deeplink payload / message_removed message_id etc. */
+  payload?: string | null;
+  title?: string;
+  is_channel?: boolean;
+  user_locale?: string | null;
+  [key: string]: unknown;
+}
+
+export interface MaxInlineKeyboardButton {
+  type:
+    | 'callback'
+    | 'link'
+    | 'request_contact'
+    | 'request_geo_location'
+    | 'open_app'
+    | 'message'
+    | 'clipboard';
+  text: string;
+  payload?: string;
+  url?: string;
+  /** open_app: public name of the bot wired to the mini app (required for open_app) */
+  web_app?: string;
+  /** open_app: id of the bot wired to the mini app */
+  contact_id?: number | null;
+}
+
+export interface MaxInlineKeyboardAttachment {
+  type: 'inline_keyboard';
+  payload: {
+    buttons: MaxInlineKeyboardButton[][];
+  };
+}
+
+export interface MaxStickerAttachment {
+  type: 'sticker';
+  payload: {
+    code: string;
+  };
+}
+
+export interface MaxNewMessageBody {
+  text?: string | null;
+  attachments?: (MaxAttachment | MaxInlineKeyboardAttachment | MaxStickerAttachment)[] | null;
+  link?: { type: 'forward' | 'reply'; mid: string } | null;
+  notify?: boolean;
+  format?: 'markdown' | 'html' | null;
+}
+
+export interface MaxBotCommand {
+  name: string;
+  description?: string;
+}
+
+/** PATCH /me/commands response (BotCommandsInfo). */
+export interface MaxBotCommandsInfo {
+  commands?: MaxBotCommand[] | null;
+}
+
+/**
+ * Chat actions (POST /chats/{chatId}/actions).
+ * mark_seen disappeared from the current docs but is still accepted; treat as legacy.
+ */
+export type MaxSenderAction =
+  'typing_on' | 'sending_photo' | 'sending_video' | 'sending_audio' | 'sending_file' | 'mark_seen';
+
+/** GET /chats/{chatId}/members/me */
+export interface MaxChatMember {
+  user_id: number;
+  first_name?: string;
+  last_name?: string | null;
+  username?: string | null;
+  is_bot?: boolean;
+  is_owner?: boolean;
+  is_admin?: boolean;
+  join_time?: number;
+  permissions?: string[] | null;
+}
+
+/** GET /videos/{videoToken} — playback info; urls may be null while processing. */
+export interface MaxVideoInfo {
+  token?: string;
+  urls?: {
+    mp4_1080?: string;
+    mp4_720?: string;
+    mp4_480?: string;
+    mp4_360?: string;
+    mp4_240?: string;
+    mp4_144?: string;
+    hls?: string;
+  } | null;
+  /** PhotoAttachmentPayload */
+  thumbnail?: { url: string; photo_id?: number; token?: string } | null;
+  width?: number;
+  height?: number;
+  duration?: number;
+}
+
+export interface MaxMessage {
+  sender?: MaxUser;
+  recipient: MaxRecipient;
+  timestamp: number;
+  link?: MaxLinkedMessage | null;
+  body: MaxMessageBody;
+  stat?: { views?: number } | null;
+  url?: string | null;
+}
+
+/** Callback object; the keyboard's message arrives next to it in the update, not inside. */
+export interface MaxCallback {
+  timestamp: number;
+  callback_id: string;
+  payload?: string;
+  user: MaxUser;
+}
+
+export interface MaxSendResult {
+  message: MaxMessage;
+}
+
+export interface MaxSimpleResult {
+  success: boolean;
+  message?: string;
+}
+
+/** GET /subscriptions item. The secret is write-only (POST /subscriptions) and never returned. */
+export interface MaxSubscription {
+  url: string;
+  time: number;
+  update_types?: string[] | null;
+}
+
+export interface MaxSubscriptionsResponse {
+  subscriptions: MaxSubscription[];
+}
+
+export interface MaxUploadUrlResponse {
+  url: string;
+  token?: string;
+}