@0xmaxma/claude-gateway 1.8.13 → 1.8.14

package/dist/wechat/ilink-client.d.ts

@@ -0,0 +1,194 @@
+export interface ILinkCredentials {
+    accountId: string;
+    token: string;
+    baseUrl: string;
+}
+export interface ILinkQrSession {
+    /** Data URI (or remote image URL) to render as the login QR. */
+    qrDataUri: string;
+    /** Opaque handle to poll for this specific login attempt's completion. */
+    loginSessionId: string;
+}
+export interface ILinkLinkResult {
+    linked: boolean;
+    credentials?: ILinkCredentials;
+    /**
+     * The raw status string Tencent returned (`wait`/`scaned`/`confirmed`/
+     * `expired`/`need_verifycode`/`verify_code_blocked`/`scaned_but_redirect`/
+     * `binded_redirect`), surfaced purely for operational logging — nothing
+     * downstream branches on it besides `linked` above. Added after a live
+     * link attempt where the confirm button was tapped but nothing here ever
+     * saw `confirmed`, with zero visibility into which of these statuses it
+     * actually got stuck on.
+     */
+    status?: string;
+}
+export interface ILinkUpdate {
+    /** iLink message id — used for at-least-once delivery de-duplication. */
+    id: string;
+    /** Sender's iLink user id. */
+    fromId: string;
+    /** Plain text body, when present. */
+    text?: string;
+    /** Best-effort display name, when iLink provides one. */
+    displayName?: string;
+    /** Server timestamp (ms since epoch), when provided. */
+    timestamp?: number;
+    /**
+     * Conversation context token this specific message carries (Tencent's
+     * `WeixinMessage.context_token`) — established by an INBOUND message, not
+     * minted by sending one. Must be echoed on the next `sendText` call to
+     * this same sender. See this module's doc comment for why `sendText`
+     * itself no longer returns one.
+     */
+    contextToken?: string;
+    /** Present when this message carries an inbound image (item type 2). Download+decrypt via `downloadWeixinImage()`. */
+    image?: ILinkImageRef;
+    /** Present when this message carries an inbound file (item type 4, e.g. a PDF). Download+decrypt via `downloadWeixinImage()`, same as an image. */
+    file?: ILinkFileRef;
+}
+/** Resolved download target for an inbound image, from `resolveWeixinImageRef()`. */
+export interface ILinkImageRef {
+    url: string;
+    /** Absent means the bytes at `url` are already plaintext. */
+    aesKey?: Buffer;
+    /**
+     * Sender-declared plaintext byte count (`file_item.len` — files only, per
+     * protocol.md). When set and the decrypted buffer is longer than this,
+     * `downloadWeixinImage` keeps the trailing `expectedLength` bytes and
+     * drops the rest as a leading prefix — confirmed live 2026-09-11: a real
+     * decrypted PDF carried 3 extra bytes before its `%PDF-` header despite a
+     * byte-perfect key/cipher (images never show this, only files), so
+     * WeChat's file upload path evidently prepends a few bytes ahead of the
+     * real content that protocol.md doesn't document.
+     */
+    expectedLength?: number;
+}
+export interface ILinkClient {
+    /** Start a fresh QR login flow. */
+    requestLinkQr(): Promise<ILinkQrSession>;
+    /** Poll whether a QR login attempt has been completed (scanned + confirmed). */
+    pollLinkStatus(loginSessionId: string): Promise<ILinkLinkResult>;
+    /**
+     * Long-poll for new messages. Resolves with zero or more updates once
+     * either a message arrives or `timeoutSeconds` elapses (iLink's documented
+     * `getupdates` contract) — never rejects on a plain timeout, only on a real
+     * transport/auth failure.
+     */
+    getUpdates(creds: ILinkCredentials, timeoutSeconds: number): Promise<ILinkUpdate[]>;
+    /**
+     * Send a single already-chunked text message. `contextToken` is whatever
+     * the most recent INBOUND message from this recipient carried (undefined
+     * if they've never messaged first) — sending does not return a new one,
+     * per Tencent's documented `sendmessage` response (`{ret, errmsg}` only).
+     */
+    sendText(creds: ILinkCredentials, toId: string, text: string, contextToken?: string): Promise<void>;
+    /**
+     * Tell iLink's backend this channel client has started, before the first
+     * `getUpdates` call — confirmed via Tencent's own official client
+     * (`Tencent/openclaw-weixin`'s `src/channel.ts`, checked 2026-09-10): it
+     * calls this unconditionally before starting its poll loop, and
+     * protocol.md documents it as "notify the backend that the client
+     * started." This codebase never called it at all, which is the likely
+     * cause of `getUpdates` failing (Cloudflare 522/524) on the large
+     * majority of polls during live testing — never confirmed as THE fix
+     * (Tencent's own docs don't spell out what not calling it does), but it's
+     * a real gap versus the reference implementation, not a stretch. Failure
+     * here must never block startup — Tencent's own client only logs a
+     * warning and continues (see `notifyStart`'s call site in manager.ts).
+     */
+    notifyStart(creds: ILinkCredentials): Promise<void>;
+    /** Counterpart to notifyStart, sent on channel stop. Same non-blocking contract. */
+    notifyStop(creds: ILinkCredentials): Promise<void>;
+}
+/**
+ * Plugin version as `0x00MMNNPP` (major/minor/patch, one byte each) rendered
+ * as a decimal string, per protocol.md's `iLink-App-ClientVersion` spec.
+ */
+export declare function encodeClientVersion(version: string): string;
+/**
+ * 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.
+ */
+export declare function normalizeQrImage(content: string): Promise<string>;
+interface WeixinMessageItem {
+    type: number;
+    text_item?: {
+        text: string;
+    };
+    /**
+     * Present on a type=2 (image) item. `aeskey` (raw 32 hex chars) takes
+     * precedence over `media.aes_key` (base64 of either 16 raw bytes or a
+     * 32-char hex string) per protocol.md — see `resolveWeixinImageRef`.
+     */
+    image_item?: {
+        aeskey?: string;
+        media?: {
+            encrypt_query_param?: string;
+            aes_key?: string;
+            full_url?: string;
+        };
+    };
+    /**
+     * Present on a type=4 (file) item. Unlike `image_item`, protocol.md
+     * documents no top-level `aeskey` for files — the key comes from
+     * `media.aes_key` only. `file_name` is the attachment's real name
+     * (including extension), needed to stage it usefully.
+     */
+    file_item?: {
+        file_name?: string;
+        /** Plaintext byte count, as a decimal string, per protocol.md. */
+        len?: string;
+        media?: {
+            encrypt_query_param?: string;
+            aes_key?: string;
+            full_url?: string;
+        };
+    };
+}
+export declare function resolveWeixinImageRef(items: WeixinMessageItem[] | undefined): ILinkImageRef | undefined;
+export interface ILinkFileRef extends ILinkImageRef {
+    /** Attachment's real filename (including extension), e.g. "report.pdf". */
+    fileName: string;
+}
+/** Resolve an inbound file item (type=4) — protocol.md has no top-level aeskey for files, only media.aes_key. */
+export declare function resolveWeixinFileRef(items: WeixinMessageItem[] | undefined): ILinkFileRef | 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.
+ */
+export declare function aes128EcbDecryptPermissive(ciphertext: Buffer, key: Buffer): Buffer;
+export declare function downloadWeixinImage(ref: ILinkImageRef, opts?: {
+    timeoutMs?: number;
+    maxBytes?: number;
+}): Promise<Buffer>;
+/**
+ * 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.
+ */
+export declare function createILinkClient(baseUrl?: string, botAgent?: string): ILinkClient;
+/**
+ * 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.
+ */
+export declare function createFakeILinkClient(): ILinkClient;
+/** Opt-in only, local dev/manual-testing use — see createFakeILinkClient's doc comment. */
+export declare function isWeChatILinkFakeEnabled(): boolean;
+export {};
+//# sourceMappingURL=ilink-client.d.ts.map

package/dist/wechat/ilink-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ilink-client.d.ts","sourceRoot":"","sources":["../../src/wechat/ilink-client.ts"],"names":[],"mappings":"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"}