@zhin.js/adapter-weixin-ilink 0.1.0

package/src/pic-decrypt.ts

@@ -0,0 +1,101 @@
+import { decryptAesEcb } from "./aes-ecb.js";
+import { buildCdnDownloadUrl, ENABLE_CDN_URL_FALLBACK } from "./cdn-url.js";
+import { logger } from "./ilink-logger.js";
+
+/**
+ * Download raw bytes from the CDN (no decryption).
+ */
+async function fetchCdnBytes(url: string, label: string): Promise<Buffer> {
+  let res: Response;
+  try {
+    res = await fetch(url);
+  } catch (err) {
+    const cause =
+      (err as NodeJS.ErrnoException).cause ?? (err as NodeJS.ErrnoException).code ?? "(no cause)";
+    logger.error(
+      `${label}: fetch network error url=${url} err=${String(err)} cause=${String(cause)}`,
+    );
+    throw err;
+  }
+  logger.debug(`${label}: response status=${res.status} ok=${res.ok}`);
+  if (!res.ok) {
+    const body = await res.text().catch(() => "(unreadable)");
+    const msg = `${label}: CDN download ${res.status} ${res.statusText} body=${body}`;
+    logger.error(msg);
+    throw new Error(msg);
+  }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/**
+ * Parse CDNMedia.aes_key into a raw 16-byte AES key.
+ *
+ * Two encodings are seen in the wild:
+ *   - base64(raw 16 bytes)          → images (aes_key from media field)
+ *   - base64(hex string of 16 bytes) → file / voice / video
+ *
+ * In the second case, base64-decoding yields 32 ASCII hex chars which must
+ * then be parsed as hex to recover the actual 16-byte key.
+ */
+function parseAesKey(aesKeyBase64: string, label: string): Buffer {
+  const decoded = Buffer.from(aesKeyBase64, "base64");
+  if (decoded.length === 16) {
+    return decoded;
+  }
+  if (decoded.length === 32 && /^[0-9a-fA-F]{32}$/.test(decoded.toString("ascii"))) {
+    // hex-encoded key: base64 → hex string → raw bytes
+    return Buffer.from(decoded.toString("ascii"), "hex");
+  }
+  const msg = `${label}: aes_key must decode to 16 raw bytes or 32-char hex string, got ${decoded.length} bytes (base64="${aesKeyBase64}")`;
+  logger.error(msg);
+  throw new Error(msg);
+}
+
+/**
+ * Download and AES-128-ECB decrypt a CDN media file. Returns plaintext Buffer.
+ * aesKeyBase64: CDNMedia.aes_key JSON field (see parseAesKey for supported formats).
+ */
+export async function downloadAndDecryptBuffer(
+  encryptedQueryParam: string,
+  aesKeyBase64: string,
+  cdnBaseUrl: string,
+  label: string,
+  fullUrl?: string,
+): Promise<Buffer> {
+  const key = parseAesKey(aesKeyBase64, label);
+  let url: string;
+  if (fullUrl) {
+    url = fullUrl;
+  } else if (ENABLE_CDN_URL_FALLBACK) {
+    url = buildCdnDownloadUrl(encryptedQueryParam, cdnBaseUrl);
+  } else {
+    throw new Error(`${label}: fullUrl is required (CDN URL fallback is disabled)`);
+  }
+  logger.debug(`${label}: fetching url=${url}`);
+  const encrypted = await fetchCdnBytes(url, label);
+  logger.debug(`${label}: downloaded ${encrypted.byteLength} bytes, decrypting`);
+  const decrypted = decryptAesEcb(encrypted, key);
+  logger.debug(`${label}: decrypted ${decrypted.length} bytes`);
+  return decrypted;
+}
+
+/**
+ * Download plain (unencrypted) bytes from the CDN. Returns the raw Buffer.
+ */
+export async function downloadPlainCdnBuffer(
+  encryptedQueryParam: string,
+  cdnBaseUrl: string,
+  label: string,
+  fullUrl?: string,
+): Promise<Buffer> {
+  let url: string;
+  if (fullUrl) {
+    url = fullUrl;
+  } else if (ENABLE_CDN_URL_FALLBACK) {
+    url = buildCdnDownloadUrl(encryptedQueryParam, cdnBaseUrl);
+  } else {
+    throw new Error(`${label}: fullUrl is required (CDN URL fallback is disabled)`);
+  }
+  logger.debug(`${label}: fetching url=${url}`);
+  return fetchCdnBytes(url, label);
+}

package/src/routes.ts

@@ -0,0 +1,39 @@
+/**
+ * weixin-ilink HTTP 路由
+ */
+import type { Router } from "@zhin.js/host-router";
+import type { Plugin } from "zhin.js";
+import type { WeixinIlinkAdapter } from "./adapter.js";
+import { registerLoginAssistRoutes } from "./login-assist-routes.js";
+
+export function registerRoutes(
+  router: Router,
+  adapter: WeixinIlinkAdapter,
+  root: Plugin,
+): void {
+  registerLoginAssistRoutes(router, root);
+
+  router.get("/api/weixin-ilink/bots", async (ctx) => {
+    try {
+      const bots = Array.from(adapter.bots.values());
+      const data = bots.map((bot) => ({
+        name: bot.$config.name,
+        connected: bot.$connected,
+        status: bot.$connected ? "online" : "offline",
+        hasCredentials: Boolean(bot.hasCredentials),
+      }));
+      ctx.body = {
+        success: true,
+        data,
+        timestamp: new Date().toISOString(),
+      };
+    } catch (error) {
+      ctx.status = 500;
+      ctx.body = {
+        success: false,
+        error: "WEIXIN_ILINK_API_ERROR",
+        message: (error as Error).message,
+      };
+    }
+  });
+}

package/src/silk-transcode.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("../util/logger.js", () => ({
+  logger: {
+    info: vi.fn(),
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+describe("silkToWav", () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  it("returns null when silk-wasm is unavailable", async () => {
+    vi.doMock("silk-wasm", () => {
+      throw new Error("Cannot find module 'silk-wasm'");
+    });
+    const { silkToWav } = await import("./silk-transcode.js");
+    const result = await silkToWav(Buffer.from("fake-silk"));
+    expect(result).toBeNull();
+  });
+
+  it("transcodes silk to WAV successfully", async () => {
+    const fakePcm = new Uint8Array(480); // 10ms at 24kHz mono 16-bit
+    vi.doMock("silk-wasm", () => ({
+      decode: vi.fn().mockResolvedValue({
+        data: fakePcm,
+        duration: 10,
+      }),
+    }));
+    const { silkToWav } = await import("./silk-transcode.js");
+    const result = await silkToWav(Buffer.from("fake-silk"));
+    expect(result).not.toBeNull();
+    expect(result!.length).toBe(44 + fakePcm.byteLength); // WAV header + PCM data
+
+    // Verify WAV header
+    expect(result!.toString("ascii", 0, 4)).toBe("RIFF");
+    expect(result!.toString("ascii", 8, 12)).toBe("WAVE");
+    expect(result!.toString("ascii", 12, 16)).toBe("fmt ");
+    expect(result!.readUInt16LE(20)).toBe(1); // PCM format
+    expect(result!.readUInt16LE(22)).toBe(1); // mono
+    expect(result!.readUInt32LE(24)).toBe(24000); // sample rate
+    expect(result!.readUInt16LE(34)).toBe(16); // bits per sample
+    expect(result!.toString("ascii", 36, 40)).toBe("data");
+  });
+
+  it("returns null when decode fails", async () => {
+    vi.doMock("silk-wasm", () => ({
+      decode: vi.fn().mockRejectedValue(new Error("decode error")),
+    }));
+    const { silkToWav } = await import("./silk-transcode.js");
+    const result = await silkToWav(Buffer.from("bad-silk"));
+    expect(result).toBeNull();
+  });
+});

package/src/silk-transcode.ts

@@ -0,0 +1,74 @@
+import { logger } from "./ilink-logger.js";
+
+/** Default sample rate for Weixin voice messages. */
+const SILK_SAMPLE_RATE = 24_000;
+
+/**
+ * Wrap raw pcm_s16le bytes in a WAV container.
+ * Mono channel, 16-bit signed little-endian.
+ */
+function pcmBytesToWav(pcm: Uint8Array, sampleRate: number): Buffer {
+  const pcmBytes = pcm.byteLength;
+  const totalSize = 44 + pcmBytes;
+  const buf = Buffer.allocUnsafe(totalSize);
+  let offset = 0;
+
+  buf.write("RIFF", offset);
+  offset += 4;
+  buf.writeUInt32LE(totalSize - 8, offset);
+  offset += 4;
+  buf.write("WAVE", offset);
+  offset += 4;
+
+  buf.write("fmt ", offset);
+  offset += 4;
+  buf.writeUInt32LE(16, offset);
+  offset += 4; // fmt chunk size
+  buf.writeUInt16LE(1, offset);
+  offset += 2; // PCM format
+  buf.writeUInt16LE(1, offset);
+  offset += 2; // mono
+  buf.writeUInt32LE(sampleRate, offset);
+  offset += 4;
+  buf.writeUInt32LE(sampleRate * 2, offset);
+  offset += 4; // byte rate (mono 16-bit)
+  buf.writeUInt16LE(2, offset);
+  offset += 2; // block align
+  buf.writeUInt16LE(16, offset);
+  offset += 2; // bits per sample
+
+  buf.write("data", offset);
+  offset += 4;
+  buf.writeUInt32LE(pcmBytes, offset);
+  offset += 4;
+
+  Buffer.from(pcm.buffer, pcm.byteOffset, pcm.byteLength).copy(buf, offset);
+
+  return buf;
+}
+
+/**
+ * Try to transcode a SILK audio buffer to WAV using silk-wasm.
+ * silk-wasm's decode() returns { data: Uint8Array (pcm_s16le), duration: number }.
+ *
+ * Returns a WAV Buffer on success, or null if silk-wasm is unavailable or decoding fails.
+ * Callers should fall back to passing the raw SILK file when null is returned.
+ */
+export async function silkToWav(silkBuf: Buffer): Promise<Buffer | null> {
+  try {
+    const { decode } = await import("silk-wasm");
+
+    logger.debug(`silkToWav: decoding ${silkBuf.length} bytes of SILK`);
+    const result = await decode(silkBuf, SILK_SAMPLE_RATE);
+    logger.debug(
+      `silkToWav: decoded duration=${result.duration}ms pcmBytes=${result.data.byteLength}`,
+    );
+
+    const wav = pcmBytesToWav(result.data, SILK_SAMPLE_RATE);
+    logger.debug(`silkToWav: WAV size=${wav.length}`);
+    return wav;
+  } catch (err) {
+    logger.warn(`silkToWav: transcode failed, will use raw silk err=${String(err)}`);
+    return null;
+  }
+}

package/src/silk-wasm.d.ts

@@ -0,0 +1,6 @@
+declare module "silk-wasm" {
+  export function decode(
+    buf: Buffer,
+    sampleRate: number,
+  ): Promise<{ data: Uint8Array; duration: number }>;
+}

package/src/types.ts

@@ -0,0 +1,26 @@
+export interface WeixinIlinkBotConfig {
+  context: "weixin-ilink";
+  name: string;
+  /** 观测用 bot_agent，默认 Zhin.js/<version> */
+  botAgent?: string;
+  /** iLink API 根地址，默认 https://ilinkai.weixin.qq.com */
+  baseUrl?: string;
+  /** CDN 根地址 */
+  cdnBaseUrl?: string;
+  /** 长轮询超时（ms），默认 35000 */
+  longPollTimeoutMs?: number;
+  /** 直接配置 token（优先于侧车凭证文件） */
+  botToken?: string;
+  typingIndicator?: {
+    enabled?: boolean;
+    /** sendTyping 保活间隔（ms） */
+    keepaliveIntervalMs?: number;
+    privateConfig?: {
+      type?: "typing";
+      autoRemove?: boolean;
+      platformConfig?: Record<string, unknown>;
+    };
+  };
+}
+
+export type { WeixinMessage, MessageItem } from "./ilink-types.js";

package/src/typing-indicator.ts

@@ -0,0 +1,139 @@
+/**
+ * 微信 iLink Typing Indicator（iLink sendTyping API → 微信「正在输入」）
+ */
+import type { WeixinIlinkBot } from "./bot.js";
+import {
+  NativeTypingIndicatorAdapter,
+  TypingIndicatorManager,
+  type TypingIndicator,
+  type TypingIndicatorConfig,
+  type TypingIndicatorOptions,
+} from "@zhin.js/agent";
+import { TypingStatus } from "./ilink-types.js";
+
+export interface WeixinIlinkTypingIndicatorConfig {
+  enabled?: boolean;
+  /** sendTyping 保活间隔（ms），长任务期间重复发送；默认 5000 */
+  keepaliveIntervalMs?: number;
+  privateConfig?: Partial<TypingIndicatorConfig>;
+}
+
+const DEFAULT_CONFIG: WeixinIlinkTypingIndicatorConfig = {
+  enabled: true,
+  keepaliveIntervalMs: 5_000,
+  privateConfig: {
+    type: "typing",
+    autoRemove: true,
+    platformConfig: { keepaliveIntervalMs: 5_000 },
+  },
+};
+
+export class WeixinIlinkTypingIndicatorManager {
+  private manager: TypingIndicatorManager;
+  private config: WeixinIlinkTypingIndicatorConfig;
+  private bot: WeixinIlinkBot;
+
+  constructor(bot: WeixinIlinkBot, config: WeixinIlinkTypingIndicatorConfig = {}) {
+    this.bot = bot;
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      privateConfig: {
+        ...DEFAULT_CONFIG.privateConfig,
+        ...config.privateConfig,
+        platformConfig: {
+          keepaliveIntervalMs: config.keepaliveIntervalMs ?? DEFAULT_CONFIG.keepaliveIntervalMs,
+          ...config.privateConfig?.platformConfig,
+        },
+      },
+    };
+
+    this.manager = new TypingIndicatorManager({
+      type: "typing",
+      autoRemove: true,
+    });
+    this.registerAdapter();
+  }
+
+  private registerAdapter(): void {
+    const adapter = new NativeTypingIndicatorAdapter(
+      "weixin-ilink",
+      async (options: TypingIndicatorOptions) => {
+        const peerId = resolvePeerId(options);
+        if (!peerId) return;
+        await this.bot.sendTypingToUser(peerId, TypingStatus.TYPING);
+      },
+      async (options: TypingIndicatorOptions) => {
+        const peerId = resolvePeerId(options);
+        if (!peerId) return;
+        await this.bot.sendTypingToUser(peerId, TypingStatus.CANCEL);
+      },
+    );
+    this.manager.registerAdapter(adapter);
+  }
+
+  async start(options: {
+    messageId?: string;
+    sessionId: string;
+    userId?: string;
+    groupId?: string;
+    sceneType: "private" | "group";
+  }): Promise<TypingIndicator> {
+    if (!this.config.enabled) {
+      return {
+        start: async () => {},
+        stop: async () => {},
+        isActive: () => false,
+      };
+    }
+
+    const peerId = resolvePeerId(options);
+    const typingOptions: TypingIndicatorOptions = {
+      messageId: options.messageId,
+      sessionId: options.sessionId,
+      userId: peerId,
+      groupId: options.groupId,
+      platform: "weixin-ilink",
+      botId: this.bot.$id,
+      sceneType: "private",
+    };
+
+    return this.manager.start(typingOptions, this.config.privateConfig);
+  }
+
+  async stop(options: {
+    sessionId: string;
+    userId?: string;
+    groupId?: string;
+  }): Promise<void> {
+    const peerId = resolvePeerId(options);
+    await this.manager.stop({
+      sessionId: options.sessionId,
+      userId: peerId,
+      groupId: options.groupId,
+      platform: "weixin-ilink",
+      botId: this.bot.$id,
+      sceneType: "private",
+    });
+  }
+}
+
+function resolvePeerId(options: {
+  userId?: string;
+  sessionId?: string;
+}): string | undefined {
+  const raw = options.userId?.trim()
+    || (options.sessionId ? options.sessionId.split(":").filter(Boolean).at(-1) : undefined);
+  if (!raw) return undefined;
+  const hash = raw.indexOf("#");
+  return hash >= 0 ? raw.slice(0, hash) : raw;
+}
+
+export function enableTypingIndicator(
+  bot: WeixinIlinkBot,
+  config?: WeixinIlinkTypingIndicatorConfig,
+): WeixinIlinkTypingIndicatorManager {
+  const manager = new WeixinIlinkTypingIndicatorManager(bot, config);
+  bot.$typingIndicator = manager;
+  return manager;
+}