@nodetool-ai/telegram 0.8.1

package/dist/identity-client.d.ts

@@ -0,0 +1,132 @@
+/**
+ * IdentityClient — the bridge's half of the identity layer (design §5).
+ *
+ * The bridge holds exactly one credential: the service token that identifies
+ * it to the NodeTool server. It never sees a user password, an OAuth code, or
+ * a long-lived user token. To act as a linked user it exchanges the Telegram
+ * user id for a short-lived delegated token, and caches that token until
+ * shortly before it expires.
+ *
+ * Every route this module calls is `packages/websocket/src/routes/integrations.ts`.
+ * All I/O goes through the injected `fetch`, so the whole flow is testable
+ * without a server.
+ */
+export declare const TOKEN_EXPIRY_SLACK_MS: number;
+/** The identity layer's provider column for this bridge. */
+export declare const TELEGRAM_PROVIDER = "telegram";
+export interface IdentityClientOptions {
+    /** NodeTool server base URL, no trailing slash. */
+    readonly apiUrl: string;
+    /** `NODETOOL_INTEGRATION_TOKEN` — the bridge's service token. */
+    readonly integrationToken: string;
+    /** Injected so tests need no network. */
+    readonly fetch: typeof fetch;
+    /** Identity provider name. Defaults to `telegram`. */
+    readonly provider?: string;
+    /** Clock, in ms. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Cache slack before expiry. Defaults to {@link TOKEN_EXPIRY_SLACK_MS}. */
+    readonly expirySlackMs?: number;
+}
+/** A delegated token good for acting as the linked NodeTool user. */
+export interface LinkedIdentity {
+    readonly unlinked: false;
+    /** Bearer token for `/ws`, `/trpc` and asset URLs. */
+    readonly token: string;
+    /** The NodeTool user the token authenticates as. */
+    readonly userId: string;
+    /** Absolute expiry, in ms since the epoch. */
+    readonly expiresAtMs: number;
+}
+/** Why no token could be minted. Both cases are answered in the chat, not thrown. */
+export type UnlinkedReason = 
+/** No `external_identities` row: the user must link first (HTTP 404). */
+"not-linked"
+/** Server runs in local single-user trust mode (HTTP 409, design §9). */
+ | "local-mode";
+export interface UnlinkedIdentity {
+    readonly unlinked: true;
+    readonly reason: UnlinkedReason;
+    /** The server's own explanation, for relaying to the user. */
+    readonly message: string;
+}
+export type IdentityResolution = LinkedIdentity | UnlinkedIdentity;
+/** A link code the user turns into an `external_identities` row in the browser. */
+export interface LinkStart {
+    readonly code: string;
+    /** Confirmation page URL to send to the user. */
+    readonly url: string;
+    /** ISO timestamp the code stops working at, when the server reported one. */
+    readonly expiresAt: string | null;
+}
+/**
+ * Outcome of completing a `/start <code>` deep link.
+ *
+ * `unsupported` is the committed server's answer today: `/link/complete`
+ * requires a `user_id` the bridge does not know, because the code it mints is
+ * bound to an `external_id`, not to a user. See the module note below.
+ */
+export type DeepLinkResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: "expired" | "mismatch" | "unsupported" | "server-error";
+    readonly message: string;
+};
+/** A transport or server failure the caller must surface rather than swallow. */
+export declare class IdentityError extends Error {
+    /** HTTP status, or null when the request never got a response. */
+    readonly status: number | null;
+    constructor(message: string, status: number | null, options?: {
+        cause?: unknown;
+    });
+}
+export declare class IdentityClient {
+    private readonly apiUrl;
+    private readonly integrationToken;
+    private readonly fetchImpl;
+    private readonly provider;
+    private readonly now;
+    private readonly expirySlackMs;
+    private readonly cache;
+    constructor(options: IdentityClientOptions);
+    /**
+     * A delegated token for this Telegram user, from cache when one is still
+     * comfortably valid.
+     *
+     * @throws {IdentityError} on transport failure or an unexpected status —
+     * "not linked" and "local mode" are results, not errors.
+     */
+    resolve(telegramUserId: string): Promise<IdentityResolution>;
+    /**
+     * Forget the cached token for a user. Called when the server rejects it
+     * mid-session, so the next turn mints a fresh one instead of retrying a
+     * token the server has already refused.
+     */
+    invalidate(telegramUserId: string): void;
+    /** Mint a one-time link code and confirmation URL for the `/link` flow. */
+    linkStart(telegramUserId: string): Promise<LinkStart>;
+    /**
+     * Complete a link the *web* side started, from a `/start <code>` deep link.
+     *
+     * ROUTE GAP: against the *committed*
+     * `packages/websocket/src/routes/integrations.ts` this direction does not
+     * exist. `/link/start` binds a code to `(provider, external_id)` and
+     * `/link/complete` requires a `user_id` in the body, so only the
+     * bot-initiated direction closes — the bridge knows the Telegram id, never
+     * the NodeTool user id. The direction needs the route to accept
+     * `{external_id, code}` and read the user off a code the web side minted,
+     * which is what the M1 T1.4 change to that route adds.
+     *
+     * So the call is made in exactly the shape that direction takes, and a 400
+     * naming the missing `user_id` is reported as `unsupported` — which
+     * `/start <code>` handling turns into the ordinary `/link` flow rather than
+     * leaving the user holding a dead code.
+     */
+    completeDeepLink(telegramUserId: string, code: string): Promise<DeepLinkResult>;
+    /** Delete the mapping for this Telegram user. Returns whether a row went. */
+    unlink(telegramUserId: string): Promise<boolean>;
+    private post;
+    private request;
+}
+//# sourceMappingURL=identity-client.d.ts.map

package/dist/identity-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-client.d.ts","sourceRoot":"","sources":["../src/identity-client.ts"],"names":[],"mappings":"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"}

package/dist/identity-client.js

@@ -0,0 +1,204 @@
+/**
+ * IdentityClient — the bridge's half of the identity layer (design §5).
+ *
+ * The bridge holds exactly one credential: the service token that identifies
+ * it to the NodeTool server. It never sees a user password, an OAuth code, or
+ * a long-lived user token. To act as a linked user it exchanges the Telegram
+ * user id for a short-lived delegated token, and caches that token until
+ * shortly before it expires.
+ *
+ * Every route this module calls is `packages/websocket/src/routes/integrations.ts`.
+ * All I/O goes through the injected `fetch`, so the whole flow is testable
+ * without a server.
+ */
+/** How long before a token's stated expiry it stops being served from cache. */
+import { trimTrailingSlashes } from "./strings.js";
+export const TOKEN_EXPIRY_SLACK_MS = 5 * 60 * 1000;
+/** The identity layer's provider column for this bridge. */
+export const TELEGRAM_PROVIDER = "telegram";
+/** A transport or server failure the caller must surface rather than swallow. */
+export class IdentityError extends Error {
+    /** HTTP status, or null when the request never got a response. */
+    status;
+    constructor(message, status, options) {
+        super(message, options);
+        this.name = "IdentityError";
+        this.status = status;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(body, field) {
+    if (!isRecord(body)) {
+        return null;
+    }
+    const value = body[field];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/** The server's `{error}` string, or a generic line naming the status. */
+function errorMessage(body, status) {
+    return stringField(body, "error") ?? `NodeTool server answered ${status}`;
+}
+export class IdentityClient {
+    apiUrl;
+    integrationToken;
+    fetchImpl;
+    provider;
+    now;
+    expirySlackMs;
+    cache = new Map();
+    constructor(options) {
+        this.apiUrl = trimTrailingSlashes(options.apiUrl);
+        this.integrationToken = options.integrationToken;
+        this.fetchImpl = options.fetch;
+        this.provider = options.provider ?? TELEGRAM_PROVIDER;
+        this.now = options.now ?? Date.now;
+        this.expirySlackMs = options.expirySlackMs ?? TOKEN_EXPIRY_SLACK_MS;
+    }
+    /**
+     * A delegated token for this Telegram user, from cache when one is still
+     * comfortably valid.
+     *
+     * @throws {IdentityError} on transport failure or an unexpected status —
+     * "not linked" and "local mode" are results, not errors.
+     */
+    async resolve(telegramUserId) {
+        const cached = this.cache.get(telegramUserId);
+        if (cached && cached.expiresAtMs - this.expirySlackMs > this.now()) {
+            return {
+                unlinked: false,
+                token: cached.token,
+                userId: cached.userId,
+                expiresAtMs: cached.expiresAtMs
+            };
+        }
+        this.cache.delete(telegramUserId);
+        const { status, body } = await this.post("token", { external_id: telegramUserId });
+        if (status === 404) {
+            return { unlinked: true, reason: "not-linked", message: errorMessage(body, status) };
+        }
+        if (status === 409) {
+            return { unlinked: true, reason: "local-mode", message: errorMessage(body, status) };
+        }
+        if (status !== 200) {
+            throw new IdentityError(errorMessage(body, status), status);
+        }
+        const token = stringField(body, "token");
+        const userId = stringField(body, "user_id");
+        if (token === null || userId === null) {
+            throw new IdentityError("Token response is missing `token` or `user_id`", status);
+        }
+        const expiresAt = stringField(body, "expires_at");
+        const parsed = expiresAt === null ? Number.NaN : Date.parse(expiresAt);
+        // A token whose expiry the server did not state is treated as expiring
+        // immediately after the slack window, so it is re-minted rather than used
+        // forever on a guess.
+        const expiresAtMs = Number.isFinite(parsed) ? parsed : this.now() + this.expirySlackMs;
+        this.cache.set(telegramUserId, { token, userId, expiresAtMs });
+        return { unlinked: false, token, userId, expiresAtMs };
+    }
+    /**
+     * Forget the cached token for a user. Called when the server rejects it
+     * mid-session, so the next turn mints a fresh one instead of retrying a
+     * token the server has already refused.
+     */
+    invalidate(telegramUserId) {
+        this.cache.delete(telegramUserId);
+    }
+    /** Mint a one-time link code and confirmation URL for the `/link` flow. */
+    async linkStart(telegramUserId) {
+        const { status, body } = await this.post("link/start", {
+            external_id: telegramUserId
+        });
+        if (status !== 200) {
+            throw new IdentityError(errorMessage(body, status), status);
+        }
+        const code = stringField(body, "code");
+        const url = stringField(body, "url");
+        if (code === null || url === null) {
+            throw new IdentityError("Link response is missing `code` or `url`", status);
+        }
+        return { code, url, expiresAt: stringField(body, "expires_at") };
+    }
+    /**
+     * Complete a link the *web* side started, from a `/start <code>` deep link.
+     *
+     * ROUTE GAP: against the *committed*
+     * `packages/websocket/src/routes/integrations.ts` this direction does not
+     * exist. `/link/start` binds a code to `(provider, external_id)` and
+     * `/link/complete` requires a `user_id` in the body, so only the
+     * bot-initiated direction closes — the bridge knows the Telegram id, never
+     * the NodeTool user id. The direction needs the route to accept
+     * `{external_id, code}` and read the user off a code the web side minted,
+     * which is what the M1 T1.4 change to that route adds.
+     *
+     * So the call is made in exactly the shape that direction takes, and a 400
+     * naming the missing `user_id` is reported as `unsupported` — which
+     * `/start <code>` handling turns into the ordinary `/link` flow rather than
+     * leaving the user holding a dead code.
+     */
+    async completeDeepLink(telegramUserId, code) {
+        const { status, body } = await this.post("link/complete", {
+            external_id: telegramUserId,
+            code
+        });
+        if (status === 200) {
+            return { ok: true };
+        }
+        if (status === 410) {
+            return { ok: false, reason: "expired", message: errorMessage(body, status) };
+        }
+        if (status === 400) {
+            const message = errorMessage(body, status);
+            const reason = message.includes("different account") ? "mismatch" : "unsupported";
+            return { ok: false, reason, message };
+        }
+        return { ok: false, reason: "server-error", message: errorMessage(body, status) };
+    }
+    /** Delete the mapping for this Telegram user. Returns whether a row went. */
+    async unlink(telegramUserId) {
+        const { status, body } = await this.request("DELETE", "link", {
+            external_id: telegramUserId
+        });
+        if (status !== 200) {
+            throw new IdentityError(errorMessage(body, status), status);
+        }
+        this.cache.delete(telegramUserId);
+        return isRecord(body) && body.unlinked === true;
+    }
+    post(path, payload) {
+        return this.request("POST", path, payload);
+    }
+    async request(method, path, payload) {
+        const url = `${this.apiUrl}/api/integrations/${this.provider}/${path}`;
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method,
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${this.integrationToken}`
+                },
+                body: JSON.stringify(payload)
+            });
+        }
+        catch (err) {
+            throw new IdentityError(`Cannot reach the NodeTool server at ${this.apiUrl}: ${err.message}`, null, { cause: err });
+        }
+        const text = await response.text();
+        let body = null;
+        if (text.length > 0) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                // A non-JSON body (a proxy's HTML error page) carries no field to
+                // read; the status alone is what the caller reports.
+                body = null;
+            }
+        }
+        return { status: response.status, body };
+    }
+}
+//# sourceMappingURL=identity-client.js.map

package/dist/identity-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-client.js","sourceRoot":"","sources":["../src/identity-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @nodetool-ai/telegram — the Telegram bridge.
+ *
+ * A bridge process, not a second agent runtime: it translates Telegram updates
+ * into `chat_message` commands on the NodeTool server's `/ws` chat protocol and
+ * the resulting frames back into Telegram messages. The agent loop, tools,
+ * permissions, thread persistence and cost tracking stay on the server.
+ *
+ * See `docs/telegram-bot-design.md`.
+ */
+export { loadConfig, TelegramConfigError, DEFAULT_API_URL, DEFAULT_CONFIG_FILE, DEFAULT_EDIT_THROTTLE_MS, DEFAULT_MAX_QUEUED_TURNS } from "./config.js";
+export type { TelegramBotConfig, TelegramBotFileConfig, LoadConfigOptions } from "./config.js";
+export { chunkText, splitOnce, DEFAULT_CHUNK_MAX, TELEGRAM_MESSAGE_LIMIT } from "./chunk.js";
+export { markdownToTelegramHtml, escapeHtml } from "./markdown-html.js";
+export type { TelegramHtmlResult } from "./markdown-html.js";
+export { createRendererState, foldFrame, foldFrames, collectAssetRefs } from "./frame-renderer.js";
+export type { RenderOp, RenderTarget, ParseMode, TypingOp, SendOp, EditOp, FinalizeOp, AttachOp, StopNoteOp, AssetAttachment, RenderFrame, FrameEnvelope, FinalMessageFrame, GenerationStoppedFrame, RendererState, RendererOptions, FoldResult } from "./frame-renderer.js";
+export { IdentityClient, IdentityError, TELEGRAM_PROVIDER, TOKEN_EXPIRY_SLACK_MS } from "./identity-client.js";
+export type { IdentityClientOptions, IdentityResolution, LinkedIdentity, UnlinkedIdentity, UnlinkedReason, LinkStart, DeepLinkResult } from "./identity-client.js";
+export { TurnRouter, deriveThreadId, highestThreadIndex, userHash8 } from "./turn-router.js";
+export type { BridgeChatSocket, BridgeClient, BridgeSendOptions, DeliveryContext, ExecuteOps, IdentityResolver, MakeBridgeClient, SubmitInput, SubmitResult, TurnRouterConfig, TurnRouterOptions } from "./turn-router.js";
+export { BotApi, BotApiError, TELEGRAM_API_BASE, TELEGRAM_UPLOAD_LIMIT_BYTES } from "./bot-api.js";
+export type { BotApiOptions, BotCommandSpec, TelegramCallbackQuery, TelegramMessage, TelegramUpdate } from "./bot-api.js";
+export { TelegramAdapter, POLL_TIMEOUT_SECONDS, STOP_CALLBACK_DATA } from "./telegram-adapter.js";
+export type { AdapterConfig, PollStopReason, ResolveAsset, ResolvedAsset, TelegramAdapterOptions } from "./telegram-adapter.js";
+export { BOT_COMMANDS, MESSAGES, PUBLIC_COMMANDS, handleCommand, isAllowedUser, parseCommand } from "./commands.js";
+export type { CommandDeps, CommandIdentity, CommandInput, CommandOutcome, CommandRouter } from "./commands.js";
+export { registerCommands } from "./register-commands.js";
+export type { RegisterCommandsOptions } from "./register-commands.js";
+export { assetIdOf, createAssetResolver, createBridgeClientFactory, wrapChatSocket } from "./nodetool-client.js";
+import type { TelegramBotConfig } from "./config.js";
+import { type PollStopReason } from "./telegram-adapter.js";
+/** A running bridge. Returned by {@link startTelegramBot}. */
+export interface TelegramBotHandle {
+    /** Stop polling and close every open socket. */
+    readonly stop: () => Promise<void>;
+    /** Resolves when the poll loop ends, with why it ended. */
+    readonly finished: Promise<PollStopReason>;
+}
+export interface StartTelegramBotOptions {
+    /** Injected for tests; defaults to the global `fetch`. */
+    readonly fetch?: typeof fetch;
+    /** Bot API base URL, for tests. */
+    readonly botApiBaseUrl?: string;
+}
+/**
+ * Start the bridge against a running NodeTool server.
+ *
+ * Long polling only: webhook mode is M3 (design §3), and config already
+ * validates the URL/secret pair, so a webhook-configured process is refused
+ * here rather than silently polling.
+ */
+export declare function startTelegramBot(config: TelegramBotConfig, options?: StartTelegramBotOptions): TelegramBotHandle;
+/** Stop a running bridge. */
+export declare function stopTelegramBot(handle: TelegramBotHandle): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,90 @@
+/**
+ * @nodetool-ai/telegram — the Telegram bridge.
+ *
+ * A bridge process, not a second agent runtime: it translates Telegram updates
+ * into `chat_message` commands on the NodeTool server's `/ws` chat protocol and
+ * the resulting frames back into Telegram messages. The agent loop, tools,
+ * permissions, thread persistence and cost tracking stay on the server.
+ *
+ * See `docs/telegram-bot-design.md`.
+ */
+export { loadConfig, TelegramConfigError, DEFAULT_API_URL, DEFAULT_CONFIG_FILE, DEFAULT_EDIT_THROTTLE_MS, DEFAULT_MAX_QUEUED_TURNS } from "./config.js";
+export { chunkText, splitOnce, DEFAULT_CHUNK_MAX, TELEGRAM_MESSAGE_LIMIT } from "./chunk.js";
+export { markdownToTelegramHtml, escapeHtml } from "./markdown-html.js";
+export { createRendererState, foldFrame, foldFrames, collectAssetRefs } from "./frame-renderer.js";
+export { IdentityClient, IdentityError, TELEGRAM_PROVIDER, TOKEN_EXPIRY_SLACK_MS } from "./identity-client.js";
+export { TurnRouter, deriveThreadId, highestThreadIndex, userHash8 } from "./turn-router.js";
+export { BotApi, BotApiError, TELEGRAM_API_BASE, TELEGRAM_UPLOAD_LIMIT_BYTES } from "./bot-api.js";
+export { TelegramAdapter, POLL_TIMEOUT_SECONDS, STOP_CALLBACK_DATA } from "./telegram-adapter.js";
+export { BOT_COMMANDS, MESSAGES, PUBLIC_COMMANDS, handleCommand, isAllowedUser, parseCommand } from "./commands.js";
+export { registerCommands } from "./register-commands.js";
+export { assetIdOf, createAssetResolver, createBridgeClientFactory, wrapChatSocket } from "./nodetool-client.js";
+import { BotApi } from "./bot-api.js";
+import { IdentityClient } from "./identity-client.js";
+import { TelegramAdapter } from "./telegram-adapter.js";
+import { TurnRouter } from "./turn-router.js";
+import { createAssetResolver, createBridgeClientFactory } from "./nodetool-client.js";
+/**
+ * Start the bridge against a running NodeTool server.
+ *
+ * Long polling only: webhook mode is M3 (design §3), and config already
+ * validates the URL/secret pair, so a webhook-configured process is refused
+ * here rather than silently polling.
+ */
+export function startTelegramBot(config, options = {}) {
+    if (config.webhookUrl !== null) {
+        throw new Error("TELEGRAM_WEBHOOK_URL is set, but webhook mode arrives in M3. Unset it " +
+            "to run the bridge in long-polling mode.");
+    }
+    const fetchImpl = options.fetch ?? fetch;
+    const apiInit = {
+        botToken: config.botToken,
+        fetch: fetchImpl
+    };
+    if (options.botApiBaseUrl !== undefined) {
+        apiInit.baseUrl = options.botApiBaseUrl;
+    }
+    const api = new BotApi(apiInit);
+    const identity = new IdentityClient({
+        apiUrl: config.apiUrl,
+        integrationToken: config.integrationToken,
+        fetch: fetchImpl
+    });
+    // The adapter executes the router's ops, and the router routes the adapter's
+    // messages: the two are wired through a mutable slot so neither needs the
+    // other at construction.
+    let adapter = null;
+    const router = new TurnRouter({
+        identity,
+        makeClient: createBridgeClientFactory({ apiUrl: config.apiUrl, fetch: fetchImpl }),
+        config: {
+            editThrottleMs: config.editThrottleMs,
+            maxQueuedTurns: config.maxQueuedTurns,
+            permissionMode: "auto"
+        },
+        executeOps: (context, ops) => adapter?.executeOps(context, ops)
+    });
+    adapter = new TelegramAdapter({
+        api,
+        identity,
+        router,
+        config: { allowUsers: config.allowUsers, apiUrl: config.apiUrl },
+        fetch: fetchImpl,
+        resolveAsset: createAssetResolver({ apiUrl: config.apiUrl, fetch: fetchImpl })
+    });
+    const started = adapter;
+    const finished = started.poll();
+    return {
+        finished,
+        stop: async () => {
+            started.stop();
+            router.close();
+            await started.flush();
+        }
+    };
+}
+/** Stop a running bridge. */
+export function stopTelegramBot(handle) {
+    return handle.stop();
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/markdown-html.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Agent markdown → Telegram HTML parse mode.
+ *
+ * MarkdownV2 makes every `.`, `-` and `(` in prose an escaping obligation, so
+ * one missed character fails the whole message. Telegram's HTML mode needs
+ * three characters escaped and supports the five tags this converter emits:
+ * `<b>`, `<i>`, `<code>`, `<pre>` and `<a href>`. Anything the converter
+ * cannot express — an unbalanced fence, markup it does not recognize as
+ * balanced — falls back to plain text, because a turn must never fail on
+ * formatting.
+ *
+ * Hand-rolled on purpose: the supported subset is small enough that a parser
+ * dependency would cost more than it covers.
+ */
+/** Converted HTML, or the plain-text fallback when conversion is not safe. */
+export type TelegramHtmlResult = {
+    readonly ok: true;
+    readonly html: string;
+} | {
+    readonly ok: false;
+    readonly text: string;
+};
+/** Escape the three characters Telegram's HTML mode reserves. */
+export declare function escapeHtml(text: string): string;
+/**
+ * Convert agent markdown to Telegram HTML.
+ *
+ * @returns `{ok: true, html}` when the safe subset covered the input, or
+ *   `{ok: false, text}` with the original text for a plain-text send.
+ */
+export declare function markdownToTelegramHtml(markdown: string): TelegramHtmlResult;
+//# sourceMappingURL=markdown-html.d.ts.map

package/dist/markdown-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-html.d.ts","sourceRoot":"","sources":["../src/markdown-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AA6BlD,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAiND;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAoB3E"}