@rubytech/create-realagent-code 0.1.581 → 0.1.583

package/payload/platform/lib/telegram-managed-bot/src/index.ts

@@ -0,0 +1,529 @@
+/**
+ * Task 2618 — Telegram's managed-bot surface, and the webhook registration that
+ * a newly provisioned bot needs.
+ *
+ * This is a shared lib rather than plugin code because BOTH sides need it. The
+ * `managed_bot` update lands on the UI webhook route, which must fetch the new
+ * bot's token, persist it and register its webhook; the `telegram-bot-provision`
+ * MCP tool needs the same four Bot API calls for its own actions. UI production
+ * code does not import plugin source, so the alternative was a second copy of
+ * `TELEGRAM_ALLOWED_UPDATES` on the UI side — and two lists that must agree, of
+ * a set where naming any class replaces Telegram's default, is exactly the drift
+ * Task 2612 spent a task fixing.
+ *
+ * `TELEGRAM_ALLOWED_UPDATES` and `setTelegramWebhook` MOVED here from
+ * `plugins/telegram/mcp/src/lib/telegram.ts`, which now re-exports both so every
+ * existing plugin import keeps its path.
+ *
+ * Every name below is quoted from core.telegram.org/bots/api, read 2026-08-09.
+ */
+
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const TELEGRAM_API = "https://api.telegram.org";
+
+/**
+ * Task 2612 — the update classes this install asks Telegram for.
+ *
+ * The trap: naming ANY class replaces Telegram's default set, so a class that
+ * works today and is missing from this list stops arriving with no error
+ * anywhere. Telegram's default is every class except `chat_member`,
+ * `message_reaction` and `message_reaction_count`.
+ *
+ * Task 2618 — `managed_bot` is fifteenth. It IS in Telegram's default set, so it
+ * arrives on an install that names nothing; but this install names its list, so
+ * omitting it here is the difference between a tapped provisioning button that
+ * works and one that silently does nothing.
+ *
+ * The order is the one Task 2612 states, and the registration test asserts the
+ * whole array rather than membership — the failure guarded against is a name
+ * silently dropped, which a membership check cannot see.
+ */
+export const TELEGRAM_ALLOWED_UPDATES: readonly string[] = [
+  "message",
+  "edited_message",
+  "callback_query",
+  "poll_answer",
+  "poll",
+  "message_reaction",
+  "pre_checkout_query",
+  "shipping_query",
+  "subscription",
+  "my_chat_member",
+  "business_connection",
+  "business_message",
+  "edited_business_message",
+  "deleted_business_messages",
+  "managed_bot",
+  // Task 2616 — the group set. `chat_member` (another member's membership
+  // changed, as against `my_chat_member` for the bot's own) and
+  // `message_reaction_count` (the anonymous tally that pairs with
+  // `message_reaction`) are OUTSIDE Telegram's default, so neither arrives until
+  // a bot re-registers. `chat_join_request` and the two boost classes are inside
+  // it and are named so that making the list explicit is not itself a regression.
+  "chat_member",
+  "chat_join_request",
+  "message_reaction_count",
+  "chat_boost",
+  "removed_chat_boost",
+  // Task 2617 — the channel pair. Both are INSIDE Telegram's default set, so they
+  // would arrive on an install that names nothing; this install names its own
+  // list, so they are named here for the reason `chat_join_request` and the two
+  // boost classes are — making the list explicit must not itself be a regression.
+  //
+  // Without them a channel post never reaches the route at all, and the failure is
+  // silent: Telegram reports no error for a class it was not asked for.
+  "channel_post",
+  "edited_channel_post",
+];
+
+/**
+ * Register a webhook URL with Telegram and generate a cryptographic secret.
+ *
+ * The secret is generated via crypto.randomBytes (64 hex chars), passed as
+ * `secret_token`, and written to disk ONLY after the API confirms success. That
+ * order prevents orphaned secret files when the call fails, and avoids
+ * overwriting a working secret during a failed re-registration.
+ *
+ * Telegram sends the secret in the X-Telegram-Bot-Api-Secret-Token header on
+ * every delivery; the webhook route validates it before processing.
+ *
+ * If secretFilePath is omitted, no secret is generated.
+ */
+export async function setTelegramWebhook(
+  botToken: string,
+  webhookUrl: string,
+  secretFilePath?: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: boolean; secret?: string; error?: string }> {
+  const secret = secretFilePath ? randomBytes(32).toString("hex") : undefined;
+
+  // Task 2612 — `allowed_updates` travels on every registration.
+  const body: Record<string, unknown> = {
+    url: webhookUrl,
+    allowed_updates: [...TELEGRAM_ALLOWED_UPDATES],
+  };
+  if (secret) {
+    body.secret_token = secret;
+  }
+
+  const res = await fetchImpl(`${TELEGRAM_API}/bot${botToken}/setWebhook`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  const data = (await res.json()) as { ok: boolean; description?: string };
+
+  if (!data.ok) {
+    return { ok: false, error: data.description ?? "Failed to set webhook" };
+  }
+
+  if (secret && secretFilePath) {
+    mkdirSync(dirname(secretFilePath), { recursive: true });
+    writeFileSync(secretFilePath, secret, { mode: 0o600 });
+    console.error(
+      `[telegram] webhook secret written to ${secretFilePath} (${secret.length} chars)`,
+    );
+  }
+
+  return { ok: true, secret };
+}
+
+/** One entry in an account's `telegram.bots[]`.
+ *
+ *  Task 2618 adds the third role: a bot this install provisioned that nothing has
+ *  bound to an agent yet. It carries no `agent` and no `adminUsers` because
+ *  neither has an answer between the tap that created it and Task 2619's binding. */
+export type TelegramBotEntryWrite =
+  | { id: string; token: string; role: "admin"; adminUsers?: number[]; managed?: boolean }
+  | {
+      id: string;
+      token: string;
+      role: "public";
+      agent: string;
+      dmPolicy?: "open" | "allowlist" | "disabled";
+      allowFrom?: number[];
+      managed?: boolean;
+    }
+  | { id: string; token: string; role: "unbound"; managed?: boolean }
+  // Task 2619 — a bot bound to one of the account's own specialist cards.
+  // `specialist` is a card FILE BASENAME, the only value `--agent` resolves.
+  // There is no `dmPolicy`: a specialist session carries the card's own tool
+  // surface rather than the zero-tool public ringfence, so an explicit list of
+  // ids is the only gate that holds, and the register tool requires a non-empty
+  // `allowFrom` even though the shape permits its absence (an absent list admits
+  // nobody, which is the safe reading for a config already on disk).
+  | {
+      id: string;
+      token: string;
+      role: "specialist";
+      specialist: string;
+      allowFrom?: number[];
+      managed?: boolean;
+    };
+
+/** Merge one bot entry into an account's `telegram.bots[]`, replacing any entry
+ *  with the same id and leaving every other entry and every other key
+ *  byte-identical.
+ *
+ *  THE single writer of that array. Two callers reach it: the plugin's
+ *  `persistTelegramBot`, which adds the brand-containment assertion it needs
+ *  because it resolves this directory from an untrusted `accountId`; and the UI
+ *  webhook route, which already holds a directory that came from the platform's
+ *  own account enumeration. A bot registry with two writers is one that
+ *  eventually disagrees with itself about who is registered.
+ *
+ *  Task 2368's invariant is carried unchanged: registering, re-pointing or
+ *  rotating one bot cannot disturb another. */
+export function writeTelegramBotEntry(
+  accountDir: string,
+  entry: TelegramBotEntryWrite,
+): { ok: boolean; error?: string } {
+  const configPath = join(accountDir, "account.json");
+  if (!existsSync(configPath)) {
+    return { ok: false, error: `account.json not found at ${configPath}` };
+  }
+  let config: Record<string, unknown>;
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch (e) {
+    // Refuse rather than overwrite. A file that will not parse holds state this
+    // merge cannot preserve, and replacing it would drop every other bot.
+    return { ok: false, error: `account.json parse failed: ${(e as Error).message}` };
+  }
+  const telegram = (config.telegram as Record<string, unknown>) ?? {};
+  const bots = Array.isArray(telegram.bots) ? (telegram.bots as TelegramBotEntryWrite[]) : [];
+  const at = bots.findIndex((b) => b && typeof b === "object" && b.id === entry.id);
+  if (at >= 0) bots[at] = entry;
+  else bots.push(entry);
+  telegram.bots = bots;
+  config.telegram = telegram;
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+  return { ok: true };
+}
+
+export interface WebhookInfo {
+  url: string;
+  pendingUpdateCount: number;
+  /** Unix seconds of the most recent delivery error Telegram saw, 0 when it
+   *  reports none. Telegram KEEPS this across a re-registration, which is why
+   *  the verdict compares it against the moment we registered. */
+  lastErrorDate: number;
+  lastErrorMessage?: string;
+  /** Task 2612 — the classes Telegram says it will deliver. Telegram omits the
+   *  field entirely when the registration uses its default set, which reads here
+   *  as `[]` — and `[]` is exactly the pre-2612 state, so an empty list against a
+   *  non-empty request is a real mismatch and not a missing field. */
+  allowedUpdates: string[];
+}
+
+/** What Telegram says it is currently delivering for this bot.
+ *
+ *  Task 2618 — MOVED here from the plugin, which re-exports it. Three callers
+ *  now: the plugin's registration probe, the tool's rotate action reading the URL
+ *  to restore, and the UI's hourly managed-bot census. */
+export async function getTelegramWebhookInfo(
+  botToken: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<WebhookInfo> {
+  const res = await fetchImpl(`${TELEGRAM_API}/bot${botToken}/getWebhookInfo`);
+  const data = (await res.json()) as {
+    result: {
+      url: string;
+      pending_update_count: number;
+      last_error_date?: number;
+      last_error_message?: string;
+      allowed_updates?: string[];
+    };
+  };
+  return {
+    url: data.result.url,
+    pendingUpdateCount: data.result.pending_update_count,
+    lastErrorDate: data.result.last_error_date ?? 0,
+    allowedUpdates: data.result.allowed_updates ?? [],
+    ...(data.result.last_error_message !== undefined
+      ? { lastErrorMessage: data.result.last_error_message }
+      : {}),
+  };
+}
+
+/** One stored entry, whole, or null when the account holds no bot with that id.
+ *
+ *  The point is "whole". `listRegisteredBots` returns `{ id, role, agent }` for
+ *  the callers that only need to name a bot, and a rotation that spread THAT into
+ *  the writer would silently drop `adminUsers`, `dmPolicy`, `allowFrom` and
+ *  `managed` — replacing a token would quietly un-admit every admin on the bot.
+ *  A rotation changes one field and must carry the rest through untouched. */
+export function readTelegramBotEntry(
+  accountDir: string,
+  botId: string,
+): TelegramBotEntryWrite | null {
+  const configPath = join(accountDir, "account.json");
+  if (!existsSync(configPath)) return null;
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf-8")) as {
+      telegram?: { bots?: TelegramBotEntryWrite[] };
+    };
+    const bots = config.telegram?.bots;
+    if (!Array.isArray(bots)) return null;
+    return bots.find((b) => b && typeof b === "object" && b.id === botId) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Bot API `User`, as far as the managed-bot payloads use it. */
+export interface TelegramManagedUser {
+  id?: number;
+  is_bot?: boolean;
+  first_name?: string;
+  username?: string;
+  /** "True, if other bots can be created to be controlled by the bot. Returned
+   *  only in getMe." The managing bot needs this before a request button can be
+   *  offered; it is switched on in the @BotFather Mini App, not by any API call. */
+  can_manage_bots?: boolean;
+}
+
+/** Bot API `ManagedBotUpdated`, the `managed_bot` update's payload.
+ *
+ *  Note what is NOT here: no event discriminator and no `request_id`. Telegram
+ *  documents the update as "A new bot was created to be managed by the bot, or
+ *  token or owner of a managed bot was changed" and sends the same two fields
+ *  for all three. Which of them happened is derivable only from local state. */
+export interface ManagedBotUpdated {
+  /** The user who created the bot. */
+  user?: TelegramManagedUser;
+  /** The bot itself. Its `id` is the value every managed-bot method keys on. */
+  bot?: TelegramManagedUser;
+}
+
+/** Bot API `ManagedBotCreated`, the `managed_bot_created` service message field. */
+export interface ManagedBotCreated {
+  bot?: TelegramManagedUser;
+}
+
+/** Bot API `KeyboardButtonRequestManagedBot`. `request_id` is a signed 32-bit
+ *  integer, unique within the message. */
+export interface KeyboardButtonRequestManagedBot {
+  request_id: number;
+  suggested_name?: string;
+  suggested_username?: string;
+}
+
+/** The largest `request_id` Telegram accepts: it is a signed 32-bit integer. */
+export const MANAGED_BOT_REQUEST_ID_MAX = 2_147_483_647;
+
+/** Bot API `ReplyKeyboardMarkup`, narrowed to the fields this install sends.
+ *
+ *  "Not supported in channels and for messages sent on behalf of a business
+ *  account", and `request_managed_bot` is further "Available in private chats
+ *  only" — both are the caller's constraint, not this type's. */
+export interface TelegramReplyKeyboard {
+  keyboard: Array<Array<{ text: string; request_managed_bot?: KeyboardButtonRequestManagedBot }>>;
+  one_time_keyboard?: boolean;
+  resize_keyboard?: boolean;
+  is_persistent?: boolean;
+  input_field_placeholder?: string;
+}
+
+/** The one reply keyboard this install builds: a single button asking the user to
+ *  create a bot for this bot to manage.
+ *
+ *  Shared because both doors send it — the MCP tool's `offer` action and, if a
+ *  later caller needs it, the UI's own outbound. One builder, because a button
+ *  whose `request_id` is built two ways is a button whose answer cannot be
+ *  correlated.
+ *
+ *  One button in one row: `request_id` must be "unique within the message" and
+ *  nothing here has a reason to send two at once. `one_time_keyboard` so it
+ *  disappears once tapped rather than sitting in the operator's chat. */
+export function buildManagedBotRequestKeyboard(input: {
+  text: string;
+  requestId: number;
+  suggestedName?: string;
+  suggestedUsername?: string;
+}): TelegramReplyKeyboard {
+  if (
+    !Number.isInteger(input.requestId) ||
+    input.requestId < 1 ||
+    input.requestId > MANAGED_BOT_REQUEST_ID_MAX
+  ) {
+    // Refused here, not by Telegram: Telegram rejects the send with a description
+    // that never names the field, so the operator would see a failed offer and no
+    // reason for it.
+    throw new Error(
+      `request_id ${input.requestId} is not a positive signed 32-bit integer, which is what Telegram requires`,
+    );
+  }
+  return {
+    keyboard: [
+      [
+        {
+          text: input.text,
+          request_managed_bot: {
+            request_id: input.requestId,
+            ...(input.suggestedName !== undefined ? { suggested_name: input.suggestedName } : {}),
+            ...(input.suggestedUsername !== undefined
+              ? { suggested_username: input.suggestedUsername }
+              : {}),
+          },
+        },
+      ],
+    ],
+    one_time_keyboard: true,
+    resize_keyboard: true,
+  };
+}
+
+/** Telegram caps `added_user_ids` at ten. Refused locally so the cap is named,
+ *  rather than surfacing as an opaque API error with no number in it. */
+export const MAX_ADDED_USER_IDS = 10;
+
+/** The four Bot API methods this module owns, keyed by the action that uses each.
+ *  Read by the plugin's `OWNED_METHODS` census and by its `api-guard` refusals,
+ *  so neither can disagree with this module about what it covers. */
+export const MANAGED_BOT_METHODS = Object.freeze({
+  token: "getManagedBotToken",
+  rotate: "replaceManagedBotToken",
+  accessRead: "getManagedBotAccessSettings",
+  accessWrite: "setManagedBotAccessSettings",
+} as const);
+
+async function call(
+  botToken: string,
+  method: string,
+  body: Record<string, unknown>,
+  fetchImpl: typeof fetch,
+): Promise<{ ok: true; result: unknown } | { ok: false; error: string }> {
+  try {
+    const res = await fetchImpl(`${TELEGRAM_API}/bot${botToken}/${method}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    const data = (await res.json()) as { ok: boolean; result?: unknown; description?: string };
+    if (!data.ok) return { ok: false, error: data.description ?? `${method} failed` };
+    return { ok: true, result: data.result };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/** "Use this method to get the token of a managed bot. Returns the token as
+ *  String on success." `userId` is the MANAGED bot's own user id, which is also
+ *  the numeric prefix of the token this returns.
+ *
+ *  The token is a credential. Every caller persists it and nothing logs it. */
+export async function getManagedBotToken(
+  managingBotToken: string,
+  userId: number,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: true; token: string } | { ok: false; error: string }> {
+  const r = await call(managingBotToken, MANAGED_BOT_METHODS.token, { user_id: userId }, fetchImpl);
+  if (!r.ok) return r;
+  return typeof r.result === "string"
+    ? { ok: true, token: r.result }
+    : { ok: false, error: "no-token-in-result" };
+}
+
+/** "Use this method to revoke the current token of a managed bot and generate a
+ *  new one. Returns the new token as String on success."
+ *
+ *  The bot's user id is unchanged by a rotation, so the new token has the same
+ *  numeric prefix and the bot keys on nothing new. */
+export async function replaceManagedBotToken(
+  managingBotToken: string,
+  userId: number,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: true; token: string } | { ok: false; error: string }> {
+  const r = await call(managingBotToken, MANAGED_BOT_METHODS.rotate, { user_id: userId }, fetchImpl);
+  if (!r.ok) return r;
+  return typeof r.result === "string"
+    ? { ok: true, token: r.result }
+    : { ok: false, error: "no-token-in-result" };
+}
+
+export interface ManagedBotAccess {
+  isAccessRestricted: boolean;
+  /** The ids of users admitted BESIDES the owner, who "can always access it".
+   *  An absent `added_users` reads as nobody, which is what Telegram means by
+   *  omitting it, and not as unknown. */
+  addedUserIds: number[];
+}
+
+/** "Returns a BotAccessSettings object on success." */
+export async function getManagedBotAccessSettings(
+  managingBotToken: string,
+  userId: number,
+  fetchImpl: typeof fetch = fetch,
+): Promise<({ ok: true } & ManagedBotAccess) | { ok: false; error: string }> {
+  const r = await call(
+    managingBotToken,
+    MANAGED_BOT_METHODS.accessRead,
+    { user_id: userId },
+    fetchImpl,
+  );
+  if (!r.ok) return r;
+  const s = r.result as { is_access_restricted?: boolean; added_users?: TelegramManagedUser[] };
+  return {
+    ok: true,
+    isAccessRestricted: s?.is_access_restricted === true,
+    addedUserIds: (s?.added_users ?? [])
+      .map((u) => u?.id)
+      .filter((id): id is number => typeof id === "number"),
+  };
+}
+
+/** "Use this method to change the access settings of a managed bot. Returns True
+ *  on success." `addedUserIds` is "Ignored if is_access_restricted is False",
+ *  which is Telegram's behaviour and is not re-implemented here. */
+export async function setManagedBotAccessSettings(
+  managingBotToken: string,
+  userId: number,
+  isAccessRestricted: boolean,
+  addedUserIds: number[] | undefined,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: boolean; error?: string }> {
+  if (addedUserIds && addedUserIds.length > MAX_ADDED_USER_IDS) {
+    return { ok: false, error: "too-many-added-user-ids" };
+  }
+  const r = await call(
+    managingBotToken,
+    MANAGED_BOT_METHODS.accessWrite,
+    {
+      user_id: userId,
+      is_access_restricted: isAccessRestricted,
+      ...(addedUserIds ? { added_user_ids: addedUserIds } : {}),
+    },
+    fetchImpl,
+  );
+  return r.ok ? { ok: true } : { ok: false, error: r.error };
+}
+
+/** The managing bot's own `getMe`, for the one field that gates provisioning.
+ *  A bot without `can_manage_bots` cannot offer the request button at all, and
+ *  the switch lives in the @BotFather Mini App rather than behind any API call. */
+export async function botCanManageBots(
+  botToken: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: true; canManageBots: boolean; username: string } | { ok: false; error: string }> {
+  try {
+    const res = await fetchImpl(`${TELEGRAM_API}/bot${botToken}/getMe`);
+    const data = (await res.json()) as {
+      ok: boolean;
+      result?: TelegramManagedUser;
+      description?: string;
+    };
+    if (!data.ok) return { ok: false, error: data.description ?? "getMe failed" };
+    return {
+      ok: true,
+      canManageBots: data.result?.can_manage_bots === true,
+      username: data.result?.username ?? "unknown",
+    };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/payload/platform/lib/telegram-managed-bot/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}

package/payload/platform/lib/telegram-managed-bot/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: false,
+    include: ["src/__tests__/**/*.test.ts"],
+  },
+});

package/payload/platform/lib/telegram-reach/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Is this a channel key that can safely become a path segment?
+ *
+ * Both halves of an admin key are Telegram numeric ids (a bot id is positive; a
+ * chat or sender id is an integer and is negative for groups), so requiring
+ * exactly that is both the truthful shape check and a complete traversal guard:
+ * no `.`, `/` or `\` can survive it.
+ *
+ * Task 2615 — the business shape `<botId>:biz:<senderId>` joins the guard rather
+ * than bypassing it. Both alternatives are anchored and admit only digits, an
+ * optional leading minus and the literal `biz`, so neither can carry a `.`, `/`
+ * or `\` either.
+ */
+export declare function isStorableChannelKey(channelKey: string): boolean;
+/** Task 2615 — is this the three-part business shape?
+ *
+ *  Its own predicate rather than a `.includes(':biz:')` at each caller: a
+ *  business conversation is reached through the business-connection send route
+ *  and its 24-hour window, not by addressing a chat id, so anything that answers
+ *  "can we message this person now" has to be able to tell the two apart. */
+export declare function isBusinessChannelKey(channelKey: string): boolean;
+/** The filename stem for a channel key.
+ *
+ *  Throws on a key that is neither two numeric ids nor the business shape.
+ *  Refusing loudly is correct here: every caller reaches this with a key it has
+ *  already validated, so an unstorable key means a caller skipped its guard, and
+ *  silently sanitising it would build a path nobody asked for. */
+export declare function channelKeyToFileStem(channelKey: string): string;
+/** The inverse of `channelKeyToFileStem`.
+ *
+ *  Task 2615 — a stem whose second segment is exactly `biz` is a three-part
+ *  business key. Otherwise only the FIRST `_` is a separator, because both halves
+ *  of an admin key are numeric Telegram ids and nothing later in that stem is
+ *  one. */
+export declare function fileStemToChannelKey(stem: string): string;
+/** One registered bot, as much of it as reachability needs. `adminUsers` is
+ *  present on an admin entry only; absent reads as none. */
+export interface ReachBotInput {
+    id: string;
+    role: string;
+    adminUsers?: number[];
+}
+export interface ReachChat {
+    /** Null for an adminUsers entry that has never messaged: there is no chat. */
+    chatId: string | null;
+    senderId: string;
+    /** From the newest inbound row. Null when that row carried no name, and null
+     *  for a sender who has never messaged. */
+    displayName: string | null;
+    /** ISO 8601 of the newest inbound row; null means never messaged. */
+    lastInbound: string | null;
+    /** This sender is an adminUsers entry on this bot. Allowlisted is a DIFFERENT
+     *  fact from having started the chat, which is why both are carried. */
+    admin: boolean;
+    /** True exactly when `lastInbound` is non-null. */
+    reachable: boolean;
+}
+export interface ReachBot {
+    botId: string;
+    role: string;
+    adminUsers: number[];
+    /** Reachable chats newest first, then never-messaged admins in listed order. */
+    chats: ReachChat[];
+}
+export interface ReachResult {
+    bots: ReachBot[];
+    /** Message rows this call actually read, across EVERY conversation file in the
+     *  directory — including files belonging to a bot the caller did not name.
+     *  That is deliberate: `chats=0` with `storeRows>0` is then the signature of a
+     *  wrong bot list or a wrong account scope, which is the failure this number
+     *  exists to expose. */
+    storeRows: number;
+}
+/** Reachability for one account: every registered bot, the private chats that
+ *  have messaged it, and the allowlisted people who have not. */
+export declare function collectTelegramReach(input: {
+    storeDir: string;
+    bots: ReachBotInput[];
+}): ReachResult;
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/telegram-reach/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;6EAK6E;AAC7E,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;kEAKkE;AAClE,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAED;;;;;WAKW;AACX,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED;4DAC4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB;+CAC2C;IAC3C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qEAAqE;IACrE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;4EACwE;IACxE,KAAK,EAAE,OAAO,CAAC;IACf,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gFAAgF;IAChF,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB;;;;4BAIwB;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AA+FD;iEACiE;AACjE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,aAAa,EAAE,CAAC;CACvB,GAAG,WAAW,CAsCd"}