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

package/lib/endpoint.d.ts

@@ -1,8 +1,10 @@
-import { Endpoint } from 'zhin.js/adapter';
-import type { EndpointControl, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
 import { getUpdates, notifyStart, notifyStop } from './ilink-api.js';
-import { type WeixinIlinkCredentials } from './credentials.js';
+import { IlinkClientMetadata } from './ilink-meta.js';
+import { type WeixinIlinkCredentials, WeixinIlinkStateStore } from './credentials.js';
+import { WeixinContextTokenStore } from './context-store.js';
+import { IlinkSessionGuard } from './ilink-session-guard.js';
 import { sendMessageWeixin } from './weixin-send.js';
 import { type ResolvedWeixinIlinkConfig, type WeixinMessageWithMedia } from './protocol.js';
 import { WeixinIlinkClient } from './client.js';
@@ -13,12 +15,15 @@ export type WeixinIlinkGetUpdates = typeof getUpdates;
 export interface WeixinIlinkEndpointOptions {
     readonly id: CapabilityId;
     readonly config: ResolvedWeixinIlinkConfig;
-    readonly resolveCredentials?: (config: ResolvedWeixinIlinkConfig, signal?: AbortSignal) => Promise<WeixinIlinkCredentials>;
+    readonly resolveCredentials?: (config: ResolvedWeixinIlinkConfig, metadata: IlinkClientMetadata, state: WeixinIlinkStateStore, signal?: AbortSignal) => Promise<WeixinIlinkCredentials>;
     /** Test / internal: override network side effects. */
     readonly notifyStart?: WeixinIlinkNotifyStart;
     readonly notifyStop?: WeixinIlinkNotifyStop;
     readonly getUpdates?: WeixinIlinkGetUpdates;
     readonly sendText?: WeixinIlinkSendText;
+    readonly state?: WeixinIlinkStateStore;
+    readonly contextTokens?: WeixinContextTokenStore;
+    readonly sessionGuard?: IlinkSessionGuard;
 }
 export declare class WeixinIlinkEndpoint extends Endpoint<WeixinIlinkClient> {
     #private;

package/lib/endpoint.js

@@ -1,18 +1,18 @@
-import { Endpoint } from 'zhin.js/adapter';
 /**
  * WeixinIlinkEndpoint — lifecycle, long-poll inbound, outbound send.
  */
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { Endpoint, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { getUpdates, notifyStart, notifyStop } from './ilink-api.js';
-import { configureIlinkMeta } from './ilink-meta.js';
-import { loadSyncBuf, resolveStateDir, saveSyncBuf, } from './credentials.js';
+import { IlinkClientMetadata } from './ilink-meta.js';
+import { WeixinIlinkStateStore, } from './credentials.js';
 import { resolveCredentials } from './login.js';
-import { listContextTokenUserIds, restoreContextTokens, setContextToken, flushContextTokenPersist, } from './context-store.js';
+import { WeixinContextTokenStore, } from './context-store.js';
 import { WeixinConfigManager } from './ilink-config-cache.js';
-import { getRemainingPauseMs, isSessionPaused, pauseSession, SESSION_EXPIRED_ERRCODE, } from './ilink-session-guard.js';
+import { IlinkSessionGuard, SESSION_EXPIRED_ERRCODE, } from './ilink-session-guard.js';
 import { downloadMediaFromItem } from './media-download.js';
 import { sendMessageWeixin } from './weixin-send.js';
 import { materializeOutboundMedia } from './outbound-media.js';
@@ -36,6 +36,10 @@ export class WeixinIlinkEndpoint extends Endpoint {
     #notifyStop;
     #getUpdates;
     #sendText;
+    #state;
+    #contextTokens;
+    #sessionGuard;
+    #metadata;
     #creds = null;
     #pollAbort;
     #pollPromise;
@@ -59,7 +63,12 @@ export class WeixinIlinkEndpoint extends Endpoint {
         this.#notifyStop = options.notifyStop ?? notifyStop;
         this.#getUpdates = options.getUpdates ?? getUpdates;
         this.#sendText = options.sendText ?? sendMessageWeixin;
-        this.client = new WeixinIlinkClient(options.config, () => this.#creds, () => this.#configManager, this.#sendText);
+        this.#state = options.state
+            ?? new WeixinIlinkStateStore(options.config.id, options.config.dataDir);
+        this.#contextTokens = options.contextTokens ?? new WeixinContextTokenStore(this.#state);
+        this.#sessionGuard = options.sessionGuard ?? new IlinkSessionGuard(options.config.id);
+        this.#metadata = new IlinkClientMetadata({ botAgent: options.config.botAgent });
+        this.client = new WeixinIlinkClient(options.config, this.#metadata, () => this.#creds, () => this.#configManager, this.#sendText, this.#contextTokens);
     }
     get hasCredentials() {
         return this.client.authenticated;
@@ -69,16 +78,20 @@ export class WeixinIlinkEndpoint extends Endpoint {
             return;
         this.#started = true;
         try {
-            configureIlinkMeta({ botAgent: this.#options.config.botAgent });
             // QR 登录最长 8 分钟：stop() 必须能打断
             this.#loginAbort = new AbortController();
-            this.#creds = await this.#resolveCredentials(this.#options.config, this.#loginAbort.signal);
-            restoreContextTokens(this.#options.config.id);
+            this.#creds = await this.#resolveCredentials(this.#options.config, this.#metadata, this.#state, this.#loginAbort.signal);
+            this.#contextTokens.restore();
             await this.#notifyStart({
                 baseUrl: this.client.apiBaseUrl,
+                metadata: this.#metadata,
                 token: this.#creds.botToken,
             });
-            this.#configManager = new WeixinConfigManager({ baseUrl: this.client.apiBaseUrl, token: this.#creds.botToken }, (msg) => this.#logger.debug(msg));
+            this.#configManager = new WeixinConfigManager({
+                baseUrl: this.client.apiBaseUrl,
+                metadata: this.#metadata,
+                token: this.#creds.botToken,
+            }, (msg) => this.#logger.debug(msg));
             this.#pollAbort = new AbortController();
             this.#pollPromise = this.#pollLoop(this.#pollAbort.signal);
             this.#startMediaSweep();
@@ -114,10 +127,14 @@ export class WeixinIlinkEndpoint extends Endpoint {
         }
         this.#stopMediaSweep();
         // 防抖中的 context token 落盘，避免 stop 丢尾部写入
-        flushContextTokenPersist(this.#options.config.id);
+        this.#contextTokens.flush();
         if (this.#creds?.botToken) {
             try {
-                await this.#notifyStop({ baseUrl: this.client.apiBaseUrl, token: this.#creds.botToken });
+                await this.#notifyStop({
+                    baseUrl: this.client.apiBaseUrl,
+                    metadata: this.#metadata,
+                    token: this.#creds.botToken,
+                });
             }
             catch (err) {
                 this.#logger.warn(formatCompact({
@@ -151,7 +168,7 @@ export class WeixinIlinkEndpoint extends Endpoint {
             }));
             throw new Error(`missing context_token for peer ${target}`);
         }
-        const outboundDir = path.join(resolveStateDir(), 'media', 'outbound');
+        const outboundDir = this.#state.mediaDirectory('outbound');
         const wire = formatOutboundSegments(payload);
         const materialized = await materializeOutboundMedia(wire, outboundDir);
         const segments = Array.isArray(materialized) ? materialized : [materialized];
@@ -201,7 +218,7 @@ export class WeixinIlinkEndpoint extends Endpoint {
             return;
         const userId = msg.from_user_id ?? '';
         if (msg.context_token && userId) {
-            setContextToken(this.#options.config.id, userId, msg.context_token);
+            this.#contextTokens.set(userId, msg.context_token);
         }
         const conversation = weixinIlinkInboundConversation(String(this.#options.id), userId);
         const replyTo = weixinReplyTo(msg);
@@ -228,18 +245,18 @@ export class WeixinIlinkEndpoint extends Endpoint {
     async #pollLoop(abortSignal) {
         if (!this.#creds?.botToken)
             return;
-        const endpointId = this.#options.config.id;
-        let getUpdatesBuf = loadSyncBuf(endpointId);
+        let getUpdatesBuf = this.#state.loadSyncBuf();
         let nextTimeoutMs = this.#options.config.longPollTimeoutMs;
         let consecutiveFailures = 0;
         while (!abortSignal.aborted) {
-            if (isSessionPaused(endpointId)) {
-                await sleep(getRemainingPauseMs(endpointId), abortSignal);
+            if (this.#sessionGuard.paused) {
+                await sleep(this.#sessionGuard.remainingMs, abortSignal);
                 continue;
             }
             try {
                 const resp = await this.#getUpdates({
                     baseUrl: this.client.apiBaseUrl,
+                    metadata: this.#metadata,
                     token: this.#creds.botToken,
                     get_updates_buf: getUpdatesBuf,
                     timeoutMs: nextTimeoutMs,
@@ -253,9 +270,9 @@ export class WeixinIlinkEndpoint extends Endpoint {
                 if (isApiError) {
                     const sessionExpired = resp.errcode === SESSION_EXPIRED_ERRCODE || resp.ret === SESSION_EXPIRED_ERRCODE;
                     if (sessionExpired) {
-                        pauseSession(endpointId);
+                        this.#sessionGuard.pause();
                         consecutiveFailures = 0;
-                        await sleep(getRemainingPauseMs(endpointId), abortSignal);
+                        await sleep(this.#sessionGuard.remainingMs, abortSignal);
                         continue;
                     }
                     consecutiveFailures += 1;
@@ -276,7 +293,7 @@ export class WeixinIlinkEndpoint extends Endpoint {
                 }
                 if (nextBuf) {
                     getUpdatesBuf = nextBuf;
-                    saveSyncBuf(endpointId, getUpdatesBuf);
+                    this.#state.saveSyncBuf(getUpdatesBuf);
                 }
             }
             catch (err) {
@@ -300,9 +317,6 @@ export class WeixinIlinkEndpoint extends Endpoint {
     async #handleInboundMessage(full) {
         void this.#emitPlatformEvent(`message.${full.message_type ?? 'unknown'}`, full);
         const fromUserId = full.from_user_id ?? '';
-        if (full.context_token && fromUserId) {
-            setContextToken(this.#options.config.id, fromUserId, full.context_token);
-        }
         const mediaOpts = await this.#downloadInboundMedia(full);
         this.admit({ ...full, _media: mediaOpts });
         this.#logger.debug(formatCompact({
@@ -341,7 +355,7 @@ export class WeixinIlinkEndpoint extends Endpoint {
         if (buffer.length > maxBytes) {
             throw new Error(`media exceeds max size ${maxBytes}`);
         }
-        const dir = path.join(resolveStateDir(), 'media', subdir);
+        const dir = this.#state.mediaDirectory(subdir);
         fs.mkdirSync(dir, { recursive: true });
         const resolvedMime = contentType ?? sniffMimeFromBuffer(buffer);
         const ext = originalFilename
@@ -372,7 +386,7 @@ export class WeixinIlinkEndpoint extends Endpoint {
         }
     }
     #sweepInboundMedia() {
-        const dir = path.join(resolveStateDir(), 'media', 'inbound');
+        const dir = this.#state.mediaDirectory('inbound');
         let entries;
         try {
             entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -408,7 +422,7 @@ function createWeixinIlinkEndpointManagement(requireClient) {
         // "好友"只能从会话推导：凡持有 context_token 的对端（来过消息，含重启后从磁盘恢复的）
         // 即为可达私聊对端；昵称不可得，用 user_id 占位并在 remark 注明来源。
         async listFriends() {
-            return listContextTokenUserIds(requireClient().config.id).map((userId) => ({
+            return requireClient().reachableUserIds().map((userId) => ({
                 user_id: userId,
                 nickname: userId,
                 remark: 'ilink: 从会话 context_token 推导，非通讯录',

package/lib/ilink-api.d.ts

@@ -1,7 +1,9 @@
+import { type IlinkClientMetadata } from "./ilink-meta.js";
 import type { GetUploadUrlReq, GetUploadUrlResp, GetUpdatesReq, GetUpdatesResp, NotifyStopResp, NotifyStartResp, SendMessageReq, SendTypingReq, GetConfigResp } from "./ilink-types.js";
-export { buildBaseInfo, sanitizeBotAgent } from "./ilink-meta.js";
+export { IlinkClientMetadata, sanitizeBotAgent } from "./ilink-meta.js";
 export type WeixinApiOptions = {
     baseUrl: string;
+    metadata: IlinkClientMetadata;
     token?: string;
     timeoutMs?: number;
     /** Long-poll timeout for getUpdates (server may hold the request up to this). */
@@ -15,6 +17,7 @@ export type WeixinApiOptions = {
  */
 export declare function apiGetFetch(params: {
     baseUrl: string;
+    metadata: IlinkClientMetadata;
     endpoint: string;
     timeoutMs?: number;
     label: string;
@@ -29,6 +32,7 @@ export declare function apiGetFetch(params: {
  */
 export declare function apiPostFetch(params: {
     baseUrl: string;
+    metadata: IlinkClientMetadata;
     endpoint: string;
     body: string;
     token?: string;
@@ -42,10 +46,7 @@ export declare function apiPostFetch(params: {
  * On client-side timeout (no server response within timeoutMs), returns an empty response
  * with ret=0 so the caller can simply retry. This is normal for long-poll.
  */
-export declare function getUpdates(params: GetUpdatesReq & {
-    baseUrl: string;
-    token?: string;
-    timeoutMs?: number;
+export declare function getUpdates(params: GetUpdatesReq & WeixinApiOptions & {
     /**
      * Optional external abort signal (e.g. from the gateway when stopping the
      * channel). When this aborts, the in-flight long-poll is terminated

package/lib/ilink-api.js

@@ -1,8 +1,8 @@
 import crypto from "node:crypto";
 import { logger } from "./ilink-logger.js";
-import { buildBaseInfo, ILINK_APP_CLIENT_VERSION, ILINK_APP_ID, } from "./ilink-meta.js";
+import { ILINK_APP_ID, } from "./ilink-meta.js";
 import { redactBody, redactUrl } from "./ilink-redact.js";
-export { buildBaseInfo, sanitizeBotAgent } from "./ilink-meta.js";
+export { IlinkClientMetadata, sanitizeBotAgent } from "./ilink-meta.js";
 /** Default timeout for long-poll getUpdates requests. */
 const DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000;
 /** Default timeout for regular API requests (sendMessage, getUploadUrl). */
@@ -18,10 +18,10 @@ function randomWechatUin() {
     return Buffer.from(String(uint32), "utf-8").toString("base64");
 }
 /** Build headers shared by both GET and POST requests. */
-function buildCommonHeaders() {
+function buildCommonHeaders(metadata) {
     const headers = {
         "iLink-App-Id": ILINK_APP_ID,
-        "iLink-App-ClientVersion": String(ILINK_APP_CLIENT_VERSION),
+        "iLink-App-ClientVersion": String(metadata.appClientVersion),
     };
     return headers;
 }
@@ -30,7 +30,7 @@ function buildHeaders(opts) {
         "Content-Type": "application/json",
         AuthorizationType: "ilink_bot_token",
         "X-WECHAT-UIN": randomWechatUin(),
-        ...buildCommonHeaders(),
+        ...buildCommonHeaders(opts.metadata),
     };
     if (opts.token?.trim()) {
         headers.Authorization = `Bearer ${opts.token.trim()}`;
@@ -47,7 +47,7 @@ function buildHeaders(opts) {
 export async function apiGetFetch(params) {
     const base = ensureTrailingSlash(params.baseUrl);
     const url = new URL(params.endpoint, base);
-    const hdrs = buildCommonHeaders();
+    const hdrs = buildCommonHeaders(params.metadata);
     logger.debug(`GET ${redactUrl(url.toString())}`);
     const timeoutMs = params.timeoutMs;
     const controller = timeoutMs != null && timeoutMs > 0 ? new AbortController() : undefined;
@@ -107,7 +107,7 @@ function combineAbortSignals(internal, external) {
 export async function apiPostFetch(params) {
     const base = ensureTrailingSlash(params.baseUrl);
     const url = new URL(params.endpoint, base);
-    const hdrs = buildHeaders({ token: params.token });
+    const hdrs = buildHeaders({ metadata: params.metadata, token: params.token });
     logger.debug(`POST ${redactUrl(url.toString())} body=${redactBody(params.body)}`);
     const controller = params.timeoutMs !== undefined ? new AbortController() : undefined;
     const t = controller != null && params.timeoutMs !== undefined
@@ -148,10 +148,11 @@ export async function getUpdates(params) {
     try {
         const rawText = await apiPostFetch({
             baseUrl: params.baseUrl,
+            metadata: params.metadata,
             endpoint: "ilink/bot/getupdates",
             body: JSON.stringify({
                 get_updates_buf: params.get_updates_buf ?? "",
-                base_info: buildBaseInfo(),
+                base_info: params.metadata.buildBaseInfo(),
             }),
             token: params.token,
             timeoutMs: timeout,
@@ -183,6 +184,7 @@ export async function getUpdates(params) {
 export async function getUploadUrl(params) {
     const rawText = await apiPostFetch({
         baseUrl: params.baseUrl,
+        metadata: params.metadata,
         endpoint: "ilink/bot/getuploadurl",
         body: JSON.stringify({
             filekey: params.filekey,
@@ -196,7 +198,7 @@ export async function getUploadUrl(params) {
             thumb_filesize: params.thumb_filesize,
             no_need_thumb: params.no_need_thumb,
             aeskey: params.aeskey,
-            base_info: buildBaseInfo(),
+            base_info: params.metadata.buildBaseInfo(),
         }),
         token: params.token,
         timeoutMs: params.timeoutMs ?? DEFAULT_API_TIMEOUT_MS,
@@ -209,8 +211,9 @@ export async function getUploadUrl(params) {
 export async function sendMessage(params) {
     await apiPostFetch({
         baseUrl: params.baseUrl,
+        metadata: params.metadata,
         endpoint: "ilink/bot/sendmessage",
-        body: JSON.stringify({ ...params.body, base_info: buildBaseInfo() }),
+        body: JSON.stringify({ ...params.body, base_info: params.metadata.buildBaseInfo() }),
         token: params.token,
         timeoutMs: params.timeoutMs ?? DEFAULT_API_TIMEOUT_MS,
         label: "sendMessage",
@@ -220,11 +223,12 @@ export async function sendMessage(params) {
 export async function getConfig(params) {
     const rawText = await apiPostFetch({
         baseUrl: params.baseUrl,
+        metadata: params.metadata,
         endpoint: "ilink/bot/getconfig",
         body: JSON.stringify({
             ilink_user_id: params.ilinkUserId,
             context_token: params.contextToken,
-            base_info: buildBaseInfo(),
+            base_info: params.metadata.buildBaseInfo(),
         }),
         token: params.token,
         timeoutMs: params.timeoutMs ?? DEFAULT_CONFIG_TIMEOUT_MS,
@@ -237,8 +241,9 @@ export async function getConfig(params) {
 export async function sendTyping(params) {
     await apiPostFetch({
         baseUrl: params.baseUrl,
+        metadata: params.metadata,
         endpoint: "ilink/bot/sendtyping",
-        body: JSON.stringify({ ...params.body, base_info: buildBaseInfo() }),
+        body: JSON.stringify({ ...params.body, base_info: params.metadata.buildBaseInfo() }),
         token: params.token,
         timeoutMs: params.timeoutMs ?? DEFAULT_CONFIG_TIMEOUT_MS,
         label: "sendTyping",
@@ -252,8 +257,9 @@ export async function sendTyping(params) {
 export async function notifyStop(params) {
     const rawText = await apiPostFetch({
         baseUrl: params.baseUrl,
+        metadata: params.metadata,
         endpoint: "ilink/bot/msg/notifystop",
-        body: JSON.stringify({ base_info: buildBaseInfo() }),
+        body: JSON.stringify({ base_info: params.metadata.buildBaseInfo() }),
         token: params.token,
         timeoutMs: params.timeoutMs ?? DEFAULT_CONFIG_TIMEOUT_MS,
         label: "notifyStop",
@@ -266,8 +272,9 @@ export async function notifyStop(params) {
 export async function notifyStart(params) {
     const rawText = await apiPostFetch({
         baseUrl: params.baseUrl,
+        metadata: params.metadata,
         endpoint: "ilink/bot/msg/notifystart",
-        body: JSON.stringify({ base_info: buildBaseInfo() }),
+        body: JSON.stringify({ base_info: params.metadata.buildBaseInfo() }),
         token: params.token,
         timeoutMs: params.timeoutMs ?? DEFAULT_CONFIG_TIMEOUT_MS,
         label: "notifyStart",

package/lib/ilink-config-cache.d.ts

@@ -1,3 +1,4 @@
+import { type WeixinApiOptions } from "./ilink-api.js";
 /** Subset of getConfig fields that we actually need; add new fields here as needed. */
 export interface CachedConfig {
     typingTicket: string;
@@ -7,12 +8,7 @@ export interface CachedConfig {
  * exponential-backoff retry (up to 1h) on failure.
  */
 export declare class WeixinConfigManager {
-    private apiOpts;
-    private log;
-    private cache;
-    constructor(apiOpts: {
-        baseUrl: string;
-        token?: string;
-    }, log: (msg: string) => void);
+    #private;
+    constructor(apiOptions: WeixinApiOptions, log: (msg: string) => void);
     getForUser(userId: string, contextToken?: string): Promise<CachedConfig>;
 }

package/lib/ilink-config-cache.js

@@ -7,39 +7,38 @@ const CONFIG_CACHE_MAX_RETRY_MS = 60 * 60 * 1000;
  * exponential-backoff retry (up to 1h) on failure.
  */
 export class WeixinConfigManager {
-    apiOpts;
-    log;
-    cache = new Map();
-    constructor(apiOpts, log) {
-        this.apiOpts = apiOpts;
-        this.log = log;
+    #cache = new Map();
+    #apiOptions;
+    #log;
+    constructor(apiOptions, log) {
+        this.#apiOptions = apiOptions;
+        this.#log = log;
     }
     async getForUser(userId, contextToken) {
         const now = Date.now();
-        const entry = this.cache.get(userId);
+        const entry = this.#cache.get(userId);
         const shouldFetch = !entry || now >= entry.nextFetchAt;
         if (shouldFetch) {
             let fetchOk = false;
             try {
                 const resp = await getConfig({
-                    baseUrl: this.apiOpts.baseUrl,
-                    token: this.apiOpts.token,
+                    ...this.#apiOptions,
                     ilinkUserId: userId,
                     contextToken,
                 });
                 if (resp.ret === 0) {
-                    this.cache.set(userId, {
+                    this.#cache.set(userId, {
                         config: { typingTicket: resp.typing_ticket ?? "" },
                         everSucceeded: true,
                         nextFetchAt: now + Math.random() * CONFIG_CACHE_TTL_MS,
                         retryDelayMs: CONFIG_CACHE_INITIAL_RETRY_MS,
                     });
-                    this.log(`[weixin] config ${entry?.everSucceeded ? "refreshed" : "cached"} for ${userId}`);
+                    this.#log(`[weixin] config ${entry?.everSucceeded ? "refreshed" : "cached"} for ${userId}`);
                     fetchOk = true;
                 }
             }
             catch (err) {
-                this.log(`[weixin] getConfig failed for ${userId} (ignored): ${String(err)}`);
+                this.#log(`[weixin] getConfig failed for ${userId} (ignored): ${String(err)}`);
             }
             if (!fetchOk) {
                 const prevDelay = entry?.retryDelayMs ?? CONFIG_CACHE_INITIAL_RETRY_MS;
@@ -49,7 +48,7 @@ export class WeixinConfigManager {
                     entry.retryDelayMs = nextDelay;
                 }
                 else {
-                    this.cache.set(userId, {
+                    this.#cache.set(userId, {
                         config: { typingTicket: "" },
                         everSucceeded: false,
                         nextFetchAt: now + CONFIG_CACHE_INITIAL_RETRY_MS,
@@ -58,6 +57,6 @@ export class WeixinConfigManager {
                 }
             }
         }
-        return this.cache.get(userId)?.config ?? { typingTicket: "" };
+        return this.#cache.get(userId)?.config ?? { typingTicket: "" };
     }
 }

package/lib/ilink-logger.d.ts

@@ -5,5 +5,4 @@ export type IlinkLogger = {
     error: (msg: string) => void;
     withAccount: (accountId: string) => IlinkLogger;
 };
-export declare function setIlinkLogger(next: IlinkLogger): void;
 export declare const logger: IlinkLogger;

package/lib/ilink-logger.js

@@ -1,26 +1,12 @@
-let sink = {
-    debug: () => { },
-    info: () => { },
-    warn: (msg) => console.warn(`[weixin-ilink] ${msg}`),
-    error: (msg) => console.error(`[weixin-ilink] ${msg}`),
-    withAccount(accountId) {
-        const prefix = `[weixin-ilink:${accountId}]`;
-        return {
-            debug: (msg) => sink.debug(`${prefix} ${msg}`),
-            info: (msg) => sink.info(`${prefix} ${msg}`),
-            warn: (msg) => sink.warn(`${prefix} ${msg}`),
-            error: (msg) => sink.error(`${prefix} ${msg}`),
-            withAccount: () => this,
-        };
-    },
-};
-export function setIlinkLogger(next) {
-    sink = next;
+function createIlinkLogger(prefix = '[weixin-ilink]') {
+    return Object.freeze({
+        debug: () => { },
+        info: () => { },
+        warn: (msg) => console.warn(`${prefix} ${msg}`),
+        error: (msg) => console.error(`${prefix} ${msg}`),
+        withAccount(accountId) {
+            return createIlinkLogger(`[weixin-ilink:${accountId}]`);
+        },
+    });
 }
-export const logger = {
-    debug: (msg) => sink.debug(msg),
-    info: (msg) => sink.info(msg),
-    warn: (msg) => sink.warn(msg),
-    error: (msg) => sink.error(msg),
-    withAccount: (accountId) => sink.withAccount(accountId),
-};
+export const logger = createIlinkLogger();

package/lib/ilink-meta.d.ts

@@ -2,11 +2,17 @@ import type { BaseInfo } from "./ilink-types.js";
 export declare const ILINK_APP_ID = "bot";
 export declare const DEFAULT_CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
 export declare const DEFAULT_API_BASE_URL = "https://ilinkai.weixin.qq.com";
-export declare function configureIlinkMeta(opts: {
-    botAgent?: string;
-    version?: string;
-}): void;
 export declare function buildClientVersion(version: string): number;
-export declare const ILINK_APP_CLIENT_VERSION: number;
-export declare function sanitizeBotAgent(raw: string | undefined): string;
-export declare function buildBaseInfo(): BaseInfo;
+export declare function sanitizeBotAgent(raw: string | undefined, fallback?: string): string;
+export interface IlinkClientMetadataOptions {
+    readonly botAgent?: string;
+    readonly version?: string;
+}
+/** Immutable request identity owned by one endpoint. */
+export declare class IlinkClientMetadata {
+    readonly channelVersion: string;
+    readonly botAgent: string;
+    readonly appClientVersion: number;
+    constructor(options?: IlinkClientMetadataOptions);
+    buildBaseInfo(): BaseInfo;
+}

package/lib/ilink-meta.js

@@ -6,8 +6,6 @@ export const DEFAULT_CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
 export const DEFAULT_API_BASE_URL = "https://ilinkai.weixin.qq.com";
 const DEFAULT_BOT_AGENT = "Zhin.js";
 const BOT_AGENT_MAX_LEN = 256;
-let channelVersion = "0.0.0";
-let configuredBotAgent;
 function readPackageVersion() {
     try {
         const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
@@ -18,13 +16,7 @@ function readPackageVersion() {
         return "0.0.0";
     }
 }
-channelVersion = readPackageVersion();
-export function configureIlinkMeta(opts) {
-    if (opts.botAgent)
-        configuredBotAgent = opts.botAgent;
-    if (opts.version)
-        channelVersion = opts.version;
-}
+const PACKAGE_VERSION = readPackageVersion();
 export function buildClientVersion(version) {
     const parts = version.split(".").map((p) => parseInt(p, 10));
     const major = parts[0] ?? 0;
@@ -32,25 +24,37 @@ export function buildClientVersion(version) {
     const patch = parts[2] ?? 0;
     return ((major & 0xff) << 16) | ((minor & 0xff) << 8) | (patch & 0xff);
 }
-export const ILINK_APP_CLIENT_VERSION = buildClientVersion(channelVersion);
-export function sanitizeBotAgent(raw) {
+export function sanitizeBotAgent(raw, fallback = DEFAULT_BOT_AGENT) {
     if (!raw || typeof raw !== "string")
-        return configuredBotAgent ?? DEFAULT_BOT_AGENT;
+        return fallback;
     const trimmed = raw.trim();
     if (!trimmed)
-        return configuredBotAgent ?? DEFAULT_BOT_AGENT;
+        return fallback;
     const productRe = /^[A-Za-z0-9_.\-]{1,32}\/[A-Za-z0-9_.+\-]{1,32}$/;
     const tokens = trimmed.split(/\s+/).filter((tok) => productRe.test(tok));
     if (tokens.length === 0)
-        return configuredBotAgent ?? DEFAULT_BOT_AGENT;
+        return fallback;
     const joined = tokens.join(" ");
     if (Buffer.byteLength(joined, "utf-8") <= BOT_AGENT_MAX_LEN)
         return joined;
-    return (configuredBotAgent ?? DEFAULT_BOT_AGENT);
+    return fallback;
 }
-export function buildBaseInfo() {
-    return {
-        channel_version: channelVersion,
-        bot_agent: sanitizeBotAgent(configuredBotAgent),
-    };
+/** Immutable request identity owned by one endpoint. */
+export class IlinkClientMetadata {
+    channelVersion;
+    botAgent;
+    appClientVersion;
+    constructor(options = {}) {
+        this.channelVersion = options.version ?? PACKAGE_VERSION;
+        const defaultBotAgent = `Zhin.js/${this.channelVersion}`;
+        this.botAgent = sanitizeBotAgent(options.botAgent, defaultBotAgent);
+        this.appClientVersion = buildClientVersion(this.channelVersion);
+        Object.freeze(this);
+    }
+    buildBaseInfo() {
+        return {
+            channel_version: this.channelVersion,
+            bot_agent: this.botAgent,
+        };
+    }
 }

package/lib/ilink-session-guard.d.ts

@@ -1,15 +1,14 @@
-/** Error code returned by the server when the bot session has expired. */
 export declare const SESSION_EXPIRED_ERRCODE = -14;
-/** Pause all inbound/outbound API calls for `accountId` for one hour. */
-export declare function pauseSession(accountId: string): void;
-/** Returns `true` when the bot is still within its one-hour cooldown window. */
-export declare function isSessionPaused(accountId: string): boolean;
-/** Milliseconds remaining until the pause expires (0 when not paused). */
-export declare function getRemainingPauseMs(accountId: string): number;
-/** Throw if the session is currently paused. Call before any API request. */
-export declare function assertSessionActive(accountId: string): void;
-/**
- * Reset internal state — only for tests.
- * @internal
- */
-export declare function _resetForTest(): void;
+export declare const SESSION_PAUSE_DURATION_MS: number;
+/** Endpoint-owned cooldown state for an authenticated iLink session. */
+export declare class IlinkSessionGuard {
+    #private;
+    readonly accountId: string;
+    private readonly now;
+    private readonly pauseDurationMs;
+    constructor(accountId: string, now?: () => number, pauseDurationMs?: number);
+    pause(): void;
+    get paused(): boolean;
+    get remainingMs(): number;
+    assertActive(): void;
+}