multi-openim-channel 0.1.0

package/dist/clients.js

@@ -0,0 +1,329 @@
+/**
+ * Per-account OpenIM SDK client lifecycle. Strict accountId lookups (no
+ * "default" fallback), per-account recovery backoff, and a decoupled
+ * inbound dispatcher slot so this module can be imported without forming
+ * a static cycle with inbound.ts.
+ */
+import { CbEvents, getSDK } from "@openim/client-sdk";
+import { applyFriendGuard } from "./friend-guard.js";
+import { clearManualLoginMarker, refreshAccountToken, writeManualLoginMarker, } from "./token-refresh.js";
+import { formatSdkError, logTag, truncate } from "./utils.js";
+const clients = new Map();
+const refreshing = new Set();
+/**
+ * Per-account exponential-backoff state for token-recovery attempts.
+ *
+ * State machine:
+ *   - First failure: attempt=1, schedule retry +1s; subsequent retries
+ *     follow the sequence 2s/4s/8s/16s/32s.
+ *   - After RECOVERY_BACKOFF_MS_SEQUENCE.length attempts: givenUp=true,
+ *     manual-login marker written. SDK events for this account are silently
+ *     dropped until either startAccountClient succeeds again, or
+ *     GIVENUP_RETRY_AFTER_MS elapses (whichever comes first).
+ *   - The cool-off window lets a long-running gateway survive a transient
+ *     auth-server outage without requiring a manual restart.
+ *   - Any successful login (initial or post-recovery) clears the entry.
+ */
+const RECOVERY_BACKOFF_MS_SEQUENCE = [1_000, 2_000, 4_000, 8_000, 16_000, 32_000];
+const RECOVERY_BACKOFF_STEPS = RECOVERY_BACKOFF_MS_SEQUENCE.length;
+const GIVENUP_RETRY_AFTER_MS = 30 * 60 * 1000;
+const recoveryStateByAccount = new Map();
+function resetRecoveryState(accountId) {
+    const prev = recoveryStateByAccount.get(accountId);
+    if (prev?.pendingTimer)
+        clearTimeout(prev.pendingTimer);
+    recoveryStateByAccount.delete(accountId);
+}
+let inboundDispatcher = async (ctx) => {
+    ctx.logger.warn?.(`${logTag("clients")} inbound dispatcher not registered; dropping message`);
+};
+export function setInboundDispatcher(fn) {
+    inboundDispatcher = fn;
+}
+export function getConnectedClient(accountId) {
+    const id = String(accountId ?? "").trim();
+    if (!id)
+        return null;
+    return clients.get(id) ?? null;
+}
+export function hasConnectedAccountClient(accountId) {
+    return getConnectedClient(accountId) !== null;
+}
+export function connectedClientCount() {
+    return clients.size;
+}
+export function listConnectedAccountIds() {
+    return Array.from(clients.keys());
+}
+function buildHandlers(ctx, state) {
+    const consumeMessage = (msg) => {
+        if (!msg)
+            return;
+        inboundDispatcher(ctx, state, msg).catch((e) => {
+            ctx.logger.error?.(`${logTag("clients")} inbound dispatcher failed (account=${state.config.accountId}): ${formatSdkError(e)}`);
+        });
+    };
+    const onTokenIssue = (reason) => {
+        void recoverAccount(ctx, state, reason);
+    };
+    return {
+        onRecvNewMessage: (event) => {
+            const data = event?.data;
+            if (data)
+                consumeMessage(data);
+        },
+        onRecvNewMessages: (event) => {
+            const list = Array.isArray(event?.data) ? event.data : [];
+            for (const msg of list)
+                consumeMessage(msg);
+        },
+        onRecvOfflineNewMessages: (event) => {
+            const list = Array.isArray(event?.data) ? event.data : [];
+            for (const msg of list)
+                consumeMessage(msg);
+        },
+        onConnectFailed: (evt) => {
+            const errCode = (() => {
+                if (evt && typeof evt === "object") {
+                    const e = evt;
+                    const raw = e.errCode ?? e.data?.errCode;
+                    return Number(raw ?? 0);
+                }
+                return 0;
+            })();
+            onTokenIssue(`OnConnectFailed errCode=${errCode}`);
+        },
+        onUserTokenExpired: () => onTokenIssue("OnUserTokenExpired"),
+        onUserTokenInvalid: () => onTokenIssue("OnUserTokenInvalid"),
+        onKickedOffline: () => onTokenIssue("OnKickedOffline"),
+    };
+}
+function attachHandlers(state) {
+    const { sdk, handlers } = state;
+    sdk.on(CbEvents.OnRecvNewMessage, handlers.onRecvNewMessage);
+    sdk.on(CbEvents.OnRecvNewMessages, handlers.onRecvNewMessages);
+    sdk.on(CbEvents.OnRecvOfflineNewMessages, handlers.onRecvOfflineNewMessages);
+    sdk.on(CbEvents.OnConnectFailed, handlers.onConnectFailed);
+    sdk.on(CbEvents.OnUserTokenExpired, handlers.onUserTokenExpired);
+    sdk.on(CbEvents.OnUserTokenInvalid, handlers.onUserTokenInvalid);
+    sdk.on(CbEvents.OnKickedOffline, handlers.onKickedOffline);
+}
+function detachHandlers(ctx, state) {
+    const { sdk, handlers } = state;
+    try {
+        sdk.off(CbEvents.OnRecvNewMessage, handlers.onRecvNewMessage);
+        sdk.off(CbEvents.OnRecvNewMessages, handlers.onRecvNewMessages);
+        sdk.off(CbEvents.OnRecvOfflineNewMessages, handlers.onRecvOfflineNewMessages);
+        sdk.off(CbEvents.OnConnectFailed, handlers.onConnectFailed);
+        sdk.off(CbEvents.OnUserTokenExpired, handlers.onUserTokenExpired);
+        sdk.off(CbEvents.OnUserTokenInvalid, handlers.onUserTokenInvalid);
+        sdk.off(CbEvents.OnKickedOffline, handlers.onKickedOffline);
+    }
+    catch (e) {
+        ctx.logger.warn?.(`${logTag("clients")} detachHandlers errored (account=${state.config.accountId}): ${formatSdkError(e)}`);
+    }
+}
+function noteRecoveryFailure(accountId) {
+    const now = Date.now();
+    const prev = recoveryStateByAccount.get(accountId);
+    const attempt = (prev?.attempt ?? 0) + 1;
+    if (attempt > RECOVERY_BACKOFF_STEPS) {
+        recoveryStateByAccount.set(accountId, {
+            attempt,
+            nextEarliestAt: Number.POSITIVE_INFINITY,
+            givenUp: true,
+            givenUpAt: now,
+        });
+        return { givenUp: true, attempt };
+    }
+    const delayMs = RECOVERY_BACKOFF_MS_SEQUENCE[attempt - 1] ?? 32_000;
+    recoveryStateByAccount.set(accountId, { attempt, nextEarliestAt: now + delayMs, givenUp: false });
+    return { givenUp: false, attempt };
+}
+function scheduleNextRetry(ctx, state, reason) {
+    const aid = state.config.accountId;
+    const backoff = recoveryStateByAccount.get(aid);
+    if (!backoff || backoff.givenUp)
+        return;
+    if (backoff.pendingTimer)
+        clearTimeout(backoff.pendingTimer);
+    const delay = Math.max(0, backoff.nextEarliestAt - Date.now());
+    backoff.pendingTimer = setTimeout(() => {
+        backoff.pendingTimer = undefined;
+        void recoverAccount(ctx, state, reason);
+    }, delay);
+}
+async function recoverAccount(ctx, state, reason) {
+    const aid = state.config.accountId;
+    const channel = ctx.channel;
+    const backoff = recoveryStateByAccount.get(aid);
+    if (backoff?.givenUp) {
+        const givenUpFor = backoff.givenUpAt ? Date.now() - backoff.givenUpAt : 0;
+        if (givenUpFor < GIVENUP_RETRY_AFTER_MS) {
+            return false;
+        }
+        ctx.logger.info?.(`${logTag("clients")} account=${aid} givenUp cool-off (${Math.round(givenUpFor / 60_000)}min) elapsed; retrying recovery (reason=${reason})`);
+        resetRecoveryState(aid);
+    }
+    if (backoff && Date.now() < backoff.nextEarliestAt && !backoff.pendingTimer) {
+        scheduleNextRetry(ctx, state, reason);
+        return false;
+    }
+    if (backoff && Date.now() < backoff.nextEarliestAt) {
+        return false;
+    }
+    if (refreshing.has(aid)) {
+        return false;
+    }
+    refreshing.add(aid);
+    try {
+        ctx.logger.warn?.(`${logTag("clients")} ${reason} (account=${aid}) — kicking off token-refresh flow (attempt=${(backoff?.attempt ?? 0) + 1})`);
+        const outcome = await refreshAccountToken({
+            ctx,
+            accountId: aid,
+            reason,
+        });
+        if (!outcome.ok || !outcome.token) {
+            const detail = outcome.error ?? "unknown";
+            state.lastError = truncate(detail, 500);
+            const { givenUp, attempt } = noteRecoveryFailure(aid);
+            if (givenUp) {
+                writeManualLoginMarker(ctx, aid, detail);
+                ctx.logger.error?.(`${logTag("clients")} account=${aid} recovery exhausted after ${attempt} attempts; manual login required (last reason: ${reason})`);
+            }
+            else {
+                scheduleNextRetry(ctx, state, reason);
+            }
+            return false;
+        }
+        state.config = {
+            ...state.config,
+            token: outcome.token,
+            userID: outcome.userID ?? state.config.userID,
+        };
+        try {
+            await state.sdk.logout();
+        }
+        catch {
+            // logout failures here are non-fatal: re-login follows
+        }
+        try {
+            await state.sdk.login({
+                userID: state.config.userID,
+                token: state.config.token,
+                wsAddr: state.config.wsAddr,
+                apiAddr: state.config.apiAddr,
+                platformID: state.config.platformID,
+            });
+            state.connected = true;
+            state.lastConnectedAt = Date.now();
+            state.lastError = undefined;
+            clients.set(aid, state);
+            resetRecoveryState(aid);
+            clearManualLoginMarker(channel.tokenRefresh, aid);
+            ctx.logger.info?.(`${logTag("clients")} account=${aid} recovered after token refresh (via=${outcome.via})`);
+            return true;
+        }
+        catch (e) {
+            const detail = formatSdkError(e);
+            state.connected = false;
+            state.lastError = truncate(detail, 500);
+            const { givenUp, attempt } = noteRecoveryFailure(aid);
+            if (givenUp) {
+                writeManualLoginMarker(ctx, aid, detail);
+                ctx.logger.error?.(`${logTag("clients")} account=${aid} relogin exhausted after ${attempt} attempts: ${truncate(detail, 200)}`);
+            }
+            else {
+                ctx.logger.warn?.(`${logTag("clients")} relogin failed after refresh (account=${aid}, attempt=${attempt}): ${truncate(detail, 200)}`);
+                scheduleNextRetry(ctx, state, reason);
+            }
+            return false;
+        }
+    }
+    finally {
+        refreshing.delete(aid);
+    }
+}
+export async function startAccountClient(ctx, account) {
+    const aid = account.accountId;
+    if (clients.has(aid)) {
+        ctx.logger.info?.(`${logTag("clients")} startAccountClient: account=${aid} already started`);
+        return;
+    }
+    const sdk = getSDK();
+    const state = {
+        sdk,
+        config: account,
+        handlers: undefined,
+        connected: false,
+    };
+    applyFriendGuard(sdk, account, ctx.logger);
+    state.handlers = buildHandlers(ctx, state);
+    attachHandlers(state);
+    try {
+        await sdk.login({
+            userID: account.userID,
+            token: account.token,
+            wsAddr: account.wsAddr,
+            apiAddr: account.apiAddr,
+            platformID: account.platformID,
+        });
+        state.connected = true;
+        state.lastConnectedAt = Date.now();
+        clients.set(aid, state);
+        resetRecoveryState(aid);
+        clearManualLoginMarker(ctx.channel.tokenRefresh, aid);
+        ctx.logger.info?.(`${logTag("clients")} account=${aid} connected`);
+    }
+    catch (e) {
+        const detail = formatSdkError(e);
+        state.lastError = truncate(detail, 500);
+        ctx.logger.error?.(`${logTag("clients")} initial login failed (account=${aid}): ${truncate(detail, 200)}`);
+        const recovered = await recoverAccount(ctx, state, "initial login failed");
+        if (!recovered) {
+            detachHandlers(ctx, state);
+        }
+    }
+}
+export async function stopAccountClient(ctx, accountId) {
+    const aid = String(accountId ?? "").trim();
+    if (!aid)
+        return false;
+    const state = clients.get(aid);
+    if (!state) {
+        resetRecoveryState(aid);
+        return false;
+    }
+    clients.delete(aid);
+    resetRecoveryState(aid);
+    detachHandlers(ctx, state);
+    try {
+        await state.sdk.logout();
+    }
+    catch (e) {
+        ctx.logger.warn?.(`${logTag("clients")} logout failed (account=${aid}): ${formatSdkError(e)}`);
+    }
+    return true;
+}
+export async function stopAllClients(ctx) {
+    const ids = Array.from(clients.keys());
+    for (const aid of ids) {
+        await stopAccountClient(ctx, aid);
+    }
+}
+export function snapshotAccountStatus(accountId) {
+    const state = clients.get(accountId);
+    return {
+        accountId,
+        enabled: state ? state.config.enabled : undefined,
+        configured: !!state,
+        running: !!state,
+        connected: state?.connected ?? false,
+        lastConnectedAt: state?.lastConnectedAt,
+        lastError: state?.lastError ?? null,
+    };
+}
+export function _internal_resetClients() {
+    clients.clear();
+    refreshing.clear();
+}

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Configuration normalization. Reads `channels.multi-openim` from the
+ * gateway config:
+ *
+ *   - The single-account fallback (top-level token/wsAddr/apiAddr) is
+ *     intentionally not supported. Every account must be declared under
+ *     `accounts.<id>`.
+ *   - `userID` and `platformID` are auto-derived from JWT claims when
+ *     omitted.
+ *   - Token-refresh mode and manual-login marker path are validated and
+ *     defaulted here.
+ */
+import type { AccountConfig, AccountConfigRaw, ChannelConfig, ChannelConfigRaw, PluginApi } from "./types.js";
+export declare function getChannelConfigRaw(apiOrCfg?: PluginApi | Record<string, unknown>): ChannelConfigRaw;
+export interface NormalizeAccountIssue {
+    accountId: string;
+    reason: string;
+}
+export declare function normalizeAccount(accountId: string, raw: AccountConfigRaw | null | undefined, channelDefaults: {
+    disableFriendSdk: boolean;
+}): {
+    account?: AccountConfig;
+    issue?: NormalizeAccountIssue;
+};
+export interface NormalizedChannelResult {
+    channel: ChannelConfig;
+    issues: NormalizeAccountIssue[];
+}
+export declare function normalizeChannelConfig(apiOrCfg: PluginApi | Record<string, unknown> | undefined, logger?: {
+    warn?: (msg: string) => void;
+}): NormalizedChannelResult;
+export declare function listAccountIds(apiOrCfg?: PluginApi | Record<string, unknown>): string[];
+export declare function listEnabledAccountConfigs(apiOrCfg?: PluginApi | Record<string, unknown>): AccountConfig[];
+export declare function getAccountConfig(apiOrCfg: PluginApi | Record<string, unknown> | undefined, accountId: string): AccountConfig | null;
+export declare function resolveAccountConfig(apiOrCfg: PluginApi | Record<string, unknown> | undefined, accountId?: string): {
+    accountId: string;
+} & Partial<AccountConfig>;

package/dist/config.js

@@ -0,0 +1,256 @@
+/**
+ * Configuration normalization. Reads `channels.multi-openim` from the
+ * gateway config:
+ *
+ *   - The single-account fallback (top-level token/wsAddr/apiAddr) is
+ *     intentionally not supported. Every account must be declared under
+ *     `accounts.<id>`.
+ *   - `userID` and `platformID` are auto-derived from JWT claims when
+ *     omitted.
+ *   - Token-refresh mode and manual-login marker path are validated and
+ *     defaulted here.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CHANNEL_ID } from "./types.js";
+import { decodeJwtPayload, logTag, toFiniteNumber } from "./utils.js";
+const DEFAULT_HEALTH_CHECK_MINUTES = 30;
+const DEFAULT_PLATFORM_ID = 5;
+const VALID_TOKEN_REFRESH_MODES = new Set(["hook", "off", "http"]);
+function getConfigRoot(apiOrCfg) {
+    if (!apiOrCfg || typeof apiOrCfg !== "object")
+        return {};
+    const obj = apiOrCfg;
+    if ("config" in obj && obj.config && typeof obj.config === "object") {
+        return obj.config;
+    }
+    if ("channels" in obj && obj.channels && typeof obj.channels === "object") {
+        return obj;
+    }
+    return {};
+}
+export function getChannelConfigRaw(apiOrCfg) {
+    const root = getConfigRoot(apiOrCfg);
+    const channels = root.channels ?? {};
+    const block = channels[CHANNEL_ID];
+    return (block && typeof block === "object" ? block : {});
+}
+function normalizeStringList(raw) {
+    if (raw == null)
+        return [];
+    if (Array.isArray(raw)) {
+        return raw.map((x) => String(x ?? "").trim()).filter((s) => s.length > 0);
+    }
+    const s = String(raw ?? "").trim();
+    return s ? [s] : [];
+}
+function normalizeHttpRefresh(raw, logger) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const r = raw;
+    const endpoint = String(r.endpoint ?? "").trim();
+    const responseTokenPath = normalizeStringList(r.responseTokenPath);
+    if (!endpoint) {
+        logger?.warn?.(`${logTag("config")} tokenRefresh.http.endpoint missing — http refresh disabled`);
+        return undefined;
+    }
+    if (responseTokenPath.length === 0) {
+        logger?.warn?.(`${logTag("config")} tokenRefresh.http.responseTokenPath missing — http refresh disabled`);
+        return undefined;
+    }
+    const stateFileRaw = String(r.stateFile ?? "").trim();
+    const method = String(r.method ?? "POST").trim().toUpperCase() || "POST";
+    const headersRaw = r.headers && typeof r.headers === "object" ? r.headers : {};
+    const headers = {};
+    for (const [k, v] of Object.entries(headersRaw)) {
+        if (v == null)
+            continue;
+        headers[String(k)] = String(v);
+    }
+    const timeoutMs = toFiniteNumber(r.timeoutMs, 15_000);
+    const responseUserIdPath = normalizeStringList(r.responseUserIdPath);
+    const stateWriteBackRaw = r.stateWriteBack && typeof r.stateWriteBack === "object"
+        ? r.stateWriteBack
+        : null;
+    let stateWriteBack;
+    if (stateWriteBackRaw) {
+        stateWriteBack = {};
+        for (const [field, spec] of Object.entries(stateWriteBackRaw)) {
+            const paths = normalizeStringList(spec);
+            if (paths.length > 0)
+                stateWriteBack[String(field)] = paths;
+        }
+        if (Object.keys(stateWriteBack).length === 0)
+            stateWriteBack = undefined;
+    }
+    const clearOnSuccess = normalizeStringList(r.clearOnSuccess);
+    return {
+        stateFile: stateFileRaw || undefined,
+        endpoint,
+        method,
+        headers: Object.keys(headers).length > 0 ? headers : undefined,
+        body: r.body,
+        timeoutMs,
+        responseTokenPath: responseTokenPath.length === 1 ? responseTokenPath[0] : responseTokenPath,
+        responseUserIdPath: responseUserIdPath.length === 0
+            ? undefined
+            : responseUserIdPath.length === 1
+                ? responseUserIdPath[0]
+                : responseUserIdPath,
+        stateWriteBack,
+        clearOnSuccess: clearOnSuccess.length > 0 ? clearOnSuccess : undefined,
+    };
+}
+function normalizeTokenRefresh(raw, logger) {
+    const rawMode = String(raw?.mode ?? "hook").trim();
+    let mode = VALID_TOKEN_REFRESH_MODES.has(rawMode) ? rawMode : "hook";
+    const markerRaw = String(raw?.manualLoginMarkerPath ?? "").trim();
+    const manualLoginMarkerPath = markerRaw || join(homedir(), ".openclaw", CHANNEL_ID, "manual-login.json");
+    const http = normalizeHttpRefresh(raw?.http, logger);
+    if (mode === "http" && !http) {
+        logger?.warn?.(`${logTag("config")} tokenRefresh.mode="http" but http config invalid — falling back to "off"`);
+        mode = "off";
+    }
+    return {
+        mode,
+        manualLoginMarkerPath,
+        http,
+    };
+}
+function normalizeInboundWhitelist(raw) {
+    const values = Array.isArray(raw)
+        ? raw
+        : typeof raw === "string"
+            ? raw.split(",")
+            : [];
+    const out = [];
+    const seen = new Set();
+    for (const item of values) {
+        const s = String(item ?? "").trim();
+        if (!s || seen.has(s))
+            continue;
+        seen.add(s);
+        out.push(s);
+    }
+    return out;
+}
+function extractAccountHintsFromToken(token) {
+    const payload = decodeJwtPayload(token);
+    if (!payload)
+        return {};
+    const userIDRaw = payload.UserID ?? payload.userID;
+    const userID = String(userIDRaw ?? "").trim();
+    const platformRaw = payload.PlatformID ?? payload.platformID;
+    const platformID = toFiniteNumber(platformRaw, NaN);
+    const hints = {};
+    if (userID)
+        hints.userID = userID;
+    if (Number.isFinite(platformID))
+        hints.platformID = platformID;
+    return hints;
+}
+export function normalizeAccount(accountId, raw, channelDefaults) {
+    if (!raw || typeof raw !== "object") {
+        return { issue: { accountId, reason: "missing account config block" } };
+    }
+    const token = String(raw.token ?? "").trim();
+    const wsAddr = String(raw.wsAddr ?? "").trim();
+    const apiAddr = String(raw.apiAddr ?? "").trim();
+    if (!token)
+        return { issue: { accountId, reason: "missing token" } };
+    if (!wsAddr)
+        return { issue: { accountId, reason: "missing wsAddr" } };
+    if (!apiAddr)
+        return { issue: { accountId, reason: "missing apiAddr" } };
+    const hints = extractAccountHintsFromToken(token);
+    const userID = String(raw.userID ?? hints.userID ?? "").trim();
+    if (!userID) {
+        return {
+            issue: { accountId, reason: "userID missing and JWT lacks UserID claim" },
+        };
+    }
+    const platformID = toFiniteNumber(raw.platformID ?? hints.platformID, DEFAULT_PLATFORM_ID);
+    const enabled = raw.enabled !== false;
+    const requireMention = raw.requireMention !== false;
+    const inboundWhitelist = normalizeInboundWhitelist(raw.inboundWhitelist);
+    const disableFriendSdk = raw.disableFriendSdk ?? channelDefaults.disableFriendSdk;
+    return {
+        account: {
+            accountId,
+            enabled,
+            userID,
+            token,
+            wsAddr,
+            apiAddr,
+            platformID,
+            requireMention,
+            inboundWhitelist,
+            disableFriendSdk,
+        },
+    };
+}
+export function normalizeChannelConfig(apiOrCfg, logger) {
+    const raw = getChannelConfigRaw(apiOrCfg);
+    const enabled = raw.enabled !== false;
+    const healthCheckIntervalMinutes = Math.max(1, toFiniteNumber(raw.healthCheckIntervalMinutes, DEFAULT_HEALTH_CHECK_MINUTES));
+    const disableFriendSdk = raw.disableFriendSdk !== false;
+    const tokenRefresh = normalizeTokenRefresh(raw.tokenRefresh, logger);
+    const topLevel = raw;
+    const offenders = [];
+    for (const k of ["token", "wsAddr", "apiAddr", "userID", "platformID"]) {
+        if (k in topLevel && topLevel[k] !== undefined && topLevel[k] !== null && topLevel[k] !== "") {
+            offenders.push(k);
+        }
+    }
+    if (offenders.length > 0) {
+        logger?.warn?.(`${logTag("config")} top-level field(s) [${offenders.join(", ")}] are ignored — use channels.${CHANNEL_ID}.accounts.<id> instead`);
+    }
+    const accounts = {};
+    const issues = [];
+    const rawAccounts = raw.accounts && typeof raw.accounts === "object" ? raw.accounts : {};
+    for (const [aid, accRaw] of Object.entries(rawAccounts)) {
+        const id = String(aid).trim();
+        if (!id)
+            continue;
+        const { account, issue } = normalizeAccount(id, accRaw, { disableFriendSdk });
+        if (account) {
+            accounts[id] = account;
+        }
+        else if (issue) {
+            issues.push(issue);
+            logger?.warn?.(`${logTag("config")} account "${issue.accountId}" skipped: ${issue.reason}`);
+        }
+    }
+    return {
+        channel: {
+            enabled,
+            healthCheckIntervalMinutes,
+            tokenRefresh,
+            disableFriendSdk,
+            accounts,
+        },
+        issues,
+    };
+}
+export function listAccountIds(apiOrCfg) {
+    const { channel } = normalizeChannelConfig(apiOrCfg);
+    return Object.keys(channel.accounts);
+}
+export function listEnabledAccountConfigs(apiOrCfg) {
+    const { channel } = normalizeChannelConfig(apiOrCfg);
+    return Object.values(channel.accounts).filter((a) => a.enabled);
+}
+export function getAccountConfig(apiOrCfg, accountId) {
+    const id = String(accountId ?? "").trim();
+    if (!id)
+        return null;
+    const { channel } = normalizeChannelConfig(apiOrCfg);
+    return channel.accounts[id] ?? null;
+}
+export function resolveAccountConfig(apiOrCfg, accountId) {
+    const id = String(accountId ?? "").trim();
+    if (!id)
+        return { accountId: "" };
+    const acc = getAccountConfig(apiOrCfg, id);
+    return acc ?? { accountId: id };
+}

package/dist/context.d.ts

@@ -0,0 +1,7 @@
+import type { ChannelConfig, PluginApi, PluginLogger } from "./types.js";
+export interface PluginContext {
+    readonly api: PluginApi;
+    readonly logger: PluginLogger;
+    readonly channel: ChannelConfig;
+}
+export declare function createPluginContext(api: PluginApi, channel: ChannelConfig): PluginContext;

package/dist/context.js

@@ -0,0 +1,8 @@
+const NULL_LOGGER = Object.freeze({});
+export function createPluginContext(api, channel) {
+    return {
+        api,
+        logger: api.logger ?? NULL_LOGGER,
+        channel,
+    };
+}

package/dist/friend-guard.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Optional shield for the OpenIM SDK's friend-relationship methods. When the
+ * channel-level `disableFriendSdk` flag is true (the default), every friend
+ * SDK method on a connected client is replaced by a throwing stub that
+ * surfaces a grep-able error code (`MULTI_OPENIM_FRIEND_API_DISABLED`).
+ *
+ * Use case: when an external system (your own backend, a CRM, a directory
+ * service, etc.) is the authoritative store for friend relationships,
+ * letting the SDK's friend methods run directly would split the source of
+ * truth and — under multi-account load — has been observed to raise
+ * uncaught rejections during token rotation. Operators who want raw SDK
+ * friend behavior can opt out per channel or per account via
+ * `disableFriendSdk: false`.
+ */
+import type { ApiService } from "@openim/client-sdk";
+import type { AccountConfig, PluginLogger } from "./types.js";
+export declare const FRIEND_API_DISABLED_CODE = "MULTI_OPENIM_FRIEND_API_DISABLED";
+export declare function applyFriendGuard(sdk: ApiService, account: AccountConfig, logger?: PluginLogger): number;
+export declare function listGuardedMethods(): readonly string[];