clawgram 2.0.0

package/dist/history.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * Reading a window of chat history.
+ *
+ * The channel could only ever send. An assistant that is expected to summarize
+ * what a team wrote during a standup needs to read it, and inbound events do not
+ * cover that: under `groupPolicy: "mention"` a message without a mention is
+ * dropped at the gate, and nothing is buffered anywhere.
+ *
+ * Everything here is pure so it can be tested without a Telegram client. The
+ * transport call lives in `GramJsClientManager.listMessages`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARTICIPANTS_MAX_LIMIT = exports.PARTICIPANTS_DEFAULT_LIMIT = exports.HISTORY_MAX_LIMIT = exports.HISTORY_DEFAULT_LIMIT = void 0;
+exports.parseTimeBoundary = parseTimeBoundary;
+exports.parseLimit = parseLimit;
+exports.parseMessageId = parseMessageId;
+exports.parseListMessagesParams = parseListMessagesParams;
+exports.parseListParticipantsParams = parseListParticipantsParams;
+exports.buildHistoryQuery = buildHistoryQuery;
+exports.isChatReadable = isChatReadable;
+exports.isWithinWindow = isWithinWindow;
+exports.normalizeHistoryMessage = normalizeHistoryMessage;
+exports.collectHistoryWindow = collectHistoryWindow;
+exports.HISTORY_DEFAULT_LIMIT = 100;
+exports.HISTORY_MAX_LIMIT = 500;
+/**
+ * Matches `normalize.ts` and `gramjs-client.ts` deliberately.
+ *
+ * GramJS carries ids as `big-integer` instances — plain objects whose `typeof`
+ * is "object", not native `bigint`. A `typeof value === "bigint"` check misses
+ * every one of them, and the failure is silent: `senderId` simply comes back
+ * undefined and a standup summary loses the one field that says who wrote.
+ *
+ * The `[object Object]` guard catches the opposite mistake — passing a whole
+ * Peer instead of the id inside it, which would otherwise produce a plausible
+ * looking string.
+ */
+function toStringId(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    try {
+        const text = String(value);
+        return text && text !== "[object Object]" ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Accepts Unix seconds or anything `Date` can parse (ISO 8601 in practice).
+ *
+ * Milliseconds are converted rather than rejected: a caller reading OpenClaw
+ * metadata has millisecond timestamps at hand, and silently treating 1.7e12 as
+ * seconds would place the window some fifty thousand years out.
+ */
+function parseTimeBoundary(value, field) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (typeof value === "number" && Number.isFinite(value)) {
+        if (value <= 0)
+            throw new Error(`clawgram: ${field} must be a positive timestamp`);
+        return value >= 10_000_000_000 ? Math.floor(value / 1000) : Math.floor(value);
+    }
+    if (typeof value === "string") {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric) && value.trim() !== "") {
+            return parseTimeBoundary(numeric, field);
+        }
+        const parsed = Date.parse(value);
+        if (Number.isNaN(parsed)) {
+            throw new Error(`clawgram: ${field} is not a valid date: ${value}`);
+        }
+        return Math.floor(parsed / 1000);
+    }
+    throw new Error(`clawgram: ${field} must be a timestamp or an ISO 8601 date`);
+}
+/**
+ * `limit` is clamped rather than rejected. A model asking for 10000 messages is
+ * making a scale mistake, not a security one, and failing the whole call would
+ * teach it nothing useful.
+ */
+function parseLimit(value) {
+    if (value === undefined || value === null || value === "")
+        return exports.HISTORY_DEFAULT_LIMIT;
+    const numeric = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(numeric)) {
+        throw new Error("clawgram: limit must be a number");
+    }
+    if (numeric < 1) {
+        throw new Error("clawgram: limit must be at least 1");
+    }
+    return Math.min(Math.floor(numeric), exports.HISTORY_MAX_LIMIT);
+}
+/** Message ids are integers, and confusing one with a date is the bug this exists to prevent. */
+function parseMessageId(value, field) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const numeric = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(numeric) || !Number.isInteger(numeric) || numeric < 1) {
+        throw new Error(`clawgram: ${field} must be a positive message id`);
+    }
+    return numeric;
+}
+function parseListMessagesParams(params) {
+    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat;
+    const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
+    if (!target) {
+        throw new Error("clawgram: list requires a chatId");
+    }
+    // Only `since`/`until` carry dates. `before`/`after` are NOT accepted here:
+    // in OpenClaw's vocabulary they are message ids, and `openclaw message read
+    // --before 12345` would otherwise parse an id as a Unix timestamp and quietly
+    // place the window in 1970.
+    const since = parseTimeBoundary(params.since, "since");
+    const until = parseTimeBoundary(params.until, "until");
+    if (since !== undefined && until !== undefined && since > until) {
+        throw new Error("clawgram: since must not be later than until");
+    }
+    return {
+        target,
+        limit: parseLimit(params.limit),
+        since,
+        until,
+        minId: parseMessageId(params.after, "after"),
+        maxId: parseMessageId(params.before, "before"),
+    };
+}
+exports.PARTICIPANTS_DEFAULT_LIMIT = 200;
+exports.PARTICIPANTS_MAX_LIMIT = 1000;
+/**
+ * Membership is asked for by chat, so a target is required. `limit` is clamped
+ * for the same reason it is clamped when reading history: a large group must
+ * not silently turn into an unbounded response.
+ */
+function parseListParticipantsParams(params) {
+    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat;
+    const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
+    if (!target) {
+        throw new Error("clawgram: participants requires a chatId");
+    }
+    const includeNames = params.includeNames === true || params.includeNames === "true";
+    const rawLimit = params.limit;
+    if (rawLimit === undefined || rawLimit === null || rawLimit === "") {
+        return { target, limit: exports.PARTICIPANTS_DEFAULT_LIMIT, includeNames };
+    }
+    const parsed = Number(rawLimit);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error("clawgram: participants limit must be a positive number");
+    }
+    return { target, limit: Math.min(Math.floor(parsed), exports.PARTICIPANTS_MAX_LIMIT), includeNames };
+}
+/**
+ * Builds the GramJS query for a window.
+ *
+ * `offsetDate` is Unix seconds (`DateLike = number`) and Telegram documents it
+ * exclusive — "messages previous to this date". `until` here is inclusive, so
+ * the bound is shifted by a second and the exact bound is re-applied by
+ * `isWithinWindow` afterwards. There is no server-side lower bound in this
+ * call, which is why `limit` is the real guard: `since` can only be enforced
+ * after the fact.
+ */
+function buildHistoryQuery(args) {
+    const query = { limit: args.limit };
+    if (args.until !== undefined) {
+        query.offsetDate = args.until + 1;
+    }
+    if (args.minId !== undefined) {
+        query.minId = args.minId;
+    }
+    if (args.maxId !== undefined) {
+        query.maxId = args.maxId;
+    }
+    return query;
+}
+function normalizeChatKey(value) {
+    return String(value ?? "").trim().replace(/^@/, "").toLowerCase();
+}
+/**
+ * Read scope for the account, checked before any history call.
+ *
+ * Sending is gated by whoever asks; reading is not, so the scope has to be
+ * declared. This account belongs to a person, not a bot: it sits in family
+ * chats and private conversations alongside the work ones, and a model that
+ * has been talked into reading the wrong chat pulls that correspondence into
+ * a prompt — and from there into whatever it publishes next.
+ *
+ * An absent list means "no restriction", which keeps the plugin generally
+ * usable; a deployment that cares sets `readChats` and gets a hard boundary
+ * rather than a sentence in a prompt that a model may be argued out of.
+ */
+function isChatReadable(target, readChats) {
+    if (readChats === undefined || readChats === null)
+        return true;
+    const entries = (Array.isArray(readChats) ? readChats : [readChats])
+        .map(normalizeChatKey)
+        .filter(Boolean);
+    // An empty list is a configured empty list — deny, rather than silently
+    // reading everything because someone left brackets behind.
+    if (entries.length === 0)
+        return false;
+    if (entries.includes("*"))
+        return true;
+    return entries.includes(normalizeChatKey(target));
+}
+function isWithinWindow(timestamp, since, until) {
+    // A message without a date cannot be placed in the window. Keeping it only
+    // when the window is open avoids silently widening a bounded request.
+    if (timestamp === undefined)
+        return since === undefined && until === undefined;
+    if (since !== undefined && timestamp < since)
+        return false;
+    if (until !== undefined && timestamp > until)
+        return false;
+    return true;
+}
+function readSender(msg, key) {
+    const value = msg?.sender?.[key] ?? msg?._sender?.[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function resolveSenderDisplay(msg) {
+    const first = readSender(msg, "firstName");
+    const last = readSender(msg, "lastName");
+    const joined = [first, last].filter(Boolean).join(" ").trim();
+    if (joined)
+        return joined;
+    return readSender(msg, "title") ?? readSender(msg, "username");
+}
+/**
+ * Deliberately drops `raw`. Inbound events carry it because the runtime may need
+ * the original object; history is read straight into a model's context, where an
+ * unbounded GramJS structure is both expensive and a way for internals to leak
+ * into a prompt.
+ */
+function normalizeHistoryMessage(msg, fallbackChatId) {
+    const messageId = toStringId(msg?.id);
+    if (!messageId)
+        return null;
+    const text = typeof msg?.message === "string" ? msg.message :
+        typeof msg?.text === "string" ? msg.text :
+            undefined;
+    const rawDate = msg?.date;
+    let timestamp;
+    if (rawDate instanceof Date) {
+        timestamp = Math.floor(rawDate.getTime() / 1000);
+    }
+    else if (typeof rawDate === "number" && Number.isFinite(rawDate)) {
+        timestamp = rawDate >= 10_000_000_000 ? Math.floor(rawDate / 1000) : Math.floor(rawDate);
+    }
+    return {
+        messageId,
+        chatId: toStringId(msg?.chatId) ?? fallbackChatId,
+        senderId: toStringId(msg?.senderId) ?? toStringId(msg?.fromId?.userId) ?? toStringId(msg?.fromId?.channelId),
+        senderUsername: readSender(msg, "username"),
+        senderDisplay: resolveSenderDisplay(msg),
+        text,
+        timestamp,
+        sentAt: timestamp === undefined ? undefined : new Date(timestamp * 1000).toISOString(),
+        replyToMessageId: toStringId(msg?.replyTo?.replyToMsgId) ?? toStringId(msg?.replyToMsgId),
+        messageThreadId: toStringId(msg?.replyTo?.replyToTopId) ?? toStringId(msg?.replyToTopId),
+        isOutgoing: msg?.out === true,
+    };
+}
+/**
+ * Normalizes, drops what falls outside the window, and returns oldest first —
+ * reading order, which is what a summary needs. Telegram hands back newest
+ * first, so an unsorted result would have the model reconstruct a conversation
+ * backwards.
+ */
+function collectHistoryWindow(messages, options = {}) {
+    const collected = [];
+    for (const raw of messages ?? []) {
+        const normalized = normalizeHistoryMessage(raw, options.fallbackChatId);
+        if (!normalized)
+            continue;
+        if (!isWithinWindow(normalized.timestamp, options.since, options.until))
+            continue;
+        collected.push(normalized);
+    }
+    return collected.sort((a, b) => {
+        const byTime = (a.timestamp ?? 0) - (b.timestamp ?? 0);
+        if (byTime !== 0)
+            return byTime;
+        return Number(a.messageId) - Number(b.messageId);
+    });
+}

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const channel_1 = require("./channel");
+const cli_1 = require("./cli");
+const plugin = {
+    id: 'clawgram',
+    name: 'Clawgram',
+    description: "Connect your personal Telegram account to OpenClaw via MTProto. Your AI assistant responds as you.",
+    register(api) {
+        const runtimes = new Map();
+        api.registerCli(({ program, config }) => {
+            (0, cli_1.registerTelegramUserbotCli)(program, config);
+        }, {
+            commands: (0, cli_1.getTelegramUserbotCliDescriptors)().map((entry) => entry.name),
+            descriptors: (0, cli_1.getTelegramUserbotCliDescriptors)()
+        });
+        api.registerChannel({ plugin: (0, channel_1.createChannelPlugin)(runtimes) });
+    }
+};
+exports.default = plugin;

package/dist/joins.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOINS_JOURNAL_MAX_RECORDS = exports.JOINS_MAX_LIMIT = exports.JOINS_DEFAULT_LIMIT = void 0;
+exports.parseJoinEvent = parseJoinEvent;
+exports.resolveJoinsJournalPath = resolveJoinsJournalPath;
+exports.readJoinRecords = readJoinRecords;
+exports.appendJoinRecord = appendJoinRecord;
+exports.selectJoinRecords = selectJoinRecords;
+exports.parseJoinsParams = parseJoinsParams;
+/**
+ * "Someone added this account to a chat" — the one event an assistant needs to
+ * learn where it is expected to work, and who put it there.
+ *
+ * Telegram delivers it as a service message, which the `NewMessage` subscription
+ * deliberately drops, so it is recognised here from raw updates instead. Only
+ * additions of THIS account are recorded: who else joins a chat is none of our
+ * business and would turn the journal into surveillance.
+ */
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const normalize_js_1 = require("./normalize.js");
+exports.JOINS_DEFAULT_LIMIT = 50;
+exports.JOINS_MAX_LIMIT = 500;
+/** The journal answers "recently", not "since the beginning of time". */
+exports.JOINS_JOURNAL_MAX_RECORDS = 2000;
+function chatIdOf(rawMessage) {
+    return (0, normalize_js_1.toStringId)(rawMessage?.chatId) ??
+        (0, normalize_js_1.toPeerChannelId)(rawMessage?.peerId?.channelId) ??
+        (0, normalize_js_1.toPeerChatId)(rawMessage?.peerId?.chatId);
+}
+function atOf(rawMessage) {
+    const seconds = Number(rawMessage?.date);
+    if (Number.isFinite(seconds) && seconds > 0) {
+        return new Date(seconds * 1000).toISOString();
+    }
+    // A service message without a usable date is still a real event; it is
+    // stamped on arrival rather than dropped.
+    return new Date().toISOString();
+}
+function containsId(users, selfId) {
+    if (!Array.isArray(users))
+        return false;
+    return users.some((entry) => (0, normalize_js_1.toStringId)(entry) === selfId);
+}
+/**
+ * Returns the join event when THIS account was added, otherwise undefined.
+ * Everything is read defensively: raw updates arrive untyped and malformed
+ * input must not take the channel down.
+ */
+function parseJoinEvent(rawMessage, selfId) {
+    if (!selfId)
+        return undefined;
+    const action = rawMessage?.action;
+    const className = typeof action?.className === "string" ? action.className : undefined;
+    if (!className)
+        return undefined;
+    const chatId = chatIdOf(rawMessage);
+    if (!chatId)
+        return undefined;
+    const base = {
+        chatId,
+        at: atOf(rawMessage),
+        messageId: (0, normalize_js_1.toStringId)(rawMessage?.id),
+    };
+    const fromId = (0, normalize_js_1.toStringId)(rawMessage?.fromId?.userId) ?? (0, normalize_js_1.toStringId)(rawMessage?.senderId);
+    if (className === "MessageActionChatAddUser") {
+        if (!containsId(action?.users, selfId))
+            return undefined;
+        return { ...base, via: "added", inviterId: fromId };
+    }
+    if (className === "MessageActionChatJoinedByLink") {
+        // The same message is emitted when other people join by link, so it only
+        // concerns us when we are the one who joined.
+        if (fromId !== undefined && fromId !== selfId)
+            return undefined;
+        return { ...base, via: "link", inviterId: (0, normalize_js_1.toStringId)(action?.inviterId) };
+    }
+    if (className === "MessageActionChatCreate") {
+        if (!containsId(action?.users, selfId))
+            return undefined;
+        return { ...base, via: "created", inviterId: fromId };
+    }
+    return undefined;
+}
+function resolveJoinsJournalPath(accountCfg, accountId) {
+    const configured = accountCfg?.joinsJournalPath;
+    if (typeof configured === "string" && configured.trim().length > 0) {
+        return configured.trim();
+    }
+    const safeAccount = accountId.replace(/[^A-Za-z0-9._-]/g, "_");
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "state", "clawgram", `joins-${safeAccount}.jsonl`);
+}
+function readJoinRecords(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return [];
+    return (0, node_fs_1.readFileSync)(path, "utf8")
+        .split("\n")
+        .filter((line) => line.trim().length > 0)
+        .map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return undefined;
+        }
+    })
+        .filter((entry) => entry !== undefined);
+}
+/**
+ * Appends one event, keeping the journal bounded. A repeated add to the same
+ * chat is kept: being re-added after a removal is itself information.
+ */
+function appendJoinRecord(path, event) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    (0, node_fs_1.appendFileSync)(path, JSON.stringify(event) + "\n");
+    const records = readJoinRecords(path);
+    if (records.length > exports.JOINS_JOURNAL_MAX_RECORDS) {
+        const kept = records.slice(records.length - exports.JOINS_JOURNAL_MAX_RECORDS);
+        (0, node_fs_1.writeFileSync)(path, kept.map((entry) => JSON.stringify(entry)).join("\n") + "\n");
+    }
+}
+function selectJoinRecords(records, args) {
+    const filtered = args.since
+        ? records.filter((entry) => typeof entry.at === "string" && entry.at >= args.since)
+        : records;
+    return filtered.slice(Math.max(0, filtered.length - args.limit));
+}
+function parseJoinsParams(params) {
+    const rawSince = params.since;
+    let since;
+    if (rawSince !== undefined && rawSince !== null && rawSince !== "") {
+        if (typeof rawSince !== "string" || Number.isNaN(Date.parse(rawSince))) {
+            throw new Error("clawgram: joins since must be an ISO-8601 timestamp");
+        }
+        since = new Date(rawSince).toISOString();
+    }
+    const rawLimit = params.limit;
+    if (rawLimit === undefined || rawLimit === null || rawLimit === "") {
+        return { since, limit: exports.JOINS_DEFAULT_LIMIT };
+    }
+    const parsed = Number(rawLimit);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error("clawgram: joins limit must be a positive number");
+    }
+    return { since, limit: Math.min(Math.floor(parsed), exports.JOINS_MAX_LIMIT) };
+}

package/dist/normalize.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toStringId = toStringId;
+exports.toPeerChatId = toPeerChatId;
+exports.toPeerChannelId = toPeerChannelId;
+exports.normalizeTelegramEvent = normalizeTelegramEvent;
+function toStringId(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    try {
+        return String(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function inferChatType(chatId) {
+    if (chatId.startsWith("-100"))
+        return "channel";
+    if (chatId.startsWith("-"))
+        return "group";
+    return "direct";
+}
+function inferTelegramChatType(msg, chatId) {
+    if (msg?.isGroup === true)
+        return "group";
+    if (msg?.isChannel === true)
+        return "channel";
+    if (chatId.startsWith("-100") && msg?.post !== true)
+        return "group";
+    return inferChatType(chatId);
+}
+function toPeerChatId(value) {
+    const id = toStringId(value);
+    if (!id)
+        return undefined;
+    return `-${id.replace(/^-/, "")}`;
+}
+function toPeerChannelId(value) {
+    const id = toStringId(value);
+    if (!id)
+        return undefined;
+    return `-100${id.replace(/^-100|-/, "")}`;
+}
+function toTimestamp(value) {
+    if (value instanceof Date) {
+        return value.getTime();
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        // GramJS message.date may arrive as a Unix timestamp in seconds.
+        // OpenClaw expects millisecond timestamps for prompt/runtime metadata.
+        return value < 10_000_000_000 ? value * 1000 : value;
+    }
+    return undefined;
+}
+function resolveMessageThreadId(msg) {
+    const isForumTopic = msg?.replyTo?.forumTopic === true || msg?.forumTopic === true;
+    if (!isForumTopic) {
+        return undefined;
+    }
+    const topId = toStringId(msg?.replyTo?.replyToTopId) ??
+        toStringId(msg?.replyToTopId);
+    if (topId) {
+        return topId;
+    }
+    return (toStringId(msg?.replyTo?.replyToMsgId) ??
+        toStringId(msg?.replyToMsgId));
+}
+function normalizeTelegramEvent(event, accountId) {
+    const msg = event?.message;
+    if (!msg)
+        return null;
+    const chatId = toStringId(msg.chatId) ??
+        toStringId(event?.chatId) ??
+        toPeerChannelId(msg.peerId?.channelId) ??
+        toPeerChatId(msg.peerId?.chatId) ??
+        toStringId(msg.peerId?.userId);
+    const messageId = toStringId(msg.id);
+    if (!chatId || !messageId)
+        return null;
+    const senderId = toStringId(msg.senderId) ??
+        toStringId(msg.fromId?.userId) ??
+        toStringId(msg.fromId?.channelId);
+    const replyToMessageId = toStringId(msg.replyTo?.replyToMsgId) ??
+        toStringId(msg.replyToMsgId);
+    const messageThreadId = resolveMessageThreadId(msg);
+    const text = typeof msg.message === "string"
+        ? msg.message
+        : typeof msg.text === "string"
+            ? msg.text
+            : undefined;
+    const chatType = inferTelegramChatType(msg, chatId);
+    const senderUsername = typeof msg.sender?.username === "string"
+        ? msg.sender.username
+        : typeof msg._sender?.username === "string"
+            ? msg._sender.username
+            : undefined;
+    const senderDisplay = typeof msg.sender?.firstName === "string"
+        ? [msg.sender.firstName, msg.sender.lastName].filter(Boolean).join(" ").trim()
+        : typeof msg._sender?.firstName === "string"
+            ? [msg._sender.firstName, msg._sender.lastName].filter(Boolean).join(" ").trim()
+            : undefined;
+    const replyTarget = msg.inputChat ??
+        msg._inputChat ??
+        msg.inputSender ??
+        msg._inputSender ??
+        msg.peerId;
+    return {
+        channel: "clawgram",
+        accountId,
+        chatId,
+        messageThreadId,
+        senderId,
+        senderUsername,
+        senderDisplay: senderDisplay || undefined,
+        messageId,
+        text,
+        replyToMessageId,
+        chatType,
+        timestamp: toTimestamp(msg.date),
+        isOutgoing: Boolean(msg.out),
+        replyTarget,
+        raw: event
+    };
+}

package/dist/proxy-config.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProxyConfig = resolveProxyConfig;
+exports.buildTelegramClientOptions = buildTelegramClientOptions;
+exports.describeProxy = describeProxy;
+const CONNECTION_RETRIES = 5;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toFiniteNumber(value) {
+    if (typeof value === "number") {
+        return value;
+    }
+    if (typeof value === "string" && value.trim()) {
+        return Number(value.trim());
+    }
+    return Number.NaN;
+}
+function resolveProxyHost(value) {
+    const host = typeof value === "string" ? value.trim() : "";
+    if (!host) {
+        throw new Error("clawgram: proxy.ip must be a non-empty hostname or IP address.");
+    }
+    return host;
+}
+function resolveProxyPort(value) {
+    const port = toFiniteNumber(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error("clawgram: proxy.port must be an integer between 1 and 65535.");
+    }
+    return port;
+}
+function resolveSocksType(value) {
+    const socksType = toFiniteNumber(value);
+    if (socksType !== 4 && socksType !== 5) {
+        throw new Error("clawgram: proxy.socksType must be 4 (SOCKS4) or 5 (SOCKS5).");
+    }
+    return socksType;
+}
+function resolveProxyCredential(value, field) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`clawgram: proxy.${field} must be a string.`);
+    }
+    return value.trim() ? value : undefined;
+}
+function resolveProxyTimeout(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const timeout = toFiniteNumber(value);
+    if (!Number.isFinite(timeout) || timeout <= 0) {
+        throw new Error("clawgram: proxy.timeout must be a positive number of seconds.");
+    }
+    return timeout;
+}
+/**
+ * Normalizes and validates the optional per-account `proxy` config.
+ * Returns `undefined` when no proxy is configured; throws when one is
+ * configured but unusable, so a broken proxy never silently falls back to a
+ * direct connection.
+ */
+function resolveProxyConfig(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (!isPlainObject(value)) {
+        throw new Error("clawgram: proxy must be an object.");
+    }
+    const ip = resolveProxyHost(value.ip);
+    const port = resolveProxyPort(value.port);
+    const socksType = resolveSocksType(value.socksType);
+    const username = resolveProxyCredential(value.username, "username");
+    const password = resolveProxyCredential(value.password, "password");
+    const timeout = resolveProxyTimeout(value.timeout);
+    return {
+        ip,
+        port,
+        socksType,
+        ...(username ? { username } : {}),
+        ...(password ? { password } : {}),
+        ...(timeout !== undefined ? { timeout } : {}),
+    };
+}
+/**
+ * Builds the TelegramClient options. Without a proxy the options stay exactly as
+ * before this feature existed.
+ */
+function buildTelegramClientOptions(proxy) {
+    const resolved = resolveProxyConfig(proxy);
+    if (!resolved) {
+        return {
+            connectionRetries: CONNECTION_RETRIES,
+        };
+    }
+    return {
+        connectionRetries: CONNECTION_RETRIES,
+        proxy: resolved,
+    };
+}
+/** Credential-free proxy summary safe to log. */
+function describeProxy(proxy) {
+    return proxy ? `socks${proxy.socksType}` : undefined;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });