@cjhyy/code-shell-chat 0.8.0

package/dist/config.js

@@ -0,0 +1,469 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { defaultWechatDataDirectory, FileWechatCredentialStore } from "./wechat-storage.js";
+export function defaultGatewayConfigPath(env = process.env) {
+    return join(resolveHome(env), ".code-shell", "im-gateway", "config.json");
+}
+export function defaultDesktopControlDescriptorPath(env = process.env) {
+    return join(resolveHome(env), ".code-shell", "im-gateway", "desktop-control.json");
+}
+/** Safe, disabled-by-default starter file used by the Desktop Link editor. */
+export function gatewayConfigTemplate() {
+    return {
+        _help: "Set enabled=true for the channels you want, fill their credentials and allowlists, then start Chat Gateway in CodeShell Desktop.",
+        telegram: {
+            enabled: false,
+            botToken: "",
+            allowedChatIds: [],
+            allowedUserIds: [],
+        },
+        discord: {
+            enabled: false,
+            botToken: "",
+            allowedChannelIds: [],
+            allowedUserIds: [],
+        },
+        slack: {
+            enabled: false,
+            botToken: "",
+            appToken: "",
+            allowedChannelIds: [],
+            allowedUserIds: [],
+        },
+        lark: {
+            enabled: false,
+            appId: "",
+            appSecret: "",
+            allowedChatIds: [],
+            allowedUserIds: [],
+        },
+        dingtalk: {
+            enabled: false,
+            clientId: "",
+            clientSecret: "",
+            allowedConversationIds: [],
+            allowedUserIds: [],
+        },
+        wecom: {
+            enabled: false,
+            botId: "",
+            secret: "",
+            allowedChatIds: [],
+            allowedUserIds: [],
+        },
+        wechat: { enabled: false },
+        matrix: {
+            enabled: false,
+            homeserverUrl: "",
+            accessToken: "",
+            botUserId: "",
+            allowedRoomIds: [],
+            allowedUserIds: [],
+        },
+        mattermost: {
+            enabled: false,
+            serverUrl: "",
+            botToken: "",
+            botUserId: "",
+            allowedChannelIds: [],
+            allowedUserIds: [],
+        },
+        line: {
+            enabled: false,
+            channelSecret: "",
+            channelAccessToken: "",
+            allowedTargetIds: [],
+            allowedUserIds: [],
+        },
+        whatsapp: {
+            enabled: false,
+            accessToken: "",
+            appSecret: "",
+            verifyToken: "",
+            phoneNumberId: "",
+            allowedPhoneNumbers: [],
+        },
+        teams: {
+            enabled: false,
+            appId: "",
+            appPassword: "",
+            appType: "MultiTenant",
+            allowedConversationIds: [],
+            allowedUserIds: [],
+        },
+        webhook: { host: "127.0.0.1", port: 8787, maxBodyBytes: 1048576 },
+        runtime: {
+            maxPending: 1000,
+            maxConcurrent: 4,
+            maxPerTarget: 1,
+            maxMessagesPerUserPerMinute: 20,
+        },
+        notifications: {
+            enabled: false,
+            _help: "Optional proactive Desktop/tunnel event targets, keyed by channel.",
+            targets: {},
+        },
+    };
+}
+export function loadGatewayConfig(opts = {}) {
+    const env = opts.env ?? process.env;
+    const platform = opts.platform ?? process.platform;
+    const configPath = resolve(opts.configPath ?? env.CODE_SHELL_IM_GATEWAY_CONFIG ?? defaultGatewayConfigPath(env));
+    const raw = readRawConfig(configPath);
+    if (existsSync(configPath) && platform !== "win32") {
+        const mode = statSync(configPath).mode & 0o777;
+        if ((mode & 0o077) !== 0) {
+            throw new Error(`IM gateway 配置权限必须为 0600：${configPath}`);
+        }
+    }
+    const channels = loadChannels(raw, env);
+    if (channels.length === 0) {
+        throw new Error("至少配置一个 IM channel；当前支持 Telegram、Discord、Slack、飞书、钉钉、个人微信、企业微信、Matrix、Mattermost、LINE、WhatsApp、Teams");
+    }
+    const configuredCommand = readNonEmptyString(raw.desktop?.command);
+    const configuredArgs = readStringList(raw.desktop?.args, false);
+    const defaultLaunch = defaultDesktopLaunch(platform);
+    const config = {
+        channels,
+        desktop: {
+            descriptorPath: readNonEmptyString(raw.desktop?.descriptorPath) ?? defaultDesktopControlDescriptorPath(env),
+            autoLaunch: raw.desktop?.autoLaunch !== false,
+            command: configuredCommand ?? defaultLaunch.command,
+            args: configuredArgs ?? (configuredCommand ? [] : defaultLaunch.args),
+            startupTimeoutMs: readPositiveNumber(raw.desktop?.startupTimeoutMs) ?? 30_000,
+        },
+        webhook: {
+            host: readNonEmptyString(raw.webhook?.host) ?? "127.0.0.1",
+            port: readPort(raw.webhook?.port) ?? 8787,
+            maxBodyBytes: readPositiveNumber(raw.webhook?.maxBodyBytes) ?? 1_048_576,
+        },
+        runtime: {
+            lockPath: readNonEmptyString(raw.runtime?.lockPath) ??
+                join(resolveHome(env), ".code-shell", "im-gateway", "gateway.lock"),
+            inboxPath: readNonEmptyString(raw.runtime?.inboxPath) ??
+                join(resolveHome(env), ".code-shell", "im-gateway", "inbox.json"),
+            eventCursorPath: readNonEmptyString(raw.runtime?.eventCursorPath) ??
+                join(resolveHome(env), ".code-shell", "im-gateway", "desktop-events.json"),
+            maxPending: readPositiveInteger(raw.runtime?.maxPending) ?? 1_000,
+            maxConcurrent: readPositiveInteger(raw.runtime?.maxConcurrent) ?? 4,
+            maxPerTarget: readPositiveInteger(raw.runtime?.maxPerTarget) ?? 1,
+            maxMessagesPerUserPerMinute: readPositiveInteger(raw.runtime?.maxMessagesPerUserPerMinute) ?? 20,
+            adapterRestartBaseMs: readPositiveInteger(raw.runtime?.adapterRestartBaseMs) ?? 1_000,
+            adapterRestartMaxMs: readPositiveInteger(raw.runtime?.adapterRestartMaxMs) ?? 30_000,
+        },
+        notifications: [],
+    };
+    config.notifications = loadNotificationTargets(raw.notifications, channels);
+    return config;
+}
+function loadNotificationTargets(raw, channels) {
+    if (!raw || raw.enabled === false)
+        return [];
+    const targets = raw.targets;
+    if (!targets || typeof targets !== "object" || Array.isArray(targets)) {
+        throw new Error("notifications.targets 必须是 channel 到 target 数组的映射");
+    }
+    const result = [];
+    for (const [channelName, values] of Object.entries(targets)) {
+        const channel = channels.find(({ channel }) => channel === channelName);
+        if (!channel)
+            throw new Error(`notifications 引用了未启用的 channel：${channelName}`);
+        for (const target of readStringList(values)) {
+            if (!channel.allowedTargetIds.includes(target)) {
+                throw new Error(`notifications target 不在 ${channelName} 会话白名单中：${target}`);
+            }
+            result.push({ channel: channel.channel, target });
+        }
+    }
+    if (result.length === 0)
+        throw new Error("notifications.enabled=true 时至少配置一个 target");
+    if (result.length > 32)
+        throw new Error("notifications targets 最多配置 32 个");
+    return result;
+}
+function loadChannels(raw, env) {
+    return [
+        loadTelegram(raw.telegram, env),
+        loadDiscord(raw.discord, env),
+        loadSlack(raw.slack, env),
+        loadLark(raw.lark, env),
+        loadDingTalk(raw.dingtalk, env),
+        loadWeCom(raw.wecom, env),
+        loadWechat(raw.wechat, env),
+        loadMatrix(raw.matrix, env),
+        loadMattermost(raw.mattermost, env),
+        loadLine(raw.line, env),
+        loadWhatsApp(raw.whatsapp, env),
+        loadTeams(raw.teams, env),
+    ].filter((channel) => channel !== undefined);
+}
+function loadTelegram(raw, env) {
+    const botToken = envString(env, "CODE_SHELL_TELEGRAM_BOT_TOKEN") ?? readNonEmptyString(raw?.botToken);
+    if (!sectionEnabled(raw, botToken))
+        return undefined;
+    return {
+        channel: "telegram",
+        botToken: requireValue("Telegram", "botToken", botToken),
+        ...loadAllowlist("Telegram", raw, env, "CODE_SHELL_TELEGRAM_ALLOWED_CHAT_IDS", "CODE_SHELL_TELEGRAM_ALLOWED_USER_IDS", "allowedChatIds"),
+        apiBaseUrl: readNonEmptyString(raw?.apiBaseUrl)?.replace(/\/$/, "") ?? "https://api.telegram.org",
+    };
+}
+function loadDiscord(raw, env) {
+    const botToken = envString(env, "CODE_SHELL_DISCORD_BOT_TOKEN") ?? readNonEmptyString(raw?.botToken);
+    if (!sectionEnabled(raw, botToken))
+        return undefined;
+    return {
+        channel: "discord",
+        botToken: requireValue("Discord", "botToken", botToken),
+        ...loadAllowlist("Discord", raw, env, "CODE_SHELL_DISCORD_ALLOWED_CHANNEL_IDS", "CODE_SHELL_DISCORD_ALLOWED_USER_IDS", "allowedChannelIds"),
+    };
+}
+function loadSlack(raw, env) {
+    const botToken = envString(env, "CODE_SHELL_SLACK_BOT_TOKEN") ?? readNonEmptyString(raw?.botToken);
+    const appToken = envString(env, "CODE_SHELL_SLACK_APP_TOKEN") ?? readNonEmptyString(raw?.appToken);
+    if (!sectionEnabled(raw, botToken, appToken))
+        return undefined;
+    return {
+        channel: "slack",
+        botToken: requireValue("Slack", "botToken", botToken),
+        appToken: requireValue("Slack", "appToken", appToken),
+        ...loadAllowlist("Slack", raw, env, "CODE_SHELL_SLACK_ALLOWED_CHANNEL_IDS", "CODE_SHELL_SLACK_ALLOWED_USER_IDS", "allowedChannelIds"),
+    };
+}
+function loadLark(raw, env) {
+    const appId = envString(env, "CODE_SHELL_LARK_APP_ID") ?? readNonEmptyString(raw?.appId);
+    const appSecret = envString(env, "CODE_SHELL_LARK_APP_SECRET") ?? readNonEmptyString(raw?.appSecret);
+    if (!sectionEnabled(raw, appId, appSecret))
+        return undefined;
+    return {
+        channel: "lark",
+        appId: requireValue("飞书/Lark", "appId", appId),
+        appSecret: requireValue("飞书/Lark", "appSecret", appSecret),
+        domain: envString(env, "CODE_SHELL_LARK_DOMAIN") ?? readNonEmptyString(raw?.domain),
+        ...loadAllowlist("飞书/Lark", raw, env, "CODE_SHELL_LARK_ALLOWED_CHAT_IDS", "CODE_SHELL_LARK_ALLOWED_USER_IDS", "allowedChatIds"),
+    };
+}
+function loadDingTalk(raw, env) {
+    const clientId = envString(env, "CODE_SHELL_DINGTALK_CLIENT_ID") ?? readNonEmptyString(raw?.clientId);
+    const clientSecret = envString(env, "CODE_SHELL_DINGTALK_CLIENT_SECRET") ?? readNonEmptyString(raw?.clientSecret);
+    if (!sectionEnabled(raw, clientId, clientSecret))
+        return undefined;
+    return {
+        channel: "dingtalk",
+        clientId: requireValue("钉钉", "clientId", clientId),
+        clientSecret: requireValue("钉钉", "clientSecret", clientSecret),
+        ...loadAllowlist("钉钉", raw, env, "CODE_SHELL_DINGTALK_ALLOWED_CONVERSATION_IDS", "CODE_SHELL_DINGTALK_ALLOWED_USER_IDS", "allowedConversationIds"),
+    };
+}
+function loadWeCom(raw, env) {
+    const botId = envString(env, "CODE_SHELL_WECOM_BOT_ID") ?? readNonEmptyString(raw?.botId);
+    const secret = envString(env, "CODE_SHELL_WECOM_SECRET") ?? readNonEmptyString(raw?.secret);
+    if (!sectionEnabled(raw, botId, secret))
+        return undefined;
+    return {
+        channel: "wecom",
+        botId: requireValue("企业微信", "botId", botId),
+        secret: requireValue("企业微信", "secret", secret),
+        ...loadAllowlist("企业微信", raw, env, "CODE_SHELL_WECOM_ALLOWED_CHAT_IDS", "CODE_SHELL_WECOM_ALLOWED_USER_IDS", "allowedChatIds"),
+    };
+}
+function loadWechat(raw, env) {
+    const explicitAccountId = envString(env, "CODE_SHELL_WECHAT_ACCOUNT_ID") ?? readNonEmptyString(raw?.accountId);
+    const explicitToken = envString(env, "CODE_SHELL_WECHAT_BOT_TOKEN") ?? readNonEmptyString(raw?.botToken);
+    const configuredDirectory = envString(env, "CODE_SHELL_WECHAT_CREDENTIALS_DIR") ?? readNonEmptyString(raw?.credentialsDir);
+    if (!sectionEnabled(raw, explicitAccountId, explicitToken, configuredDirectory))
+        return undefined;
+    const credentialsDir = resolve(configuredDirectory ?? defaultWechatDataDirectory(env));
+    const store = new FileWechatCredentialStore(credentialsDir);
+    const stored = store.load(explicitAccountId);
+    const accountId = explicitAccountId ?? stored?.accountId;
+    const token = explicitToken ?? stored?.token;
+    if (!accountId || !token) {
+        throw new Error("个人微信未登录：请先执行 code-shell-chat wechat login");
+    }
+    const defaultOwner = stored?.userId ? [stored.userId] : [];
+    const allowedTargetIds = readCsvOverride(env.CODE_SHELL_WECHAT_ALLOWED_USER_IDS) ??
+        readStringList(raw?.allowedUserIds, false) ??
+        defaultOwner;
+    if (allowedTargetIds.length === 0) {
+        throw new Error("个人微信至少配置 allowedUserIds，或重新扫码以记录管理员身份");
+    }
+    const allowedUserIds = readCsvOverride(env.CODE_SHELL_WECHAT_ALLOWED_USER_IDS) ??
+        readStringList(raw?.allowedUserIds, false) ??
+        defaultOwner;
+    return {
+        channel: "wechat",
+        accountId,
+        token,
+        baseUrl: envString(env, "CODE_SHELL_WECHAT_BASE_URL") ??
+            readNonEmptyString(raw?.baseUrl) ??
+            stored?.baseUrl ??
+            "https://ilinkai.weixin.qq.com",
+        botAgent: envString(env, "CODE_SHELL_WECHAT_BOT_AGENT") ?? readNonEmptyString(raw?.botAgent),
+        protocolVersion: envString(env, "CODE_SHELL_WECHAT_PROTOCOL_VERSION") ??
+            readNonEmptyString(raw?.protocolVersion),
+        allowUnsafeBaseUrl: raw?.allowUnsafeBaseUrl === true,
+        extraCdnDownloadHosts: readCsvOverride(env.CODE_SHELL_WECHAT_EXTRA_CDN_DOWNLOAD_HOSTS) ??
+            readStringList(raw?.extraCdnDownloadHosts, false),
+        credentialsDir,
+        statePath: store.statePath(accountId),
+        allowedTargetIds,
+        allowedUserIds,
+    };
+}
+function loadMatrix(raw, env) {
+    const homeserverUrl = envString(env, "CODE_SHELL_MATRIX_HOMESERVER_URL") ?? readNonEmptyString(raw?.homeserverUrl);
+    const accessToken = envString(env, "CODE_SHELL_MATRIX_ACCESS_TOKEN") ?? readNonEmptyString(raw?.accessToken);
+    if (!sectionEnabled(raw, homeserverUrl, accessToken))
+        return undefined;
+    return {
+        channel: "matrix",
+        homeserverUrl: requireValue("Matrix", "homeserverUrl", homeserverUrl).replace(/\/$/, ""),
+        accessToken: requireValue("Matrix", "accessToken", accessToken),
+        botUserId: envString(env, "CODE_SHELL_MATRIX_BOT_USER_ID") ?? readNonEmptyString(raw?.botUserId),
+        ...loadAllowlist("Matrix", raw, env, "CODE_SHELL_MATRIX_ALLOWED_ROOM_IDS", "CODE_SHELL_MATRIX_ALLOWED_USER_IDS", "allowedRoomIds"),
+    };
+}
+function loadMattermost(raw, env) {
+    const serverUrl = envString(env, "CODE_SHELL_MATTERMOST_SERVER_URL") ?? readNonEmptyString(raw?.serverUrl);
+    const botToken = envString(env, "CODE_SHELL_MATTERMOST_BOT_TOKEN") ?? readNonEmptyString(raw?.botToken);
+    if (!sectionEnabled(raw, serverUrl, botToken))
+        return undefined;
+    return {
+        channel: "mattermost",
+        serverUrl: requireValue("Mattermost", "serverUrl", serverUrl).replace(/\/$/, ""),
+        botToken: requireValue("Mattermost", "botToken", botToken),
+        botUserId: envString(env, "CODE_SHELL_MATTERMOST_BOT_USER_ID") ?? readNonEmptyString(raw?.botUserId),
+        ...loadAllowlist("Mattermost", raw, env, "CODE_SHELL_MATTERMOST_ALLOWED_CHANNEL_IDS", "CODE_SHELL_MATTERMOST_ALLOWED_USER_IDS", "allowedChannelIds"),
+    };
+}
+function loadLine(raw, env) {
+    const channelSecret = envString(env, "CODE_SHELL_LINE_CHANNEL_SECRET") ?? readNonEmptyString(raw?.channelSecret);
+    const channelAccessToken = envString(env, "CODE_SHELL_LINE_CHANNEL_ACCESS_TOKEN") ??
+        readNonEmptyString(raw?.channelAccessToken);
+    if (!sectionEnabled(raw, channelSecret, channelAccessToken))
+        return undefined;
+    return {
+        channel: "line",
+        channelSecret: requireValue("LINE", "channelSecret", channelSecret),
+        channelAccessToken: requireValue("LINE", "channelAccessToken", channelAccessToken),
+        ...loadAllowlist("LINE", raw, env, "CODE_SHELL_LINE_ALLOWED_TARGET_IDS", "CODE_SHELL_LINE_ALLOWED_USER_IDS", "allowedTargetIds"),
+    };
+}
+function loadWhatsApp(raw, env) {
+    const accessToken = envString(env, "CODE_SHELL_WHATSAPP_ACCESS_TOKEN") ?? readNonEmptyString(raw?.accessToken);
+    const appSecret = envString(env, "CODE_SHELL_WHATSAPP_APP_SECRET") ?? readNonEmptyString(raw?.appSecret);
+    const verifyToken = envString(env, "CODE_SHELL_WHATSAPP_VERIFY_TOKEN") ?? readNonEmptyString(raw?.verifyToken);
+    const phoneNumberId = envString(env, "CODE_SHELL_WHATSAPP_PHONE_NUMBER_ID") ?? readNonEmptyString(raw?.phoneNumberId);
+    if (!sectionEnabled(raw, accessToken, appSecret, verifyToken, phoneNumberId))
+        return undefined;
+    return {
+        channel: "whatsapp",
+        accessToken: requireValue("WhatsApp", "accessToken", accessToken),
+        appSecret: requireValue("WhatsApp", "appSecret", appSecret),
+        verifyToken: requireValue("WhatsApp", "verifyToken", verifyToken),
+        phoneNumberId: requireValue("WhatsApp", "phoneNumberId", phoneNumberId),
+        apiVersion: envString(env, "CODE_SHELL_WHATSAPP_API_VERSION") ??
+            readNonEmptyString(raw?.apiVersion) ??
+            "v25.0",
+        ...loadAllowlist("WhatsApp", raw, env, "CODE_SHELL_WHATSAPP_ALLOWED_PHONE_NUMBERS", "CODE_SHELL_WHATSAPP_ALLOWED_PHONE_NUMBERS", "allowedPhoneNumbers"),
+    };
+}
+function loadTeams(raw, env) {
+    const appId = envString(env, "CODE_SHELL_TEAMS_APP_ID") ?? readNonEmptyString(raw?.appId);
+    const appPassword = envString(env, "CODE_SHELL_TEAMS_APP_PASSWORD") ?? readNonEmptyString(raw?.appPassword);
+    if (!sectionEnabled(raw, appId, appPassword))
+        return undefined;
+    return {
+        channel: "teams",
+        appId: requireValue("Microsoft Teams", "appId", appId),
+        appPassword: requireValue("Microsoft Teams", "appPassword", appPassword),
+        appType: envString(env, "CODE_SHELL_TEAMS_APP_TYPE") ??
+            readNonEmptyString(raw?.appType) ??
+            "MultiTenant",
+        tenantId: envString(env, "CODE_SHELL_TEAMS_TENANT_ID") ?? readNonEmptyString(raw?.tenantId),
+        statePath: envString(env, "CODE_SHELL_TEAMS_STATE_PATH") ??
+            readNonEmptyString(raw?.statePath) ??
+            join(resolveHome(env), ".code-shell", "im-gateway", "teams-conversations.json"),
+        ...loadAllowlist("Microsoft Teams", raw, env, "CODE_SHELL_TEAMS_ALLOWED_CONVERSATION_IDS", "CODE_SHELL_TEAMS_ALLOWED_USER_IDS", "allowedConversationIds"),
+    };
+}
+function loadAllowlist(name, raw, env, targetEnv, userEnv, rawTargetKey) {
+    const allowedTargetIds = readCsvOverride(env[targetEnv]) ?? readStringList(raw?.[rawTargetKey]);
+    const allowedUserIds = readCsvOverride(env[userEnv]) ?? readStringList(raw?.allowedUserIds);
+    if (allowedTargetIds.length === 0) {
+        throw new Error(`${name} 至少配置一个会话白名单：${rawTargetKey} 或 ${targetEnv}`);
+    }
+    return { allowedTargetIds, allowedUserIds };
+}
+function readRawConfig(configPath) {
+    if (!existsSync(configPath))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("top-level value must be an object");
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`无法读取 IM gateway 配置 ${configPath}：${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+function sectionEnabled(raw, ...values) {
+    if (raw?.enabled === false)
+        return false;
+    return raw !== undefined || values.some(Boolean);
+}
+function requireValue(channel, key, value) {
+    if (!value)
+        throw new Error(`${channel} 配置不完整：缺少 ${key}`);
+    return value;
+}
+function envString(env, key) {
+    return readNonEmptyString(env[key]);
+}
+function readNonEmptyString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function readStringList(value, fallbackToEmpty = true) {
+    if (value === undefined && !fallbackToEmpty)
+        return undefined;
+    if (!Array.isArray(value))
+        return [];
+    return [
+        ...new Set(value.map(readNonEmptyString).filter((item) => Boolean(item))),
+    ];
+}
+function readCsvOverride(value) {
+    if (value === undefined)
+        return undefined;
+    return [
+        ...new Set(value
+            .split(",")
+            .map((item) => item.trim())
+            .filter(Boolean)),
+    ];
+}
+function readPositiveNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+function readPositiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+function readPort(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65_535
+        ? value
+        : undefined;
+}
+function resolveHome(env) {
+    return env.HOME ?? homedir();
+}
+function defaultDesktopLaunch(platform) {
+    if (platform === "darwin")
+        return { command: "/usr/bin/open", args: ["-a", "code-shell"] };
+    if (platform === "win32")
+        return { command: "code-shell.exe", args: [] };
+    return { command: "code-shell", args: [] };
+}

package/dist/delivery-queue.d.ts

@@ -0,0 +1,93 @@
+import type { ChannelMessage } from "./channel.js";
+export interface DeliveryQueueConfig {
+    path?: string;
+    maxPending: number;
+    maxConcurrent: number;
+    maxPerTarget: number;
+    retryBaseMs: number;
+    retryMaxMs: number;
+    completedTtlMs: number;
+    /**
+     * Directory for spooled attachment bytes. Defaults to `<path>.attachments`.
+     *
+     * Without a spool, a message carrying attachments could not be persisted (its
+     * `load()` is a function), so it stayed in memory only — while the adapter had
+     * ALREADY been told the message was accepted. Telegram advances its long-poll
+     * offset and Slack acks on handler return, so a restart between enqueue and
+     * delivery lost the message permanently: upstream will not resend, and the
+     * durable inbox has no record.
+     */
+    attachmentSpoolDir?: string;
+    /** Largest single attachment to spool. Bigger ones fall back to memory-only. */
+    maxSpooledAttachmentBytes?: number;
+}
+export interface DeliveryQueueStatus {
+    pending: number;
+    inFlight: number;
+    delayed: number;
+}
+export declare class DeliveryBackpressureError extends Error {
+    constructor(limit: number);
+}
+/**
+ * Thrown by the deliver callback when a record can never be routed (e.g. a
+ * persisted message references an adapter that no longer exists after a config
+ * change). The queue drops such records instead of retrying them forever.
+ */
+export declare class UnroutableDeliveryError extends Error {
+    constructor(message: string);
+}
+/**
+ * Durable, bounded inbox. Text webhook deliveries are acknowledged only after
+ * this queue has atomically recorded them; processing happens out of band with
+ * per-target ordering and retry. Lazy attachment functions stay in-memory.
+ */
+export declare class DeliveryQueue {
+    private readonly config;
+    private readonly deliver;
+    private readonly onError;
+    private readonly pending;
+    private readonly completed;
+    private readonly inFlight;
+    private readonly targetInFlight;
+    private mutation;
+    private retryTimer?;
+    private stopped;
+    constructor(config: DeliveryQueueConfig, deliver: (adapterId: string, message: ChannelMessage) => Promise<void>, onError: (error: unknown, message: ChannelMessage) => void);
+    start(): Promise<void>;
+    stop(): void;
+    status(): DeliveryQueueStatus;
+    enqueue(adapterId: string, message: ChannelMessage): Promise<"queued" | "duplicate">;
+    private pump;
+    private process;
+    /** Directory holding spooled attachment bytes, or undefined when not durable. */
+    private spoolDir;
+    /**
+     * Materialize a message's attachments to disk so the record can be persisted.
+     *
+     * Returns undefined when there is nothing to spool, or when spooling fails —
+     * in which case the caller falls back to the old memory-only behaviour rather
+     * than dropping the message.
+     */
+    private spoolAttachments;
+    /** Rebuild attachments whose bytes live in the spool. */
+    private rehydrateAttachments;
+    /**
+     * Delete spool files that no pending record references.
+     *
+     * `discardSpool` covers the normal path, but files can still be orphaned: a
+     * crash between writing the bytes and persisting the record, or the
+     * oversized-attachment fallback that spools nothing yet may have written
+     * earlier attachments of the same message. Without this the directory only
+     * grows, since nothing else ever looks at it.
+     *
+     * Runs once at load(), when the set of live records is exactly known.
+     */
+    private sweepOrphanedSpool;
+    /** Delete a record's spooled files once it will never be delivered again. */
+    private discardSpool;
+    private load;
+    private persist;
+    private pruneCompleted;
+    private withMutation;
+}