@zhin.js/adapter-weixin-ilink 1.1.0 → 1.1.2

package/lib/ilink-session-guard.js

@@ -1,48 +1,35 @@
-import { logger } from "./ilink-logger.js";
-const SESSION_PAUSE_DURATION_MS = 60 * 60 * 1000;
-/** Error code returned by the server when the bot session has expired. */
+import { logger } from './ilink-logger.js';
 export const SESSION_EXPIRED_ERRCODE = -14;
-const pauseUntilMap = new Map();
-/** Pause all inbound/outbound API calls for `accountId` for one hour. */
-export function pauseSession(accountId) {
-    const until = Date.now() + SESSION_PAUSE_DURATION_MS;
-    pauseUntilMap.set(accountId, until);
-    logger.info(`session-guard: paused accountId=${accountId} until=${new Date(until).toISOString()} (${SESSION_PAUSE_DURATION_MS / 1000}s)`);
-}
-/** Returns `true` when the bot is still within its one-hour cooldown window. */
-export function isSessionPaused(accountId) {
-    const until = pauseUntilMap.get(accountId);
-    if (until === undefined)
-        return false;
-    if (Date.now() >= until) {
-        pauseUntilMap.delete(accountId);
-        return false;
+export const SESSION_PAUSE_DURATION_MS = 60 * 60 * 1000;
+/** Endpoint-owned cooldown state for an authenticated iLink session. */
+export class IlinkSessionGuard {
+    accountId;
+    now;
+    pauseDurationMs;
+    #pauseUntil = 0;
+    constructor(accountId, now = Date.now, pauseDurationMs = SESSION_PAUSE_DURATION_MS) {
+        this.accountId = accountId;
+        this.now = now;
+        this.pauseDurationMs = pauseDurationMs;
     }
-    return true;
-}
-/** Milliseconds remaining until the pause expires (0 when not paused). */
-export function getRemainingPauseMs(accountId) {
-    const until = pauseUntilMap.get(accountId);
-    if (until === undefined)
-        return 0;
-    const remaining = until - Date.now();
-    if (remaining <= 0) {
-        pauseUntilMap.delete(accountId);
+    pause() {
+        this.#pauseUntil = this.now() + this.pauseDurationMs;
+        logger.info(`session-guard: paused accountId=${this.accountId} until=${new Date(this.#pauseUntil).toISOString()} (${this.pauseDurationMs / 1000}s)`);
+    }
+    get paused() {
+        return this.remainingMs > 0;
+    }
+    get remainingMs() {
+        const remaining = this.#pauseUntil - this.now();
+        if (remaining > 0)
+            return remaining;
+        this.#pauseUntil = 0;
         return 0;
     }
-    return remaining;
-}
-/** Throw if the session is currently paused. Call before any API request. */
-export function assertSessionActive(accountId) {
-    if (isSessionPaused(accountId)) {
-        const remainingMin = Math.ceil(getRemainingPauseMs(accountId) / 60_000);
-        throw new Error(`session paused for accountId=${accountId}, ${remainingMin} min remaining (errcode ${SESSION_EXPIRED_ERRCODE})`);
+    assertActive() {
+        const remaining = this.remainingMs;
+        if (remaining === 0)
+            return;
+        throw new Error(`session paused for accountId=${this.accountId}, ${Math.ceil(remaining / 60_000)} min remaining (errcode ${SESSION_EXPIRED_ERRCODE})`);
     }
 }
-/**
- * Reset internal state — only for tests.
- * @internal
- */
-export function _resetForTest() {
-    pauseUntilMap.clear();
-}

package/lib/index.d.ts

@@ -1,5 +1,8 @@
-export { formatInboundContent, formatOutboundSegments, inboundMessageId, resolveWeixinIlinkConfig, segmentLocalPath, sleep, type ResolvedWeixinIlinkConfig, type WeixinIlinkAdapterConfig, type WeixinIlinkEndpointConfig, type WeixinInboundMediaPaths, type WeixinMessageWithMedia, type WeixinWireSegment, } from './protocol.js';
+export { formatInboundContent, formatOutboundSegments, inboundMessageId, resolveWeixinIlinkConfig, segmentLocalPath, sleep, type ResolvedWeixinIlinkConfig, type WeixinIlinkEndpointConfig, type WeixinInboundMediaPaths, type WeixinMessageWithMedia, type WeixinWireSegment, } from './protocol.js';
 export type { WeixinMessage, MessageItem } from './ilink-types.js';
-export type { WeixinIlinkCredentials } from './credentials.js';
+export { WeixinIlinkStateStore, type WeixinIlinkCredentials, } from './credentials.js';
+export { IlinkClientMetadata, sanitizeBotAgent, type IlinkClientMetadataOptions, } from './ilink-meta.js';
+export { WeixinContextTokenStore } from './context-store.js';
+export { IlinkSessionGuard, SESSION_EXPIRED_ERRCODE, SESSION_PAUSE_DURATION_MS, } from './ilink-session-guard.js';
 export { WeixinIlinkClient, weixinIlinkClient, type WeixinIlinkClientEventMap, } from './client.js';
 export { WeixinIlinkEndpoint, type WeixinIlinkEndpointOptions, type WeixinIlinkGetUpdates, type WeixinIlinkNotifyStart, type WeixinIlinkNotifyStop, type WeixinIlinkSendText, } from './endpoint.js';

package/lib/index.js

@@ -1,3 +1,7 @@
 export { formatInboundContent, formatOutboundSegments, inboundMessageId, resolveWeixinIlinkConfig, segmentLocalPath, sleep, } from './protocol.js';
+export { WeixinIlinkStateStore, } from './credentials.js';
+export { IlinkClientMetadata, sanitizeBotAgent, } from './ilink-meta.js';
+export { WeixinContextTokenStore } from './context-store.js';
+export { IlinkSessionGuard, SESSION_EXPIRED_ERRCODE, SESSION_PAUSE_DURATION_MS, } from './ilink-session-guard.js';
 export { WeixinIlinkClient, weixinIlinkClient, } from './client.js';
 export { WeixinIlinkEndpoint, } from './endpoint.js';

package/lib/login.d.ts

@@ -1,4 +1,5 @@
-import { type WeixinIlinkCredentials } from './credentials.js';
+import type { IlinkClientMetadata } from './ilink-meta.js';
+import { type WeixinIlinkCredentials, type WeixinIlinkStateStore } from './credentials.js';
 import type { ResolvedWeixinIlinkConfig } from './protocol.js';
-export declare function resolveCredentials(config: ResolvedWeixinIlinkConfig, signal?: AbortSignal): Promise<WeixinIlinkCredentials>;
-export declare function loginWithQr(config: ResolvedWeixinIlinkConfig, signal?: AbortSignal): Promise<WeixinIlinkCredentials>;
+export declare function resolveCredentials(config: ResolvedWeixinIlinkConfig, metadata: IlinkClientMetadata, state: WeixinIlinkStateStore, signal?: AbortSignal): Promise<WeixinIlinkCredentials>;
+export declare function loginWithQr(config: ResolvedWeixinIlinkConfig, metadata: IlinkClientMetadata, state: WeixinIlinkStateStore, signal?: AbortSignal): Promise<WeixinIlinkCredentials>;

package/lib/login.js

@@ -1,31 +1,34 @@
 /**
- * Resolve iLink bot credentials (env / config / sidecar file / QR login).
+ * Resolve iLink bot credentials (config / endpoint state / QR login).
  * No legacy Plugin / loginAssist dependency — QR URL is logged for manual scan.
  */
 import { apiGetFetch, apiPostFetch } from './ilink-api.js';
-import { buildBaseInfo, DEFAULT_API_BASE_URL } from './ilink-meta.js';
 import { logger } from './ilink-logger.js';
-import { loadCredentials, saveCredentials, } from './credentials.js';
 const DEFAULT_ILINK_BOT_TYPE = '3';
 const QR_LONG_POLL_TIMEOUT_MS = 35_000;
 const LOGIN_TIMEOUT_MS = 480_000;
 function getLocalBotTokenList() {
     return [];
 }
-async function fetchQRCode(apiBaseUrl, botType) {
+async function fetchQRCode(apiBaseUrl, botType, metadata) {
     const rawText = await apiPostFetch({
         baseUrl: apiBaseUrl,
+        metadata,
         endpoint: `ilink/bot/get_bot_qrcode?bot_type=${encodeURIComponent(botType)}`,
-        body: JSON.stringify({ local_token_list: getLocalBotTokenList(), base_info: buildBaseInfo() }),
+        body: JSON.stringify({
+            local_token_list: getLocalBotTokenList(),
+            base_info: metadata.buildBaseInfo(),
+        }),
         label: 'fetchQRCode',
     });
     return JSON.parse(rawText);
 }
-async function pollQRStatus(apiBaseUrl, qrcode, signal) {
+async function pollQRStatus(apiBaseUrl, qrcode, metadata, signal) {
     try {
         const endpoint = `ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`;
         const rawText = await apiGetFetch({
             baseUrl: apiBaseUrl,
+            metadata,
             endpoint,
             timeoutMs: QR_LONG_POLL_TIMEOUT_MS,
             label: 'pollQRStatus',
@@ -64,29 +67,29 @@ function sleepWithAbort(ms, signal) {
         signal?.addEventListener('abort', onAbort, { once: true });
     });
 }
-export async function resolveCredentials(config, signal) {
-    const envToken = process.env.WEIXIN_ILINK_TOKEN?.trim() || config.botToken?.trim();
-    if (envToken) {
-        const stored = loadCredentials(config.id);
+export async function resolveCredentials(config, metadata, state, signal) {
+    const configuredToken = config.botToken?.trim();
+    if (configuredToken) {
+        const stored = state.loadCredentials();
         return {
-            botToken: envToken,
+            botToken: configuredToken,
             ilinkUserId: stored?.ilinkUserId,
             ilinkBotId: stored?.ilinkBotId,
-            baseUrl: config.baseUrl ?? stored?.baseUrl ?? DEFAULT_API_BASE_URL,
+            baseUrl: config.baseUrl,
         };
     }
-    const stored = loadCredentials(config.id);
+    const stored = state.loadCredentials();
     if (stored?.botToken) {
         return {
             ...stored,
-            baseUrl: config.baseUrl ?? stored.baseUrl ?? DEFAULT_API_BASE_URL,
+            baseUrl: config.baseUrl,
         };
     }
-    return loginWithQr(config, signal);
+    return loginWithQr(config, metadata, state, signal);
 }
-export async function loginWithQr(config, signal) {
-    const apiBaseUrl = config.baseUrl ?? DEFAULT_API_BASE_URL;
-    const qr = await fetchQRCode(apiBaseUrl, DEFAULT_ILINK_BOT_TYPE);
+export async function loginWithQr(config, metadata, state, signal) {
+    const apiBaseUrl = config.baseUrl;
+    const qr = await fetchQRCode(apiBaseUrl, DEFAULT_ILINK_BOT_TYPE, metadata);
     const qrcodeUrl = qr.qrcode_img_content || qr.qrcode;
     logger.info(`weixin-ilink QR login for ${config.id}: scan with WeChat ClawBot entry — ${qrcodeUrl.slice(0, 120)}${qrcodeUrl.length > 120 ? '…' : ''}`);
     const deadline = Date.now() + LOGIN_TIMEOUT_MS;
@@ -95,7 +98,7 @@ export async function loginWithQr(config, signal) {
         // stop() 的 AbortSignal：不打满 8 分钟，立即退出登录循环
         if (signal?.aborted)
             throw abortError();
-        const status = await pollQRStatus(currentBaseUrl, qr.qrcode, signal);
+        const status = await pollQRStatus(currentBaseUrl, qr.qrcode, metadata, signal);
         if (status.status === 'scaned_but_redirect' && status.redirect_host) {
             currentBaseUrl = status.redirect_host.startsWith('http')
                 ? status.redirect_host
@@ -106,7 +109,7 @@ export async function loginWithQr(config, signal) {
                 throw new Error('扫码成功但未返回 bot_token');
             }
             const creds = {
-                botToken: status.bot_token ?? loadCredentials(config.id)?.botToken ?? '',
+                botToken: status.bot_token ?? state.loadCredentials()?.botToken ?? '',
                 ilinkUserId: status.ilink_user_id,
                 ilinkBotId: status.ilink_endpoint_id,
                 baseUrl: status.baseurl ?? currentBaseUrl,
@@ -114,7 +117,7 @@ export async function loginWithQr(config, signal) {
             if (!creds.botToken) {
                 throw new Error('binded_redirect 但本地无有效 bot_token');
             }
-            saveCredentials(config.id, creds);
+            state.saveCredentials(creds);
             return creds;
         }
         if (status.status === 'expired') {

package/lib/outbound-media.js

@@ -10,7 +10,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { isMediaRef } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { downloadRemoteImageToTemp } from './upload.js';
 import { getExtensionFromMime } from './mime.js';

package/lib/protocol.d.ts

@@ -2,20 +2,17 @@
  * Weixin iLink protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-import type { ConversationRef, Segment } from '@zhin.js/im-contract';
+import { type ConversationRef, type Segment } from '@zhin.js/im-contract';
 import type { WeixinMessage } from './ilink-types.js';
-/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
-export interface WeixinIlinkAdapterConfig {
-    readonly id?: string;
+/** One expanded Weixin iLink endpoint configuration produced by AdapterIndex. */
+export interface WeixinIlinkEndpointConfig {
+    readonly id: string;
     readonly botAgent?: string;
     readonly baseUrl?: string;
     readonly cdnBaseUrl?: string;
     readonly longPollTimeoutMs?: number;
     readonly botToken?: string;
-    /** Transitional: legacy root `endpoints[]` with `context: weixin-ilink`. */
-    readonly endpoints?: ReadonlyArray<Partial<ResolvedWeixinIlinkConfig> & {
-        readonly context?: string;
-    }>;
+    readonly dataDir?: string;
 }
 export interface ResolvedWeixinIlinkConfig {
     readonly context: 'weixin-ilink';
@@ -25,8 +22,8 @@ export interface ResolvedWeixinIlinkConfig {
     readonly cdnBaseUrl: string;
     readonly longPollTimeoutMs: number;
     readonly botToken?: string;
+    readonly dataDir: string;
 }
-export type WeixinIlinkEndpointConfig = ResolvedWeixinIlinkConfig;
 export interface WeixinWireSegment {
     readonly type: string;
     readonly data?: Record<string, unknown>;
@@ -40,7 +37,7 @@ export interface WeixinInboundMediaPaths {
 export type WeixinMessageWithMedia = WeixinMessage & {
     readonly _media?: WeixinInboundMediaPaths;
 };
-export declare function resolveWeixinIlinkConfig(config?: WeixinIlinkAdapterConfig): ResolvedWeixinIlinkConfig;
+export declare function resolveWeixinIlinkConfig(config: WeixinIlinkEndpointConfig): ResolvedWeixinIlinkConfig;
 /** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */
 export declare function formatInboundContent(msg: WeixinMessageWithMedia): string;
 export declare function weixinInboundSegments(msg: WeixinMessageWithMedia): readonly Segment[];

package/lib/protocol.js

@@ -2,30 +2,30 @@
  * Weixin iLink protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-import { pickCredential } from 'zhin.js/adapter';
-import { isMediaRef } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/im-contract';
 import { bodyFromItemList } from './weixin-inbound.js';
 import { DEFAULT_API_BASE_URL, DEFAULT_CDN_BASE_URL } from './ilink-meta.js';
 const DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000;
-export function resolveWeixinIlinkConfig(config = {}) {
-    const entry = config.endpoints?.find((item) => item.context === 'weixin-ilink');
-    const id = (typeof config.id === 'string' && config.id)
-        || (typeof entry?.id === 'string' && entry.id)
-        || process.env.WEIXIN_ILINK_BOT_NAME
-        || 'weixin-ilink-bot';
-    const botToken = pickCredential(typeof config.botToken === 'string' ? config.botToken.trim() : config.botToken, typeof entry?.botToken === 'string' ? entry.botToken.trim() : entry?.botToken, process.env.WEIXIN_ILINK_TOKEN?.trim());
+export function resolveWeixinIlinkConfig(config) {
+    const id = typeof config.id === 'string' ? config.id.trim() : '';
+    if (!/^[A-Za-z0-9_.-]+$/u.test(id)) {
+        throw new TypeError('Weixin iLink endpoint id must use letters, numbers, dot, underscore, or hyphen');
+    }
+    const botToken = typeof config.botToken === 'string'
+        ? config.botToken.trim() || undefined
+        : undefined;
+    const dataDir = config.dataDir?.trim() || 'data/weixin-ilink';
     // No throw here: missing botToken is resolved later by resolveCredentials()
     // (sidecar credentials file / QR login) during endpoint.start().
     return {
         context: 'weixin-ilink',
         id,
-        botAgent: config.botAgent ?? entry?.botAgent,
-        baseUrl: config.baseUrl ?? entry?.baseUrl ?? DEFAULT_API_BASE_URL,
-        cdnBaseUrl: config.cdnBaseUrl ?? entry?.cdnBaseUrl ?? DEFAULT_CDN_BASE_URL,
-        longPollTimeoutMs: config.longPollTimeoutMs
-            ?? entry?.longPollTimeoutMs
-            ?? DEFAULT_LONG_POLL_TIMEOUT_MS,
+        botAgent: config.botAgent,
+        baseUrl: config.baseUrl ?? DEFAULT_API_BASE_URL,
+        cdnBaseUrl: config.cdnBaseUrl ?? DEFAULT_CDN_BASE_URL,
+        longPollTimeoutMs: config.longPollTimeoutMs ?? DEFAULT_LONG_POLL_TIMEOUT_MS,
         botToken,
+        dataDir,
     };
 }
 /** Build inbound text for OutboundMessageService.receive (gateway owns reply routing). */

package/lib/types.d.ts

@@ -1,2 +1,2 @@
-export type { WeixinIlinkEndpointConfig, WeixinIlinkAdapterConfig, ResolvedWeixinIlinkConfig, } from './protocol.js';
+export type { WeixinIlinkEndpointConfig, ResolvedWeixinIlinkConfig, } from './protocol.js';
 export type { WeixinMessage, MessageItem } from './ilink-types.js';

package/lib/weixin-ilink-runtime-state.js

@@ -1,6 +1,6 @@
 /**
  * Weixin iLink 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `weixin-ilink.endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `weixin-ilink endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
 export const weixinIlinkRuntimeStateToken = defineEndpointRuntimeStateToken('weixin-ilink');

package/lib/weixin-inbound.d.ts

@@ -1,78 +1,32 @@
 import { type WeixinMessage, type MessageItem } from './ilink-types.js';
-/** 立即落盘所有待写（endpoint stop / 测试用）。 */
-export declare function flushContextTokenPersist(accountId?: string): void;
-/**
- * Restore persisted context tokens for an account into the in-memory map.
- * Called once during gateway startAccount to survive restarts.
- */
-export declare function restoreContextTokens(accountId: string): void;
-/** Remove all context tokens for a given account (memory + disk). */
-export declare function clearContextTokensForAccount(accountId: string): void;
-/** Store a context token for a given account+user pair (memory + debounced disk). */
-export declare function setContextToken(accountId: string, userId: string, token: string): void;
-/** Retrieve the cached context token for a given account+user pair. */
-export declare function getContextToken(accountId: string, userId: string): string | undefined;
-/**
- * List all peer userIds that hold a context token for the given account
- * (memory map, already merged with the disk-backed file on restore).
- * Personal WeChat has no contact/profile API; this is the only peer catalog.
- */
-export declare function listContextTokenUserIds(accountId: string): string[];
-/**
- * Find all accountIds that have an active contextToken for the given userId.
- * Used to infer the sending bot account from the recipient address when
- * accountId is not explicitly provided (e.g. cron delivery).
- *
- * Returns all matching accountIds (not just the first) so the caller can
- * detect ambiguity when multiple accounts have sessions with the same user.
- */
-export declare function findAccountIdsByContextToken(accountIds: string[], userId: string): string[];
-/** Inbound context passed to the OpenClaw core pipeline (matches MsgContext shape). */
 export type WeixinMsgContext = {
     Body: string;
     From: string;
     To: string;
     AccountId: string;
-    OriginatingChannel: "openclaw-weixin";
+    OriginatingChannel: 'openclaw-weixin';
     OriginatingTo: string;
     MessageSid: string;
     Timestamp?: number;
-    Provider: "openclaw-weixin";
-    ChatType: "direct";
-    /** Set by monitor after resolveAgentRoute so dispatchReplyFromConfig uses the correct session. */
+    Provider: 'openclaw-weixin';
+    ChatType: 'direct';
     SessionKey?: string;
     context_token?: string;
     MediaUrl?: string;
     MediaPath?: string;
     MediaType?: string;
-    /** Raw message body for framework command authorization. */
     CommandBody?: string;
-    /** Whether the sender is authorized to execute slash commands. */
     CommandAuthorized?: boolean;
 };
-/** Returns true if the message item is a media type (image, video, file, or voice). */
 export declare function isMediaItem(item: MessageItem): boolean;
 export declare function bodyFromItemList(itemList?: MessageItem[]): string;
 export type WeixinInboundMediaOpts = {
-    /** Local path to decrypted image file. */
     decryptedPicPath?: string;
-    /** Local path to transcoded/raw voice file (.wav or .silk). */
     decryptedVoicePath?: string;
-    /** MIME type for the voice file (e.g. "audio/wav" or "audio/silk"). */
     voiceMediaType?: string;
-    /** Local path to decrypted file attachment. */
     decryptedFilePath?: string;
-    /** MIME type for the file attachment (guessed from file_name). */
     fileMediaType?: string;
-    /** Local path to decrypted video file. */
     decryptedVideoPath?: string;
 };
-/**
- * Convert a WeixinMessage from getUpdates to the inbound MsgContext for the core pipeline.
- * Media: only pass MediaPath (local file, after CDN download + decrypt).
- * We never pass MediaUrl — the upstream CDN URL is encrypted/auth-only.
- * Priority when multiple media types present: image > video > file > voice.
- */
 export declare function weixinMessageToMsgContext(msg: WeixinMessage, accountId: string, opts?: WeixinInboundMediaOpts): WeixinMsgContext;
-/** Extract the context_token from an inbound WeixinMsgContext. */
 export declare function getContextTokenFromMsgContext(ctx: WeixinMsgContext): string | undefined;