@amykit/plugin-telegram 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+<!-- Generated by `npm run docs:generate` from the package itself. Do not edit by hand. -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @amykit/plugin-telegram
+
+A topic per piece of work in the operator's private chat with a Telegram bot, as the conversation port.
+
+A plugin for [amy](https://github.com/nicolasmelo1/amy). It provides the `conversation` port.
+
+Use it when you want to follow and answer amy from Telegram. It mounts the conversation port: each piece of work gets a topic in your private chat with a bot, and it can also hold amy's chat. It needs the bot token in TELEGRAM_BOT_TOKEN and your numeric Telegram user id.
+
+## What it extends
+
+|  |  |
+| :-- | :-- |
+| Ports | `conversation` |
+| Actions | _none_ |
+| Operations | _none_ |
+| Commands | _none_ |
+| Events | _none_ |
+| Environment | `TELEGRAM_BOT_TOKEN` |
+
+## Install
+
+```sh
+amy add @amykit/plugin-telegram
+```
+
+Then name it in `~/.amy/config.yaml`:
+
+```yaml
+workflows:
+  your-profile:
+    plugins:
+      - "@amykit/plugin-telegram"
+```
+
+## Configuration
+
+```yaml
+plugins:
+  "@amykit/plugin-telegram":
+    directory: "telegram"
+    operator: <string>
+    server: "https://api.telegram.org"
+    topics: true
+```
+
+| Setting | Type | Required | Default | What it is |
+| :-- | :-- | :-- | :-- | :-- |
+| `directory` | `string` | no | `telegram` | where this profile's topics are remembered, by work id, relative to the state directory; the replies read for every profile are kept once per bot |
+| `operator` | `string` | **yes** |  | your Telegram user id, a number such as 123456789: the private chat each work item's topic opens in, and the only person whose replies are answers |
+| `server` | `string` | no | `https://api.telegram.org` | the Bot API server, for a local one instead of Telegram's |
+| `topics` | `boolean` | no | `true` | whether each piece of work opens a topic of its own; off, works share the private chat and a reply reaches one by quoting amy's message for it or starting with its id |
+
+Every field is checked at boot against the schema this package declares. A key that is
+not one of the above is a refusal naming the plugin and the key, not a setting that
+silently never applied.
+
+## Environment
+
+This package reads the following, which `amy doctor` checks for you:
+
+| Variable |  |
+| :-- | :-- |
+| `TELEGRAM_BOT_TOKEN` | required at mount |
+
+## Where the reasoning is
+
+- [Writing a plugin](https://github.com/nicolasmelo1/amy/tree/main/docs/guides/write-a-plugin.md)
+- [Reference: plugins](https://github.com/nicolasmelo1/amy/tree/main/docs/reference/plugins.md)
+- [Ports and the registry](https://github.com/nicolasmelo1/amy/tree/main/docs/concepts/ports.md)
+
+## Licence
+
+MIT

package/dist/BotApi.d.ts

@@ -0,0 +1,74 @@
+/** One HTTP exchange, small enough to script in a test. */
+export interface HttpRequest {
+    url: string;
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    body?: string;
+    /** Refuse the answer once its body passes this many bytes, while it arrives. */
+    maxBytes?: number;
+    /** Abandon the exchange, the body's last byte included, after this long. */
+    deadlineMs?: number;
+}
+export interface HttpResponse {
+    status: number;
+    body: Uint8Array;
+}
+export type HttpTransport = (request: HttpRequest) => Promise<HttpResponse>;
+/** An answer larger than the request allowed, refused before it was held whole. */
+export declare class TooLarge extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
+export declare const fetchTransport: HttpTransport;
+/** Telegram's own server; a local Bot API server, or a stand-in, is another. */
+export declare const TELEGRAM_API = "https://api.telegram.org";
+/** How many times a `429` is waited out before the call fails. */
+export declare const DEFAULT_RATE_LIMIT_RETRIES = 5;
+/**
+ * How long one exchange may take, body included. Updates are asked for with
+ * no long poll, so anything this slow is a server that stopped answering, and
+ * holding the bot's lock for it would stall every profile.
+ */
+export declare const DEFAULT_DEADLINE_MS = 60000;
+/**
+ * What the Bot API answered when it refused, with its `error_code` kept
+ * apart, so a 409 is told from a 400 without reading the words.
+ */
+export declare class BotApiRefusal extends Error {
+    readonly method: string;
+    readonly code: number;
+    readonly description: string;
+    constructor(method: string, code: number, description: string);
+}
+export interface BotApiOptions {
+    server?: string;
+    transport?: HttpTransport;
+    sleep?: (ms: number) => Promise<void>;
+    maxRateLimitRetries?: number;
+    deadlineMs?: number;
+}
+/**
+ * The Bot API, called by method name with a JSON body.
+ *
+ * The token is part of every URL Telegram serves, so no URL is ever put in
+ * an error, a log or a file: what goes wrong is said by method name.
+ */
+export declare class BotApi {
+    private readonly token;
+    private readonly server;
+    private readonly transport;
+    private readonly sleep;
+    private readonly maxRetries;
+    private readonly deadlineMs;
+    constructor(token: string, options?: BotApiOptions);
+    /** The method's `result`, or a {@link BotApiRefusal} when `ok` is false. */
+    call<T>(method: string, args?: Record<string, unknown>): Promise<T>;
+    /** A file's bytes, by the `file_path` getFile answered, refused past `maxBytes` while they arrive. */
+    download(filePath: string, maxBytes?: number): Promise<Uint8Array>;
+    /**
+     * The transport's failure, said without the URL that carries the token. The
+     * original is not kept as the cause: its message may carry that URL.
+     */
+    private send;
+}
+//# sourceMappingURL=BotApi.d.ts.map

package/dist/BotApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BotApi.d.ts","sourceRoot":"","sources":["../src/BotApi.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAE5E,mFAAmF;AACnF,qBAAa,QAAS,SAAQ,KAAK;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAGnC;AAED,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAC;AAkCF,gFAAgF;AAChF,eAAO,MAAM,YAAY,6BAA6B,CAAC;AAEvD,kEAAkE;AAClE,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAEpC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM;gBAFnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM;CAI/B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAUD;;;;;GAKG;AACH,qBAAa,MAAM;IAQf,OAAO,CAAC,QAAQ,CAAC,KAAK;IAPxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGjB,KAAK,EAAE,MAAM,EAC9B,OAAO,GAAE,aAAkB;IAS7B,4EAA4E;IACtE,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAsB7E,sGAAsG;IAChG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAcxE;;;OAGG;IACH,OAAO,CAAC,IAAI;CAMb"}

package/dist/BotApi.js

@@ -0,0 +1,162 @@
+/** An answer larger than the request allowed, refused before it was held whole. */
+export class TooLarge extends Error {
+    limit;
+    constructor(limit) {
+        super(`the answer is larger than ${limit} bytes`);
+        this.limit = limit;
+    }
+}
+export const fetchTransport = async (request) => {
+    // One signal for the request and the body, so a server that trickles bytes forever is cut off too.
+    const signal = request.deadlineMs === undefined ? undefined : AbortSignal.timeout(request.deadlineMs);
+    const response = await fetch(request.url, { method: request.method, headers: request.headers, body: request.body, ...(signal ? { signal } : {}) });
+    return { status: response.status, body: await readBody(response, request.maxBytes) };
+};
+/**
+ * The body, counted as it arrives: a declared length over the limit is
+ * refused unread, and a missing or understated one is caught by the count.
+ */
+async function readBody(response, maxBytes) {
+    if (maxBytes === undefined || !response.body)
+        return new Uint8Array(await response.arrayBuffer());
+    if (Number(response.headers.get("content-length") ?? 0) > maxBytes) {
+        await response.body.cancel();
+        throw new TooLarge(maxBytes);
+    }
+    const chunks = [];
+    let total = 0;
+    const reader = response.body.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new TooLarge(maxBytes);
+        }
+        chunks.push(value);
+    }
+    const body = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+/** Telegram's own server; a local Bot API server, or a stand-in, is another. */
+export const TELEGRAM_API = "https://api.telegram.org";
+/** How many times a `429` is waited out before the call fails. */
+export const DEFAULT_RATE_LIMIT_RETRIES = 5;
+/**
+ * How long one exchange may take, body included. Updates are asked for with
+ * no long poll, so anything this slow is a server that stopped answering, and
+ * holding the bot's lock for it would stall every profile.
+ */
+export const DEFAULT_DEADLINE_MS = 60_000;
+/**
+ * What the Bot API answered when it refused, with its `error_code` kept
+ * apart, so a 409 is told from a 400 without reading the words.
+ */
+export class BotApiRefusal extends Error {
+    method;
+    code;
+    description;
+    constructor(method, code, description) {
+        super(`telegram ${method} refused: ${code} ${description}`);
+        this.method = method;
+        this.code = code;
+        this.description = description;
+    }
+}
+/**
+ * The Bot API, called by method name with a JSON body.
+ *
+ * The token is part of every URL Telegram serves, so no URL is ever put in
+ * an error, a log or a file: what goes wrong is said by method name.
+ */
+export class BotApi {
+    token;
+    server;
+    transport;
+    sleep;
+    maxRetries;
+    deadlineMs;
+    constructor(token, options = {}) {
+        this.token = token;
+        this.server = (options.server ?? TELEGRAM_API).replace(/\/+$/, "");
+        this.transport = options.transport ?? fetchTransport;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.maxRetries = options.maxRateLimitRetries ?? DEFAULT_RATE_LIMIT_RETRIES;
+        this.deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS;
+    }
+    /** The method's `result`, or a {@link BotApiRefusal} when `ok` is false. */
+    async call(method, args = {}) {
+        for (let attempt = 0;; attempt++) {
+            const response = await this.send(method, {
+                url: `${this.server}/bot${this.token}/${method}`,
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(args),
+                deadlineMs: this.deadlineMs,
+            });
+            const answer = parse(method, response);
+            if (answer.ok === true)
+                return answer.result;
+            const code = answer.error_code ?? response.status;
+            const retryAfter = answer.parameters?.retry_after;
+            if (code === 429 && attempt < this.maxRetries) {
+                await this.sleep(Math.max(0, retryAfter ?? 1) * 1000);
+                continue;
+            }
+            // A local server or a proxy may echo the request, and with it the URL.
+            throw new BotApiRefusal(method, code, withoutToken(answer.description ?? "no description", this.token));
+        }
+    }
+    /** A file's bytes, by the `file_path` getFile answered, refused past `maxBytes` while they arrive. */
+    async download(filePath, maxBytes) {
+        const response = await this.send("file download", {
+            url: `${this.server}/file/bot${this.token}/${filePath}`,
+            method: "GET",
+            headers: {},
+            deadlineMs: this.deadlineMs,
+            ...(maxBytes === undefined ? {} : { maxBytes }),
+        });
+        if (response.status !== 200)
+            throw new Error(`telegram file download answered HTTP ${response.status}`);
+        // Checked again here for a transport that does not honour the limit.
+        if (maxBytes !== undefined && response.body.byteLength > maxBytes)
+            throw new TooLarge(maxBytes);
+        return response.body;
+    }
+    /**
+     * The transport's failure, said without the URL that carries the token. The
+     * original is not kept as the cause: its message may carry that URL.
+     */
+    send(what, request) {
+        return this.transport(request).catch((error) => {
+            if (error instanceof TooLarge)
+                throw error;
+            throw new Error(`telegram ${what} could not be reached: ${withoutToken(error, this.token)}`);
+        });
+    }
+}
+function parse(method, response) {
+    try {
+        return JSON.parse(new TextDecoder().decode(response.body));
+    }
+    catch {
+        throw new Error(`telegram ${method} answered HTTP ${response.status} with a body that is not JSON`);
+    }
+}
+/** The message with the token taken out, as written and as a URL would encode it, in either case. */
+function withoutToken(error, token) {
+    const text = error instanceof Error ? error.message : String(error);
+    if (!token)
+        return text;
+    const encoded = encodeURIComponent(token);
+    const forms = [...new Set([token, encoded, encoded.replace(/%[0-9A-F]{2}/g, (escape) => escape.toLowerCase())])];
+    return forms.reduce((said, form) => said.split(form).join("<token>"), text);
+}
+//# sourceMappingURL=BotApi.js.map

package/dist/BotApi.js.map

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

package/dist/TelegramConversation.d.ts

@@ -0,0 +1,207 @@
+import { Ask, ChatMessage, Conversation, Reply, ThreadRef } from "@amykit/core";
+import { BotApi } from "./BotApi.js";
+export interface TelegramConversationOptions {
+    /** The operator's user id, which is also their private chat with the bot. */
+    operator: string;
+    /**
+     * What this profile owns: its topics by work id, the replies filed under
+     * them and the files they carried. Removing the profile removes all of it.
+     */
+    directory: string;
+    /**
+     * What one bot shares across profiles: which profile owns each topic, the
+     * update offset and the lock. The directory itself when not given.
+     */
+    shared?: string;
+    /** The largest file downloaded; a larger one is named in the reply instead. */
+    maxFileBytes?: number;
+    /** How long to wait for another process reading the bot. */
+    lockWaitMs?: number;
+    /** How long a hold on the bot lasts without being renewed. */
+    leaseMs?: number;
+    /** An inspection may read existing state but must not initialize it. */
+    readOnly?: boolean;
+    /**
+     * Whether each piece of work opens a topic of its own. Off, works share the
+     * private chat, and a reply reaches one only when it quotes amy's message
+     * for it or starts with its id (S15).
+     */
+    topics?: boolean;
+}
+/** What `amy doctor` prints for this plugin, one line per question. */
+export interface TelegramCheck {
+    label: string;
+    ok: boolean;
+    detail?: string;
+}
+/** The most a bot may download, by the Bot API's own limit. */
+export declare const DEFAULT_MAX_FILE_BYTES: number;
+/** A posted structured ask and its durable selection/acceptance state. */
+export interface FiledAsk {
+    ask: Ask;
+    messageId: number;
+    at: string;
+    selected: number[];
+    accepted?: {
+        at: string;
+        chosen: string[];
+    };
+    /** Callback ids already applied; retries must not toggle a persisted selection. */
+    callbacks?: string[];
+    acknowledged?: boolean;
+}
+/**
+ * One topic per piece of work, in the operator's private chat with the bot.
+ *
+ * Telegram hands a bot its updates once, to whoever asks first, so the
+ * process reading them files each message, durably, under the profile that
+ * owns its topic before the offset that confirms it moves.
+ *
+ * Nothing here depends on that reader being alone. Every reply is a file of
+ * its own, created and never rewritten; every topic and owner is a file
+ * created once; the offset only moves forward. A second reader, or one that
+ * was paused past its hold, can only add what is already there, never lose
+ * it. The hold on the bot saves work (a 409 from Telegram, a topic opened
+ * twice) and nothing else.
+ */
+export declare class TelegramConversation implements Conversation {
+    private readonly api;
+    private readonly options;
+    readonly asks: true;
+    readonly edit: true;
+    readonly threads?: true;
+    /** The bot: its directory is named for it, so two bots never share a conversation. */
+    readonly source: string;
+    private readonly opening;
+    /** Who this profile's directory is: a directory removed and made again is somebody else. */
+    private readonly identity;
+    /** The operator's id as Telegram writes it, whatever spelling the config used. */
+    private readonly operator;
+    constructor(api: BotApi, options: TelegramConversationOptions);
+    open(workId: string, title: string): Promise<ThreadRef>;
+    /**
+     * A work in a chat without topics: nothing to ask Telegram for, only its
+     * thread to name and record, so a reply addressed to it is filed under it.
+     */
+    private openInTheChat;
+    /**
+     * Records who owns a work's thread, the thread by work id, and the work by
+     * its id for the whole bot, so a message addressed to it from outside every
+     * thread finds it. Owner first: a reply that arrives before the work knows
+     * its thread is still filed here. The directory is kept relative to the
+     * bot's, so a state root moved or mounted elsewhere still finds it.
+     */
+    private record;
+    post(thread: ThreadRef, message: {
+        text: string;
+        files?: string[];
+        ask?: Ask;
+    }): Promise<string>;
+    private postAsk;
+    private sendParts;
+    replies(thread: ThreadRef, since: string): Promise<Reply[]>;
+    /**
+     * Whether this bot can hold the conversation, asked of Telegram itself:
+     * the token, the bot's topic mode, a private chat the operator started,
+     * and nobody else reading its updates.
+     */
+    checks(): Promise<TelegramCheck[]>;
+    /**
+     * The messages in the private chat that reached no work, oldest first,
+     * until they are settled. Telegram is read for them first, so the chat is
+     * read all the time and not only when a work is looked at (S20).
+     */
+    chat(): Promise<ChatMessage[]>;
+    settle(id: string): Promise<void>;
+    /** Says something in the private chat, outside every topic, in as many messages as it takes. */
+    say(place: string, text: string): Promise<string>;
+    /** Replaces what a message amy said reads, as much of it as one message holds. */
+    revise(place: string, id: string, text: string): Promise<void>;
+    private chatId;
+    private topics;
+    /**
+     * Where each work's thread is remembered, one place per mode: a topic is no
+     * thread in a chat without topics, nor the other way round, so turning
+     * topics on or off opens each work afresh rather than reusing an id the
+     * new mode cannot post to.
+     */
+    private threadsDirectory;
+    /** Where a work's message goes: its topic, or the chat itself when works share it. */
+    private inThread;
+    private threadOf;
+    private workOfThread;
+    private shared;
+    private inbox;
+    /**
+     * Reads every update Telegram holds and files each of the operator's
+     * messages under the profile owning its topic. A topic no profile owns any
+     * more, its profile removed or made again, is skipped. The offset moves
+     * only once what it confirms is durably on disk.
+     */
+    private fileUpdates;
+    /** Handles a button only after resolving its real topic owner from the callback message. */
+    private fileCallback;
+    private callbackContext;
+    private applyCallback;
+    private sendChoices;
+    private choose;
+    private acknowledgeAccepted;
+    private redrawKeyboard;
+    private closeKeyboard;
+    private askFile;
+    private askByKey;
+    private writeAsk;
+    protected askedUnder(topic: string): FiledAsk[];
+    /**
+     * Files one message in its owner's inbox for that owner's identity, as a
+     * file of its own. The inbox is named for the identity, so a write racing a
+     * profile's removal lands where no later profile at that path reads.
+     */
+    private file;
+    /**
+     * Where a topic's replies are filed for its owner, if that owner's directory
+     * still carries the identity that opened the topic; made if needed.
+     */
+    private inboxOf;
+    /** The id of the last message amy posted in a topic by an instant, or 0 when none is known. */
+    private postedBy;
+    /** Files what arrived in a topic before its owner was recorded, now that it is. */
+    private adopt;
+    /** Whether a topic is being opened in this chat now, by any process: an opening older than a day was abandoned. */
+    private openingIn;
+    /** Replies kept for a topic whose opening was abandoned a day ago, and the openings themselves, go. */
+    private pruneAbandoned;
+    /**
+     * The offset to confirm with, unless it has outlived Telegram's update
+     * ids: then the earliest update Telegram still holds is asked for instead,
+     * and the ones already filed are filed once.
+     */
+    private offset;
+    /** Moves the offset forward, never back, so a late reader cannot unconfirm what another confirmed. */
+    private confirm;
+    /** The files as local paths, and a line naming each one too large to fetch. */
+    private downloadAll;
+    /**
+     * Fetches one file to its place, or answers false when it is too large: by
+     * what getFile says, by Telegram refusing it as too big when the message did
+     * not say its size, or by its bytes as they arrive. A local Bot API server
+     * answers with a path on its own disk, which is read where it lies.
+     */
+    private download;
+    private topicOfWork;
+    /**
+     * Files a message written outside every topic: under the work it is
+     * addressed to — a quote of amy's message for it, or its id at the start —
+     * and in the chat otherwise (S42). The rule is the core's; this only says
+     * what amy filed where (S16).
+     */
+    private fileOutside;
+    /**
+     * Runs `work` holding the bot, so one process reads its updates or opens a
+     * topic at a time: a hold not renewed within its lease is taken over. Being
+     * passed over costs a 409 or a second topic, never a reply, since nothing
+     * filed is ever rewritten.
+     */
+    private held;
+}
+//# sourceMappingURL=TelegramConversation.d.ts.map

package/dist/TelegramConversation.d.ts.map

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