@aspalagin/openclaw-max 0.7.2

package/dist/src/webhook.js

@@ -0,0 +1,196 @@
+/**
+ * MAX webhook transport — HTTP ingress on the gateway server and the
+ * subscription lifecycle (GET/POST/DELETE /subscriptions).
+ *
+ * The route is registered dynamically from the account lifecycle through
+ * `registerPluginHttpRoute` (plugin-sdk/webhook-ingress): it lives exactly as
+ * long as the account task, carries plugin-managed auth (the MAX shared
+ * secret), and a failed registration fails the account start instead of
+ * reporting ready without live ingress.
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { normalizeWebhookPath, readJsonWebhookBodyOrReject, registerPluginHttpRoute, resolveWebhookPath, } from 'openclaw/plugin-sdk/webhook-ingress';
+/** Plugin id from openclaw.plugin.json — the owner of the gateway route. */
+export const MAX_PLUGIN_ID = 'openclaw-max';
+/** Stable same-plugin route sub-owner (see gateway-routes docs). */
+export const MAX_WEBHOOK_ROUTE_SOURCE = 'max-webhook';
+export const DEFAULT_MAX_WEBHOOK_PATH = '/max/webhook';
+/** Header MAX sends with the subscription secret. */
+const SECRET_HEADER = 'x-max-bot-api-secret';
+const DEDUPE_CAPACITY = 1000;
+function secretsMatch(expected, provided) {
+    const a = Buffer.from(expected);
+    const b = Buffer.from(provided);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+const webhookTargets = new Map();
+export function resolveMaxWebhookPath(webhookPath, webhookUrl) {
+    return (resolveWebhookPath({ webhookPath, webhookUrl, defaultPath: DEFAULT_MAX_WEBHOOK_PATH }) ??
+        DEFAULT_MAX_WEBHOOK_PATH);
+}
+export function registerMaxWebhookTarget(target) {
+    const key = normalizeWebhookPath(target.path);
+    const normalizedTarget = { ...target, path: key, seen: new Map() };
+    webhookTargets.set(key, [...(webhookTargets.get(key) ?? []), normalizedTarget]);
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        const updated = (webhookTargets.get(key) ?? []).filter((entry) => entry !== normalizedTarget);
+        if (updated.length > 0) {
+            webhookTargets.set(key, updated);
+        }
+        else {
+            webhookTargets.delete(key);
+        }
+    };
+}
+/**
+ * Register the gateway HTTP route for a webhook path. Canonically equal paths
+ * of several accounts share one route: the handler picks the target by secret.
+ */
+export function registerMaxWebhookRoute(params) {
+    const register = params.register ?? registerPluginHttpRoute;
+    return register({
+        path: normalizeWebhookPath(params.path),
+        auth: 'plugin',
+        match: 'exact',
+        pluginId: MAX_PLUGIN_ID,
+        source: MAX_WEBHOOK_ROUTE_SOURCE,
+        accountId: params.accountId,
+        replaceExisting: true,
+        throwOnFailure: true,
+        log: params.log,
+        handler: handleMaxWebhookRequest,
+    });
+}
+/**
+ * Key for redelivery dedupe: MAX retries a delivery that was not acknowledged
+ * with 200 in time, so the same update can arrive twice.
+ * @internal exported for testing.
+ */
+export function maxUpdateDedupeKey(update) {
+    const id = update.callback?.callback_id ??
+        update.message?.body?.mid ??
+        (typeof update.message_id === 'string' ? update.message_id : undefined);
+    if (!id && update.timestamp == null)
+        return undefined;
+    return `${update.update_type}:${update.timestamp ?? ''}:${id ?? ''}`;
+}
+/** Returns true when the key was already seen (LRU bounded by DEDUPE_CAPACITY). */
+function rememberUpdate(seen, key) {
+    if (seen.has(key)) {
+        seen.delete(key);
+        seen.set(key, true);
+        return true;
+    }
+    seen.set(key, true);
+    if (seen.size > DEDUPE_CAPACITY) {
+        const oldest = seen.keys().next().value;
+        if (oldest !== undefined)
+            seen.delete(oldest);
+    }
+    return false;
+}
+export async function handleMaxWebhookRequest(req, res) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const path = normalizeWebhookPath(url.pathname);
+    const targets = webhookTargets.get(path);
+    if (!targets || targets.length === 0) {
+        return false;
+    }
+    if (req.method !== 'POST') {
+        res.statusCode = 405;
+        res.setHeader('Allow', 'POST');
+        res.end('Method Not Allowed');
+        return true;
+    }
+    // Authenticate before reading the body. Targets without a secret never
+    // match: an unauthenticated webhook would let anyone inject updates.
+    const rawSecret = req.headers[SECRET_HEADER];
+    const providedSecret = Array.isArray(rawSecret) ? (rawSecret[0] ?? '') : (rawSecret ?? '');
+    const matchedTarget = providedSecret
+        ? targets.find((target) => target.secret && secretsMatch(target.secret, providedSecret))
+        : undefined;
+    if (!matchedTarget) {
+        res.statusCode = 401;
+        res.end('Unauthorized');
+        return true;
+    }
+    // Size/timeout/closed-connection/malformed-JSON failures are answered by the
+    // SDK helper (413/408/400) — it has already written the response.
+    const body = await readJsonWebhookBodyOrReject({
+        req,
+        res,
+        maxBytes: 1024 * 1024,
+        timeoutMs: 30_000,
+        emptyObjectOnEmpty: false,
+        invalidJsonMessage: 'invalid payload',
+    });
+    if (!body.ok) {
+        return true;
+    }
+    const raw = body.value;
+    if (!raw ||
+        typeof raw !== 'object' ||
+        Array.isArray(raw) ||
+        typeof raw.update_type !== 'string') {
+        res.statusCode = 400;
+        res.end('invalid payload');
+        return true;
+    }
+    const update = raw;
+    // MAX needs 200 within 30 s while an agent turn can take minutes: ack first,
+    // then hand the update to the account task. Errors are logged, never turned
+    // into a non-200 (that would only make MAX redeliver and eventually
+    // unsubscribe the bot). onUpdate must only enqueue: this request's work
+    // admission is released when the handler returns, so agent/session work
+    // started from here would fail with GatewayDrainingError.
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ ok: true }));
+    const dedupeKey = maxUpdateDedupeKey(update);
+    if (dedupeKey && rememberUpdate(matchedTarget.seen, dedupeKey)) {
+        matchedTarget.log?.(`[${matchedTarget.account.accountId}] MAX webhook: duplicate ${dedupeKey} skipped`);
+        return true;
+    }
+    void Promise.resolve()
+        .then(() => matchedTarget.onUpdate(update))
+        .catch((err) => {
+        matchedTarget.error?.(`[${matchedTarget.account.accountId}] Webhook update processing failed: ${String(err)}`);
+    });
+    return true;
+}
+/**
+ * Subscribe to MAX webhook
+ */
+export async function subscribeMaxWebhook(params) {
+    const { api, webhookUrl, secret, updateTypes } = params;
+    await api.subscribe({
+        url: webhookUrl,
+        update_types: updateTypes ?? [
+            'message_created',
+            'message_callback',
+            'message_edited',
+            'message_removed',
+            'bot_started',
+            'bot_stopped',
+            'bot_added',
+            'bot_removed',
+            'dialog_cleared',
+            'dialog_removed',
+            'chat_title_changed',
+        ],
+        secret,
+    });
+}
+/**
+ * Unsubscribe from MAX webhook
+ */
+export async function unsubscribeMaxWebhook(params) {
+    const { api, webhookUrl } = params;
+    await api.unsubscribe(webhookUrl);
+}

package/openclaw.plugin.json

@@ -0,0 +1,263 @@
+{
+  "id": "openclaw-max",
+  "name": "MAX",
+  "description": "MAX messenger channel plugin (max.ru Bot API via platform-api2.max.ru, long polling or webhook)",
+  "version": "0.7.2",
+  "channels": [
+    "max"
+  ],
+  "channelEnvVars": {
+    "max": [
+      "MAX_BOT_TOKEN"
+    ]
+  },
+  "channelConfigs": {
+    "max": {
+      "schema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "definitions": {
+          "allowList": {
+            "type": "array",
+            "items": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                }
+              ]
+            }
+          },
+          "groupConfig": {
+            "type": "object",
+            "properties": {
+              "requireMention": {
+                "type": "boolean"
+              },
+              "tools": {
+                "type": "object"
+              },
+              "skills": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "enabled": {
+                "type": "boolean"
+              },
+              "allowFrom": {
+                "$ref": "#/definitions/allowList"
+              },
+              "systemPrompt": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "accountConfig": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "enabled": {
+                "type": "boolean"
+              },
+              "markdown": {
+                "type": "object"
+              },
+              "botToken": {
+                "type": "string"
+              },
+              "tokenFile": {
+                "type": "string"
+              },
+              "dmPolicy": {
+                "type": "string",
+                "enum": [
+                  "pairing",
+                  "allowlist",
+                  "open",
+                  "disabled"
+                ],
+                "default": "pairing"
+              },
+              "allowFrom": {
+                "$ref": "#/definitions/allowList"
+              },
+              "groupAllowFrom": {
+                "$ref": "#/definitions/allowList"
+              },
+              "groupPolicy": {
+                "type": "string",
+                "enum": [
+                  "allowlist",
+                  "open",
+                  "disabled"
+                ],
+                "default": "allowlist"
+              },
+              "groups": {
+                "type": "object",
+                "additionalProperties": {
+                  "$ref": "#/definitions/groupConfig"
+                }
+              },
+              "transport": {
+                "type": "string",
+                "enum": [
+                  "polling",
+                  "webhook"
+                ],
+                "description": "Update transport. Default: webhook when webhookUrl is set, otherwise polling. MAX does not serve long polling while a webhook subscription exists."
+              },
+              "webhookUrl": {
+                "type": "string",
+                "description": "Public HTTPS URL (port 443, trusted CA) MAX posts updates to; its path is served on the gateway HTTP server."
+              },
+              "webhookSecret": {
+                "type": "string",
+                "description": "X-Max-Bot-Api-Secret value, 5-256 of A-Z a-z 0-9 _ -. Prefer webhookSecretFile; generated and kept in the account state file when neither is set."
+              },
+              "webhookSecretFile": {
+                "type": "string",
+                "description": "File holding the webhook secret (like tokenFile)."
+              },
+              "webhookPath": {
+                "type": "string",
+                "description": "Gateway route path when it differs from the webhookUrl pathname (default: webhookUrl pathname, else /max/webhook)."
+              },
+              "historyLimit": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "dmHistoryLimit": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "dms": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "properties": {
+                    "historyLimit": {
+                      "type": "integer",
+                      "minimum": 0
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "textChunkLimit": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "blockStreaming": {
+                "type": "boolean"
+              },
+              "streamMode": {
+                "type": "string",
+                "enum": [
+                  "off",
+                  "partial",
+                  "block"
+                ]
+              },
+              "blockStreamingCoalesce": {
+                "type": "object",
+                "properties": {
+                  "minChars": {
+                    "type": "integer"
+                  },
+                  "maxChars": {
+                    "type": "integer"
+                  },
+                  "idleMs": {
+                    "type": "integer"
+                  }
+                },
+                "additionalProperties": false
+              },
+              "responsePrefix": {
+                "type": "string"
+              },
+              "mediaMaxMb": {
+                "type": "number",
+                "exclusiveMinimum": 0
+              },
+              "markSeen": {
+                "type": "boolean"
+              },
+              "actions": {
+                "type": "object",
+                "additionalProperties": {
+                  "anyOf": [
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "type": "string",
+                      "enum": [
+                        "pairing",
+                        "allowlist",
+                        "open"
+                      ]
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "allOf": [
+          {
+            "$ref": "#/definitions/accountConfig"
+          }
+        ],
+        "properties": {
+          "accounts": {
+            "type": "object",
+            "additionalProperties": {
+              "$ref": "#/definitions/accountConfig"
+            }
+          },
+          "commands": {
+            "type": "array",
+            "description": "Bot commands registered on start via PATCH /me/commands (replaces the whole list, max 32).",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "maxLength": 64
+                },
+                "description": {
+                  "type": "string",
+                  "maxLength": 128
+                }
+              },
+              "required": [
+                "name"
+              ],
+              "additionalProperties": false
+            },
+            "maxItems": 32
+          },
+          "defaultAccount": {
+            "type": "string"
+          }
+        }
+      },
+      "label": "MAX",
+      "description": "MAX messenger channel (max.ru Bot API)."
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@aspalagin/openclaw-max",
+  "version": "0.7.2",
+  "description": "MAX messenger channel plugin for OpenClaw",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "max",
+    "max-messenger",
+    "messenger",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aspalagin/openclaw-max.git"
+  },
+  "homepage": "https://github.com/aspalagin/openclaw-max#readme",
+  "bugs": {
+    "url": "https://github.com/aspalagin/openclaw-max/issues"
+  },
+  "scripts": {
+    "build": "rm -rf dist-ts dist/src && tsc --noEmit false --noEmitOnError false --outDir dist-ts && mkdir -p dist/src && cp dist-ts/index.js dist-ts/setup-entry.js dist/ && cp dist-ts/src/*.js dist/src/ && rm -f dist/src/*.test.js dist/src/test-setup.js",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:api": "node --input-type=module ./scripts/test-api.mjs",
+    "check:cycles": "node scripts/check-cycles.mjs",
+    "schema:update": "node scripts/update-schema.mjs"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "!src/**/*.test.ts",
+    "!src/test-setup.ts",
+    "!src/__fixtures__/",
+    "scripts/",
+    "openclaw.plugin.json",
+    "README.md",
+    "SKILL.md",
+    "LICENSE"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "setupEntry": "./dist/setup-entry.js",
+    "channel": {
+      "id": "max",
+      "label": "MAX",
+      "selectionLabel": "MAX (max.ru)",
+      "docsPath": "/channels/max",
+      "docsLabel": "max",
+      "blurb": "MAX messenger channel (max.ru Bot API)."
+    },
+    "compat": {
+      "pluginApi": ">=2026.9.6",
+      "minGatewayVersion": "2026.9.6"
+    },
+    "build": {
+      "openclawVersion": "2026.9.6",
+      "pluginSdkVersion": "2026.9.6"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.61.0",
+    "@typescript-eslint/parser": "^8.61.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "openclaw": "^2026.9.6",
+    "prettier": "^3.8.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8",
+    "yaml": "^2.9.1"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.9.6"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "undici": "^8.7.0",
+    "zod": "^4.4.3"
+  }
+}

package/scripts/check-cycles.mjs

@@ -0,0 +1,38 @@
+// Fails when src/*.ts local imports form a cycle. Type-only imports count too
+// (pass --runtime to ignore them).
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const runtimeOnly = process.argv.includes("--runtime");
+const dir = new URL("../src/", import.meta.url).pathname;
+const files = readdirSync(dir).filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts"));
+const graph = new Map();
+const importRe = /^\s*(import|export)\s+(type\s+)?[^;]*?from\s+["']\.\/([\w.-]+)\.js["']/gms;
+for (const file of files) {
+  const text = readFileSync(join(dir, file), "utf8");
+  const deps = new Set();
+  for (const m of text.matchAll(importRe)) {
+    if (runtimeOnly && m[2]) continue;
+    deps.add(`${m[3]}.ts`);
+  }
+  graph.set(file, [...deps].filter((d) => files.includes(d)));
+}
+const cycles = [];
+const state = new Map();
+const stack = [];
+const visit = (node) => {
+  state.set(node, 1);
+  stack.push(node);
+  for (const dep of graph.get(node) ?? []) {
+    if (state.get(dep) === 1) cycles.push([...stack.slice(stack.indexOf(dep)), dep].join(" → "));
+    else if (!state.has(dep)) visit(dep);
+  }
+  stack.pop();
+  state.set(node, 2);
+};
+for (const file of files) if (!state.has(file)) visit(file);
+if (cycles.length) {
+  console.error(`import cycles (${runtimeOnly ? "runtime" : "all"} imports):\n${cycles.join("\n")}`);
+  process.exit(1);
+}
+console.log(`no import cycles among ${files.length} modules (${runtimeOnly ? "runtime" : "all"} imports)`);