@0xmaxma/claude-gateway 1.8.13 → 2.0.0

package/dist/wechat/ilink-client.js

@@ -0,0 +1,660 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeClientVersion = encodeClientVersion;
+exports.normalizeQrImage = normalizeQrImage;
+exports.resolveWeixinReply = resolveWeixinReply;
+exports.resolveWeixinImageRef = resolveWeixinImageRef;
+exports.resolveWeixinFileRef = resolveWeixinFileRef;
+exports.aes128EcbDecryptPermissive = aes128EcbDecryptPermissive;
+exports.downloadWeixinImage = downloadWeixinImage;
+exports.createILinkClient = createILinkClient;
+exports.createFakeILinkClient = createFakeILinkClient;
+exports.isWeChatILinkFakeEnabled = isWeChatILinkFakeEnabled;
+/**
+ * HTTP client for Tencent's iLink Bot API ("WeChat ClawBot") — the real,
+ * documented, self-serve protocol behind both source projects this channel
+ * was researched from (Hermes-agent's Weixin adapter, OpenClaw's WeChat
+ * plugin). The canonical protocol reference is Tencent's own
+ * `Tencent/openclaw-weixin` repo (docs/protocol.md), an MIT-licensed,
+ * actively-maintained OpenClaw channel plugin published as
+ * `@tencent-weixin/openclaw-weixin` — not a third-party paid bridge. No
+ * account signup with any company is required: `openclaw channels login`
+ * scans a QR with the user's own WeChat app and stores the resulting
+ * credentials locally, which is exactly the shape `startLinking()` below
+ * mirrors.
+ *
+ * IMPORTANT caveats carried over from that protocol doc, not filled in here:
+ *  - `qrcode_img_content` — confirmed against a real response (2026-09-10):
+ *    it is a `liteapp.weixin.qq.com` URL (an `text/html` mini-program deep
+ *    link, NOT an image — confirmed by fetching it directly and checking
+ *    Content-Type), meant to be scanned as data, not displayed as a
+ *    pre-rendered picture. `normalizeQrImage()` below QR-encodes it into an
+ *    actual PNG data URI (via the `qrcode` package) so `WeChatStatus.qr`
+ *    keeps the same "ready-to-`<img src>`" contract every other device-linked
+ *    channel's status already uses (mirrors WhatsApp/Baileys, which does the
+ *    same QR-image encoding for its own pairing string).
+ *  - `need_verifycode`/`verify_code_blocked` (an extra verification-code
+ *    step some accounts hit) has no UI path yet — those statuses currently
+ *    fall back to "expired" (ask the user to retry) rather than prompting
+ *    for a code. See `pollLinkStatus`'s doc comment.
+ *  - Media: inbound IMAGES (item type 2) are downloaded + decrypted (see
+ *    `resolveWeixinImageRef`/`downloadWeixinImage` below, confirmed live
+ *    2026-09-11 against protocol.md + `NousResearch/hermes-agent`'s working
+ *    Python implementation). Voice/file/video (types 3/4/5) and ALL outbound
+ *    media sending are still out of scope — only `text_item` is written.
+ */
+const crypto = __importStar(require("crypto"));
+const QRCode = __importStar(require("qrcode"));
+const DEFAULT_ILINK_BASE_URL = 'https://ilinkai.weixin.qq.com';
+/** `base_info.bot_agent` — a short ASCII observability tag, per protocol.md's
+ * "sanitized observability identifier... not used for authentication or
+ * routing" — analogous to `bot_agent: "OpenClaw"` in Tencent's own examples.
+ * This gateway has no single fixed downstream product identity, so this is
+ * only the fallback when a deployer doesn't set `AgentConfig.wechat.botAgent`
+ * — see that field's doc comment. Mirrors `channels.openclaw-weixin.botAgent`
+ * in `Tencent/openclaw-weixin`'s own config being per-deployment, not fixed. */
+const DEFAULT_BOT_AGENT = 'claude-gateway';
+/** `base_info.channel_version` — this integration's own version, not the
+ * gateway's. Bump when this file's request/response handling changes. */
+const CHANNEL_VERSION = '1.0.0';
+/** Random uint32 → decimal string → base64, per protocol.md's `X-WECHAT-UIN` spec. */
+function randomWechatUin() {
+    const n = Math.floor(Math.random() * 0x100000000);
+    return Buffer.from(String(n), 'utf-8').toString('base64');
+}
+/**
+ * Plugin version as `0x00MMNNPP` (major/minor/patch, one byte each) rendered
+ * as a decimal string, per protocol.md's `iLink-App-ClientVersion` spec.
+ */
+function encodeClientVersion(version) {
+    const [major = 0, minor = 0, patch = 0] = version.split('.').map((n) => parseInt(n, 10) || 0);
+    const encoded = ((major & 0xff) << 16) | ((minor & 0xff) << 8) | (patch & 0xff);
+    return String(encoded);
+}
+const CLIENT_VERSION_HEADER = encodeClientVersion(CHANNEL_VERSION);
+/**
+ * Turn whatever `qrcode_img_content` actually is into a ready-to-`<img src>`
+ * PNG data URI. Confirmed shape (see module doc comment): a
+ * `liteapp.weixin.qq.com` URL that must itself be QR-encoded — it is data to
+ * scan, not a picture to show as-is.
+ */
+async function normalizeQrImage(content) {
+    if (content.startsWith('data:'))
+        return content;
+    if (content.startsWith('http://') || content.startsWith('https://')) {
+        return QRCode.toDataURL(content, { margin: 1 });
+    }
+    // Fallback for a shape neither confirmed response nor the doc describes:
+    // assume base64-encoded PNG bytes already.
+    return `data:image/png;base64,${content}`;
+}
+const DEFAULT_FETCH_TIMEOUT_MS = 15000;
+/**
+ * `redirect_host` (and `baseurl` on a `confirmed` response) — confirmed live
+ * (2026-09-10) to arrive as a bare host, e.g. `ilinkai2.weixin.qq.com`, NOT a
+ * full `https://...` URL as protocol.md's naming implies. `new URL(path,
+ * base)` throws "Invalid URL" on a schemeless base, which silently wedged
+ * every poll after a real scan forever (the retry loop in
+ * WeChatManager.startLinking keeps calling this same host, gets the same
+ * throw every time, and only the attempt's 2-minute deadline ever ends it).
+ */
+function normalizeIlinkHost(host) {
+    return /^https?:\/\//i.test(host) ? host : `https://${host}`;
+}
+async function ilinkFetch(opts) {
+    let url;
+    try {
+        url = new URL(opts.path, opts.baseUrl);
+    }
+    catch {
+        // Bare `new URL()` errors ("Invalid URL") carry no context — surface
+        // which baseUrl actually failed, since this is exactly what a malformed
+        // `redirect_host`/`baseurl` from iLink looks like (see normalizeIlinkHost).
+        throw new Error(`iLink ${opts.method} ${opts.path}: invalid baseUrl "${opts.baseUrl}"`);
+    }
+    if (opts.query) {
+        for (const [k, v] of Object.entries(opts.query))
+            url.searchParams.set(k, v);
+    }
+    const headers = {
+        'iLink-App-Id': 'bot',
+        'iLink-App-ClientVersion': CLIENT_VERSION_HEADER,
+        // Force a fresh connection per request instead of reusing Node's
+        // undici keep-alive pool. Confirmed root cause, sourced from a second
+        // independent reference implementation (Hermes-agent's
+        // `gateway/platforms/weixin.py`, `_make_ssl_connector()`): "proxies like
+        // Cloudflare Warp leave peer-initiated FIN in CLOSE_WAIT" — a pooled
+        // keep-alive connection can go stale (closed server-side) without the
+        // client noticing, and a later request reusing it just hangs/fails.
+        // Hermes-agent works around this with a 2s keepalive_timeout; the
+        // simpler equivalent here is to never keep the connection alive at all.
+        Connection: 'close',
+    };
+    // Auth headers are sent for the QR POST too (it still identifies the
+    // client), but NOT for the unauthenticated GET status-poll — see
+    // protocol.md's "Before auth (QR polling)" header table.
+    if (opts.method === 'POST') {
+        headers['Content-Type'] = 'application/json';
+        headers['AuthorizationType'] = 'ilink_bot_token';
+        headers['X-WECHAT-UIN'] = randomWechatUin();
+    }
+    if (opts.botToken)
+        headers['Authorization'] = `Bearer ${opts.botToken}`;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+        res = await fetch(url.toString(), {
+            method: opts.method,
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err.name === 'AbortError') {
+            throw new Error(`iLink ${opts.method} ${opts.path}: timed out after ${timeoutMs}ms`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok) {
+        throw new Error(`iLink ${opts.method} ${opts.path}: HTTP ${res.status}`);
+    }
+    return (await res.json());
+}
+/** Extract the first text item's body — image items are handled separately by resolveWeixinImageRef; voice/file/video are still ignored. */
+function textFromItems(items) {
+    return items?.find((i) => i.type === 1)?.text_item?.text;
+}
+/** Preserve the immediate quote only; nested quotes are not fresh user instructions. */
+function resolveWeixinReply(items) {
+    const ref = items?.find(item => item.ref_msg)?.ref_msg;
+    if (!ref)
+        return;
+    const item = ref.message_item;
+    let image, file;
+    try {
+        image = resolveWeixinImageRef(item ? [item] : []);
+    }
+    catch { /* Existing media URL guard applies. */ }
+    try {
+        file = resolveWeixinFileRef(item ? [item] : []);
+    }
+    catch { /* Existing media URL guard applies. */ }
+    return { messageId: ref.svr_id === undefined ? undefined : String(ref.svr_id), text: item?.text_item?.text ?? ref.title, image, file };
+}
+/**
+ * Hosts Tencent actually serves inbound-media downloads from, per
+ * `NousResearch/hermes-agent`'s `gateway/platforms/weixin.py`
+ * (`_WEIXIN_CDN_ALLOWLIST`, confirmed live 2026-09-11). Only checked against
+ * a server-supplied `full_url` — a URL built from `encrypt_query_param`
+ * against `DEFAULT_CDN_BASE_URL` below doesn't need it (that host is our own
+ * trusted constant). This is an SSRF guard: without it, a malicious/buggy
+ * `full_url` could point this server's own outbound fetch at an arbitrary
+ * internal host.
+ */
+const WEIXIN_CDN_ALLOWLIST = new Set([
+    'novac2c.cdn.weixin.qq.com',
+    'ilinkai.weixin.qq.com',
+    'wx.qlogo.cn',
+    'thirdwx.qlogo.cn',
+    'res.wx.qq.com',
+    'mmbiz.qpic.cn',
+    'mmbiz.qlogo.cn',
+    // Confirmed live 2026-09-11: real `image_item.media.full_url` responses use
+    // the `.wechat.com` domain family, not `.weixin.qq.com` — same mismatch
+    // class as `redirect_host` earlier this session (docs/Hermes-agent's own
+    // allowlist assumed `.weixin.qq.com`; our own post-link `baseUrl` for
+    // authenticated calls is ALSO `ilinkai.wechat.com`, confirming this is the
+    // real production domain, not a one-off).
+    'novac2c.cdn.wechat.com',
+    'ilinkai.wechat.com',
+]);
+const DEFAULT_CDN_BASE_URL = 'https://novac2c.cdn.weixin.qq.com/c2c';
+/**
+ * Decode an inbound AES key from its `media.aes_key` (base64) encoding.
+ * protocol.md: "the download decoder accepts base64 of either 16 raw bytes
+ * or a 32-character hexadecimal key" — both shapes are used in practice.
+ */
+function parseAesKeyBase64(aesKeyB64) {
+    const decoded = Buffer.from(aesKeyB64, 'base64');
+    if (decoded.length === 16)
+        return decoded;
+    if (decoded.length === 32) {
+        const text = decoded.toString('ascii');
+        if (/^[0-9a-fA-F]{32}$/.test(text))
+            return Buffer.from(text, 'hex');
+    }
+    throw new Error(`iLink image: unrecognized aes_key encoding (${decoded.length} bytes decoded)`);
+}
+/**
+ * Shared URL+key resolution for any media item's `media` block. `rawHexKey`
+ * is the item-type-specific top-level key field when one exists (only
+ * `image_item.aeskey` per protocol.md — files have no equivalent, so callers
+ * for other item types pass `undefined`).
+ */
+function resolveMediaRef(media, rawHexKey) {
+    let aesKey;
+    if (rawHexKey && /^[0-9a-fA-F]{32}$/.test(rawHexKey)) {
+        aesKey = Buffer.from(rawHexKey, 'hex');
+    }
+    else if (media?.aes_key) {
+        aesKey = parseAesKeyBase64(media.aes_key);
+    }
+    let url;
+    if (media?.full_url) {
+        const host = new URL(media.full_url).hostname;
+        if (!WEIXIN_CDN_ALLOWLIST.has(host)) {
+            throw new Error(`iLink media: refusing to download from non-allowlisted host "${host}"`);
+        }
+        url = media.full_url;
+    }
+    else if (media?.encrypt_query_param) {
+        url = `${DEFAULT_CDN_BASE_URL}/download?encrypted_query_param=${encodeURIComponent(media.encrypt_query_param)}`;
+    }
+    return url ? { url, aesKey } : undefined;
+}
+function resolveWeixinImageRef(items) {
+    const item = items?.find((i) => i.type === 2 && i.image_item);
+    if (!item?.image_item)
+        return undefined;
+    return resolveMediaRef(item.image_item.media, item.image_item.aeskey);
+}
+/** Resolve an inbound file item (type=4) — protocol.md has no top-level aeskey for files, only media.aes_key. */
+function resolveWeixinFileRef(items) {
+    const item = items?.find((i) => i.type === 4 && i.file_item);
+    if (!item?.file_item)
+        return undefined;
+    const ref = resolveMediaRef(item.file_item.media, undefined);
+    if (!ref)
+        return undefined;
+    const expectedLength = item.file_item.len ? parseInt(item.file_item.len, 10) : undefined;
+    return {
+        ...ref,
+        fileName: item.file_item.file_name || 'file',
+        expectedLength: Number.isFinite(expectedLength) ? expectedLength : undefined,
+    };
+}
+/**
+ * AES-128-ECB decrypt with PERMISSIVE PKCS#7 unpadding: if the trailing
+ * padding doesn't validate, return the padded bytes as-is instead of
+ * throwing. Mirrors `NousResearch/hermes-agent`'s `_aes128_ecb_decrypt`
+ * exactly (confirmed live 2026-09-11) — Node's built-in auto-unpad
+ * (`setAutoPadding(true)`) throws "bad decrypt" on the same real-world edge
+ * cases Hermes-agent's own implementation was written to tolerate.
+ */
+function aes128EcbDecryptPermissive(ciphertext, key) {
+    const decipher = crypto.createDecipheriv('aes-128-ecb', key, null);
+    decipher.setAutoPadding(false);
+    const padded = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    if (padded.length === 0)
+        return padded;
+    const padLen = padded[padded.length - 1];
+    if (padLen >= 1 && padLen <= 16 && padded.length >= padLen) {
+        const tail = padded.subarray(padded.length - padLen);
+        if (tail.every((b) => b === padLen))
+            return padded.subarray(0, padded.length - padLen);
+    }
+    return padded;
+}
+/**
+ * Download (and decrypt, if `ref.aesKey` is set) an inbound image's bytes.
+ * No bot-token auth — protocol.md documents this as a plain CDN GET against
+ * a pre-signed/scoped URL.
+ */
+/** 20 MB — matches MediaStore.maxUploadBytes (not imported directly: ilink-client is a
+ * protocol-layer module and shouldn't depend on history/media-store's storage layer). */
+const DEFAULT_MAX_MEDIA_BYTES = 20 * 1024 * 1024;
+async function downloadWeixinImage(ref, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 30000;
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_MEDIA_BYTES;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+        // redirect: 'manual' — WEIXIN_CDN_ALLOWLIST only validates ref.url's OWN
+        // host; fetch()'s default 'follow' would silently chase a redirect to
+        // any other host, defeating that check as an SSRF guard. A redirect
+        // response here is treated as a hard failure rather than re-validated,
+        // since the legitimate CDN paths (both the trusted default base and an
+        // allowlisted full_url) are not expected to redirect at all.
+        res = await fetch(ref.url, { signal: controller.signal, redirect: 'manual' });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400)) {
+        throw new Error('iLink media download: refusing to follow a redirect (SSRF guard)');
+    }
+    if (!res.ok) {
+        throw new Error(`iLink image download: HTTP ${res.status}`);
+    }
+    // Reject on the declared size before buffering the body when the server
+    // tells us upfront (LINE's webhook router enforces the same cap the same
+    // way — see MAX_MEDIA_BYTES's declaredSize check there).
+    const declaredLength = Number(res.headers?.get?.('content-length'));
+    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+        throw new Error(`iLink media download: declared size ${declaredLength} exceeds ${maxBytes} byte cap`);
+    }
+    const raw = Buffer.from(await res.arrayBuffer());
+    if (raw.length > maxBytes) {
+        throw new Error(`iLink media download: ${raw.length} bytes exceeds ${maxBytes} byte cap`);
+    }
+    const decrypted = ref.aesKey ? aes128EcbDecryptPermissive(raw, ref.aesKey) : raw;
+    // See ILinkImageRef.expectedLength's doc comment — trims a leading prefix
+    // WeChat's file-upload path adds ahead of the real content.
+    if (ref.expectedLength !== undefined && decrypted.length > ref.expectedLength) {
+        return decrypted.subarray(decrypted.length - ref.expectedLength);
+    }
+    return decrypted;
+}
+/**
+ * Real implementation — talks to Tencent's iLink Bot API. See this module's
+ * doc comment for the two documented ambiguities (`qrcode_img_content`'s
+ * encoding, and the unhandled verification-code statuses) still to confirm
+ * against a real account.
+ */
+function createILinkClient(baseUrl, botAgent) {
+    const qrBaseUrl = baseUrl || DEFAULT_ILINK_BASE_URL;
+    const resolvedBotAgent = botAgent || DEFAULT_BOT_AGENT;
+    const clientBaseInfo = () => ({
+        channel_version: CHANNEL_VERSION,
+        bot_agent: resolvedBotAgent,
+    });
+    // getupdates' cursor must survive across polls — scoped per accountId so
+    // one client instance could in principle serve more than one credential
+    // set, even though v1 only ever uses it for a single linked account.
+    const updateCursors = new Map();
+    // Which host to poll get_qrcode_status on next, per in-flight login
+    // attempt — starts at qrBaseUrl, switches once `redirect_host` is seen
+    // (see GetQrcodeStatusResponse's doc comment on that field for why this
+    // exists at all).
+    const qrStatusHosts = new Map();
+    return {
+        async requestLinkQr() {
+            const res = await ilinkFetch({
+                method: 'POST',
+                path: '/ilink/bot/get_bot_qrcode',
+                query: { bot_type: '3' },
+                body: { local_token_list: [] },
+                baseUrl: qrBaseUrl,
+            });
+            return { qrDataUri: await normalizeQrImage(res.qrcode_img_content), loginSessionId: res.qrcode };
+        },
+        async pollLinkStatus(loginSessionId) {
+            const pollHost = qrStatusHosts.get(loginSessionId) ?? qrBaseUrl;
+            const res = await ilinkFetch({
+                method: 'GET',
+                path: '/ilink/bot/get_qrcode_status',
+                query: { qrcode: loginSessionId },
+                baseUrl: pollHost,
+            });
+            if (res.status === 'scaned_but_redirect' && res.redirect_host) {
+                qrStatusHosts.set(loginSessionId, normalizeIlinkHost(res.redirect_host));
+            }
+            if (res.status === 'confirmed' && res.bot_token && res.ilink_bot_id) {
+                qrStatusHosts.delete(loginSessionId);
+                return {
+                    linked: true,
+                    status: res.status,
+                    credentials: {
+                        accountId: res.ilink_bot_id,
+                        token: res.bot_token,
+                        baseUrl: res.baseurl ? normalizeIlinkHost(res.baseurl) : qrBaseUrl,
+                    },
+                };
+            }
+            // `need_verifycode`/`verify_code_blocked` have no UI path yet (see
+            // module doc comment) — surface as "still not linked" so the caller's
+            // own attempt-timeout eventually reports back to the user, rather than
+            // silently hanging on a status this client can't act on.
+            return { linked: false, status: res.status };
+        },
+        async getUpdates(creds, _timeoutSeconds) {
+            const cursor = updateCursors.get(creds.accountId) ?? '';
+            const res = await ilinkFetch({
+                method: 'POST',
+                path: '/ilink/bot/getupdates',
+                body: { get_updates_buf: cursor, base_info: clientBaseInfo() },
+                botToken: creds.token,
+                baseUrl: creds.baseUrl,
+                // iLink's own long-poll legitimately blocks up to _timeoutSeconds —
+                // give it headroom above that instead of the 15s default meant for
+                // quick request/response calls.
+                timeoutMs: _timeoutSeconds * 1000 + 10000,
+            });
+            if (res.get_updates_buf !== undefined)
+                updateCursors.set(creds.accountId, res.get_updates_buf);
+            // `ret` is OMITTED entirely on a successful response (confirmed live
+            // 2026-09-10 — every real getupdates success we captured had no `ret`
+            // field at all, just `msgs`/`get_updates_buf`), matching protocol.md's
+            // explicit rule for sendMessage ("an absent ret does not trigger this
+            // check") which applies the same way here. The old `res.ret !== 0`
+            // check was true for `undefined` too, so it threw "ret=undefined" on
+            // every single successful call — the actual reason messages we KNEW
+            // existed (confirmed via a raw curl to the same account) never made it
+            // through this client.
+            if (res.ret !== undefined && res.ret !== 0) {
+                throw new Error(`iLink getupdates failed: ret=${res.ret} errmsg=${res.errmsg ?? 'unknown'}`);
+            }
+            return (res.msgs ?? [])
+                // message_type 2 = the bot's own messages echoed back — never a real
+                // inbound message, so treating them as one would make the agent
+                // reply to itself.
+                .filter((m) => m.message_type === 1)
+                .map((m) => {
+                let image;
+                let file;
+                try {
+                    image = resolveWeixinImageRef(m.item_list);
+                }
+                catch {
+                    // A malformed item or a non-allowlisted full_url (SSRF guard)
+                    // must not drop the whole batch — this one message just arrives
+                    // without its image, same as any other undeliverable-media case.
+                    image = undefined;
+                }
+                try {
+                    file = resolveWeixinFileRef(m.item_list);
+                }
+                catch {
+                    file = undefined;
+                }
+                return {
+                    id: m.message_id,
+                    fromId: m.from_user_id,
+                    text: textFromItems(m.item_list),
+                    reply: resolveWeixinReply(m.item_list),
+                    timestamp: m.create_time_ms,
+                    contextToken: m.context_token,
+                    image,
+                    file,
+                };
+            });
+        },
+        async sendText(creds, toId, text, contextToken) {
+            const res = await ilinkFetch({
+                method: 'POST',
+                path: '/ilink/bot/sendmessage',
+                body: {
+                    msg: {
+                        from_user_id: '',
+                        to_user_id: toId,
+                        // A fixed prefix, not resolvedBotAgent: this is just a dedup/
+                        // idempotency token, not user-facing, and a deployer's own
+                        // botAgent value isn't guaranteed to be ID-safe (arbitrary
+                        // characters, unlike the sanitized UA-style string protocol.md
+                        // describes for bot_agent itself, which this gateway doesn't
+                        // enforce on its own botAgent config field).
+                        client_id: `${DEFAULT_BOT_AGENT}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
+                        message_type: 2,
+                        message_state: 2,
+                        context_token: contextToken ?? '',
+                        item_list: [{ type: 1, text_item: { text } }],
+                    },
+                    base_info: clientBaseInfo(),
+                },
+                botToken: creds.token,
+                baseUrl: creds.baseUrl,
+            });
+            // Same fix as getUpdates above — confirmed live: a successful
+            // sendmessage response is just `{"message_id": ...}`, no `ret` field
+            // at all. Per protocol.md: "A non-zero ret throws; an absent ret does
+            // not trigger this check."
+            if (res.ret !== undefined && res.ret !== 0) {
+                throw new Error(`iLink sendmessage failed: ret=${res.ret} errmsg=${res.errmsg ?? 'unknown'}`);
+            }
+        },
+        async notifyStart(creds) {
+            await ilinkFetch({
+                method: 'POST',
+                path: '/ilink/bot/msg/notifystart',
+                body: { base_info: clientBaseInfo() },
+                botToken: creds.token,
+                baseUrl: creds.baseUrl,
+                timeoutMs: 10000,
+            });
+        },
+        async notifyStop(creds) {
+            await ilinkFetch({
+                method: 'POST',
+                path: '/ilink/bot/msg/notifystop',
+                body: { base_info: clientBaseInfo() },
+                botToken: creds.token,
+                baseUrl: creds.baseUrl,
+                timeoutMs: 10000,
+            });
+        },
+    };
+}
+/** A deterministic checkerboard SVG, styled to read as "a QR code" at a glance
+ * without a real QR-encoding dependency — this fake client never needs to be
+ * actually scanned. */
+function fakeQrDataUri(seed) {
+    const size = 21;
+    let hash = 0;
+    for (let i = 0; i < seed.length; i++)
+        hash = (hash * 31 + seed.charCodeAt(i)) >>> 0;
+    let cells = '';
+    for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+            // Corner "finder" squares, like a real QR code, plus a pseudo-random fill
+            // elsewhere so every fake session looks visually distinct.
+            const inFinder = (x < 7 && y < 7) || (x >= size - 7 && y < 7) || (x < 7 && y >= size - 7);
+            hash = (hash * 1103515245 + 12345) >>> 0;
+            const on = inFinder ? (x % 6 !== 3 && y % 6 !== 3) : hash % 2 === 0;
+            if (on)
+                cells += `<rect x="${x}" y="${y}" width="1" height="1"/>`;
+        }
+    }
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${size} ${size}" fill="#000">` +
+        `<rect width="${size}" height="${size}" fill="#fff"/>${cells}</svg>`;
+    return `data:image/svg+xml;base64,${Buffer.from(svg).toString('base64')}`;
+}
+/**
+ * Local-testing-only fake client — no network calls, no real iLink account
+ * needed. Simulates a QR scan completing after a few polls, then occasionally
+ * delivers one fake inbound message (carrying its own fake `contextToken`,
+ * exactly like the real protocol) so the pending-sender/access-control UI
+ * has something to show. Never wired up by default — see
+ * `isWeChatILinkFakeEnabled()` and its call site in AgentRunner.
+ *
+ * NOT a substitute for the real API contract — exists purely so the apps/web
+ * card's UI/UX (QR render, link→linked transition, DM allowlist, disconnect)
+ * can be manually verified end-to-end without a real WeChat account.
+ */
+function createFakeILinkClient() {
+    let pollCount = 0;
+    let updateCount = 0;
+    return {
+        async requestLinkQr() {
+            pollCount = 0;
+            const loginSessionId = `fake-session-${Date.now()}`;
+            return { qrDataUri: fakeQrDataUri(loginSessionId), loginSessionId };
+        },
+        async pollLinkStatus(loginSessionId) {
+            pollCount += 1;
+            // ~3 polls at the manager's 2s interval ⇒ linked after ~6s, long enough
+            // to see the QR/"Waiting for scan…" state before it resolves.
+            if (pollCount < 3)
+                return { linked: false };
+            return {
+                linked: true,
+                credentials: {
+                    accountId: 'fake-account',
+                    token: `fake-token-${loginSessionId}`,
+                    baseUrl: 'fake://local-test',
+                },
+            };
+        },
+        async getUpdates(_creds, timeoutSeconds) {
+            // Real iLink blocks up to `timeoutSeconds`; a short fixed sleep here
+            // keeps manual testing responsive instead of waiting the full 35s.
+            await new Promise((resolve) => setTimeout(resolve, Math.min(timeoutSeconds, 4) * 1000));
+            updateCount += 1;
+            // One fake message shortly after linking, then quiet — enough to
+            // exercise the pending-sender/allowlist flow without spamming.
+            if (updateCount === 2) {
+                return [
+                    {
+                        id: `fake-msg-${Date.now()}`,
+                        fromId: 'fake-tester',
+                        text: 'Hi, this is a fake WeChat test message — approve me to keep chatting!',
+                        displayName: 'Fake Tester',
+                        timestamp: Date.now(),
+                        contextToken: 'fake-context-token',
+                    },
+                ];
+            }
+            return [];
+        },
+        async sendText(_creds, toId, text, contextToken) {
+            // eslint-disable-next-line no-console -- local-testing-only visibility, not production logging
+            console.log(`[fake-ilink] would send to ${toId} (ctx=${contextToken ?? 'none'}): ${text}`);
+        },
+        async notifyStart() { },
+        async notifyStop() { },
+    };
+}
+/** Opt-in only, local dev/manual-testing use — see createFakeILinkClient's doc comment. */
+function isWeChatILinkFakeEnabled() {
+    return process.env.WECHAT_ILINK_FAKE === 'true';
+}
+//# sourceMappingURL=ilink-client.js.map