@uniquedivine/tg-sai 0.0.5 → 0.1.0

package/mtcuteAdapter.ts

@@ -1,4 +1,9 @@
-import { TelegramClient } from "@mtcute/bun"
+import { networkMiddlewares, TelegramClient } from "@mtcute/bun"
+import type {
+  FloodWaiterOptions,
+  RpcCallMiddleware,
+  RpcCallOptions,
+} from "@mtcute/bun"
 import { createTelegramCryptoProvider } from "./telegramRuntime"
 import {
   addChatMembers,
@@ -11,6 +16,17 @@ import { convertFromTelethonSession } from "@mtcute/convert"
 import type { ChatAuditInput, ChatMemberData, UserData } from "./adminAudit"
 import type { SaiChatRecord } from "./ops"
 import { isSaiChatTitle } from "./ops"
+import type { ProfileStoreEnv } from "./profiles"
+import { stateDbPath } from "./state/db"
+import { createFloodGuard } from "./state/guard"
+import type {
+  FloodGuard,
+  HoldAccountProvider,
+  HoldStoreSource,
+} from "./state/guard"
+import { HoldStore, ReopeningHoldStore } from "./state/holds"
+import { createTelemetryMiddlewares } from "./telemetry/middleware"
+import type { ClientTelemetry } from "./telemetry/middleware"
 
 /**
  * Connection settings used to create a mtcute Telegram client.
@@ -24,6 +40,17 @@ export interface MtcuteClientConfig {
   session: string
   /** Optional local mtcute storage path. */
   storage?: string
+  /**
+   * Flood-wait settings for mtcute's flood waiter, the only flood retry
+   * layer. Ignored when `telemetry.floodWaiter` is set.
+   */
+  floodWaiter?: FloodWaiterOptions
+  /**
+   * Verified Telegram user ID the session acts as (checked against
+   * `getMe` by the caller); keys the client's saved flood holds. Unset: the
+   * guard keys holds by the account the session's own `getMe` reports.
+   */
+  accountId?: number
 }
 
 /**
@@ -90,16 +117,218 @@ function isPeerNotFound(error: unknown): boolean {
   )
 }
 
-/** Shared constructor used by offline readiness and authenticated operations. */
+/** mtcute's `floodWaiter` default `maxWait`. */
+export const MTCUTE_DEFAULT_FLOOD_MAX_WAIT_MS = 10_000
+
+const holdStores = new Map<string, ReopeningHoldStore>()
+
+/**
+ * The process's `HoldStore` for `state.db` under `env`'s config dir, shared
+ * by every client. Never throws: a store that cannot open reports
+ * `unavailable`, so the guard fails closed, and a later call tries the
+ * open again at most every `HOLD_STORE_REOPEN_MS`.
+ */
+export function processHoldStore(
+  env: ProfileStoreEnv = process.env,
+  nowMs: number = Date.now(),
+): HoldStore {
+  let path: string
+  try {
+    path = stateDbPath(env)
+  } catch (error) {
+    return HoldStore.unavailable(
+      error instanceof Error ? error.message : String(error),
+    )
+  }
+  let handle = holdStores.get(path)
+  if (!handle) {
+    handle = new ReopeningHoldStore(path)
+    holdStores.set(path, handle)
+  }
+  return handle.get(nowMs)
+}
+
+/** Closes every store `processHoldStore` opened; the next use reopens. */
+export function closeProcessHoldStores(): void {
+  for (const handle of holdStores.values()) handle.close()
+  holdStores.clear()
+}
+
+/**
+ * Telegram user a client's session acts as, learned from the session's own
+ * `getMe` (a `users.getUsers` call for `inputUserSelf`). mtcute's stored
+ * self is not used: the shared storage file can carry another session's.
+ */
+export interface SessionAccount {
+  id: number | null
+}
+
+/** Options for `clientMiddlewares` beyond the flood waiter and telemetry. */
+export interface ClientMiddlewareOptions {
+  /**
+   * Verified account for the flood guard (e.g. provisioning's
+   * `expectedUserId`, checked against `getMe`). Unset: the guard keys by
+   * `sessionAccount`.
+   */
+  accountId?: number
+  /** Filled from the session's `getMe` results; default a fresh cell. */
+  sessionAccount?: SessionAccount
+  /** Runs `getMe` so `sessionAccount` is known before invite/create. */
+  resolveSessionAccount?: () => Promise<unknown>
+  /** Hold store; default `processHoldStore()`, opened on first use. */
+  holdStore?: HoldStoreSource
+}
+
+interface SelfRequest {
+  _?: unknown
+  id?: unknown
+}
+
+/** Whether `request` is `getMe`'s `users.getUsers([inputUserSelf])`. */
+export function isGetMeRequest(request: unknown): boolean {
+  const value = request as SelfRequest | null
+  return (
+    value?._ === "users.getUsers" &&
+    Array.isArray(value.id) &&
+    value.id.length === 1 &&
+    (value.id[0] as { _?: unknown } | null)?._ === "inputUserSelf"
+  )
+}
+
+/** Innermost: saves the user ID from each `getMe` result in `account`. */
+function captureSessionAccount(account: SessionAccount): RpcCallMiddleware {
+  return async (ctx, next) => {
+    const result = await next(ctx)
+    try {
+      if (isGetMeRequest(ctx.request) && Array.isArray(result)) {
+        const user = result[0] as { _?: unknown; id?: unknown } | undefined
+        if (
+          user?._ === "user" &&
+          typeof user.id === "number" &&
+          Number.isSafeInteger(user.id) &&
+          user.id > 0
+        ) {
+          account.id = user.id
+        }
+      }
+    } catch {
+      // Capturing must never change the call's result.
+    }
+    return result
+  }
+}
+
+/** `outer` runs first and hands `inner` the rest of the chain. */
+function chainMiddleware(
+  outer: RpcCallMiddleware,
+  inner: RpcCallMiddleware,
+): RpcCallMiddleware {
+  return (ctx, next) => outer(ctx, (c) => inner(c, next))
+}
+
+/**
+ * Network middlewares for a client. Passing middlewares replaces mtcute's
+ * defaults, so both branches include `networkMiddlewares.basic()` (flood
+ * waiter and 5xx retry) with the same options, wrapped by the flood guard:
+ *
+ * - without telemetry: `[check, ...basic({ floodWaiter }), record]`
+ * - with telemetry: `[outer, check, ...basic(), inner, record]`
+ *
+ * The guard saves waits longer than the flood waiter's `maxWait` (and all
+ * invite/create waits and `PEER_FLOOD`) and refuses held calls in every
+ * process. It keys holds by `accountId` when given, else by the account
+ * the session's own `getMe` reports. Until that is known, invite/create
+ * calls first run `resolveSessionAccount` and are refused with
+ * `HoldAccountUnknownError` if it fails; other calls pass unguarded.
+ */
+export function clientMiddlewares(
+  floodWaiter: FloodWaiterOptions | undefined,
+  telemetry: ClientTelemetry | undefined,
+  options: ClientMiddlewareOptions = {},
+): RpcCallMiddleware[] {
+  const waiter = telemetry?.floodWaiter ?? floodWaiter
+  const session = options.sessionAccount ?? { id: null }
+  const verified = options.accountId
+  const accountProvider: HoldAccountProvider = () => verified ?? session.id
+  const guardOptions = {
+    sleepThresholdMs: waiter?.maxWait ?? MTCUTE_DEFAULT_FLOOD_MAX_WAIT_MS,
+    ...(verified === undefined
+      ? {
+          requireAccount: true,
+          ...(options.resolveSessionAccount
+            ? { resolveAccount: options.resolveSessionAccount }
+            : {}),
+        }
+      : {}),
+  }
+  const store: HoldStoreSource = options.holdStore ?? (() => processHoldStore())
+  const capture = captureSessionAccount(session)
+  const withCapture = (guard: FloodGuard): FloodGuard => ({
+    check: guard.check,
+    record: chainMiddleware(guard.record, capture),
+  })
+  if (telemetry) {
+    return createTelemetryMiddlewares(
+      telemetry.sink,
+      telemetry.context,
+      waiter,
+      (requestIdOf) =>
+        withCapture(
+          createFloodGuard(store, accountProvider, {
+            ...guardOptions,
+            requestIdOf,
+          }),
+        ),
+    )
+  }
+  const guard = withCapture(
+    createFloodGuard(store, accountProvider, guardOptions),
+  )
+  return [
+    guard.check,
+    ...networkMiddlewares.basic(waiter ? { floodWaiter: waiter } : undefined),
+    guard.record,
+  ]
+}
+
+const sessionAccounts = new WeakMap<TelegramClient, SessionAccount>()
+
+/**
+ * The account a client's session acts as, once its `getMe` has run; `null`
+ * before that, and for clients not made by `createMtcuteRuntimeClient`.
+ */
+export function sessionAccountId(client: TelegramClient): number | null {
+  return sessionAccounts.get(client)?.id ?? null
+}
+
+/**
+ * Shared constructor used by offline readiness and authenticated operations.
+ * Every client gets the flood guard (see `clientMiddlewares`). With
+ * `telemetry`, every RPC call, wire attempt, and flood wait is recorded.
+ */
 export function createMtcuteRuntimeClient(
   config: Omit<MtcuteClientConfig, "session">,
+  telemetry?: ClientTelemetry,
 ): TelegramClient {
-  return new TelegramClient({
+  const sessionAccount: SessionAccount = { id: null }
+  let client: TelegramClient | null = null
+  const middlewares = clientMiddlewares(config.floodWaiter, telemetry, {
+    accountId: config.accountId,
+    sessionAccount,
+    resolveSessionAccount: async () => {
+      if (!client) throw new Error("client not constructed")
+      return client.getMe()
+    },
+  })
+  client = new TelegramClient({
     crypto: createTelegramCryptoProvider(),
     apiId: config.apiId,
     apiHash: config.apiHash,
     storage: config.storage ?? "sai-telegram-admin-check.session",
+    network: { middlewares },
   })
+  sessionAccounts.set(client, sessionAccount)
+  return client
 }
 
 /**
@@ -107,8 +336,9 @@ export function createMtcuteRuntimeClient(
  */
 export async function createMtcuteClient(
   config: MtcuteClientConfig,
+  telemetry?: ClientTelemetry,
 ): Promise<TelegramClient> {
-  const client = createMtcuteRuntimeClient(config)
+  const client = createMtcuteRuntimeClient(config, telemetry)
 
   await client.importSession(convertFromTelethonSession(config.session), true)
   return client
@@ -234,23 +464,41 @@ export async function findSaiChats(
 }
 
 /**
- * Adds a user or bot peer to a Telegram chat.
+ * Call options for writes that may hit an account-wide limit: mtcute never
+ * sleeps through a flood wait and resends, so a wait reaches the caller
+ * and the flood guard saves it as a hold.
+ */
+export const NO_FLOOD_SLEEP: Readonly<RpcCallOptions> = {
+  floodSleepThreshold: 0,
+}
+
+/**
+ * Adds a user or bot peer to a Telegram chat. Never sleeps through a flood
+ * wait (`NO_FLOOD_SLEEP`).
  */
 export async function addTargetToChat(
   client: TelegramClient,
   params: TargetWriteParams,
 ): Promise<void> {
-  await addChatMembers(client, params.chatId, params.targetPeer, {})
+  await addChatMembers(
+    client.withParams(NO_FLOOD_SLEEP),
+    params.chatId,
+    params.targetPeer,
+    {},
+  )
 }
 
 /**
  * Promotes a user or bot peer using the supplied admin-rights profile.
+ * Promoting a non-member also adds them, so by default the call never
+ * sleeps through a flood wait; pass `{}` for mtcute's usual flood sleep.
  */
 export async function promoteTargetAdmin(
   client: TelegramClient,
   params: PromoteTargetParams,
+  callParams: RpcCallOptions = NO_FLOOD_SLEEP,
 ): Promise<void> {
-  await editAdminRights(client, {
+  await editAdminRights(client.withParams(callParams), {
     chatId: params.chatId,
     userId: params.targetPeer,
     rights: params.rights,

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@uniquedivine/tg-sai",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "type": "module",
   "private": false,
   "description": "Sai Telegram admin audit and bootstrap CLI",
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.2.0"
   },
   "bin": {
     "tg-sai": "main.ts"
@@ -21,6 +21,14 @@
     "!*.test.ts",
     "!adminCheck.ts",
     "!testdata.ts",
+    "!testPreload.ts",
+    "telemetry/*.ts",
+    "!telemetry/*.test.ts",
+    "!telemetry/testEvents.ts",
+    "telemetry/migrations/*.sql",
+    "state/*.ts",
+    "!state/*.test.ts",
+    "state/migrations/*.sql",
     "*.py",
     "!*_test.py",
     "pyproject.toml",

package/profiles.ts

@@ -771,13 +771,24 @@ export async function credentialsFromProfile(
   return credentialsFromProfileRecord(profile)
 }
 
-export async function resolveTelegramCredentials(
+/** Where `resolveTelegramCredentialSource` found the credentials. */
+export type TelegramCredentialSource = "env" | "profile" | "known_file"
+
+/**
+ * Credentials for `profileName` and where they came from: `TELEGRAM_*`
+ * environment variables, the selected profile, or a known credential file.
+ * Only `profile` credentials match the profile's saved `userId`.
+ */
+export async function resolveTelegramCredentialSource(
   profileName: string | undefined,
   env: ProfileStoreEnv = process.env,
-): Promise<TelegramCredentials> {
+): Promise<{
+  credentials: TelegramCredentials
+  source: TelegramCredentialSource
+}> {
   const envCredentials = credentialsFromEnv(env)
   if (envCredentials) {
-    return envCredentials
+    return { credentials: envCredentials, source: "env" }
   }
 
   const config = await readConfig(env)
@@ -786,7 +797,7 @@ export async function resolveTelegramCredentials(
     ? credentialsFromProfileRecord(selectedProfile)
     : null
   if (profileCredentials) {
-    return profileCredentials
+    return { credentials: profileCredentials, source: "profile" }
   }
   if (selectedProfile) {
     throw new Error(
@@ -796,7 +807,7 @@ export async function resolveTelegramCredentials(
 
   const knownFileCredentials = await credentialsFromKnownFiles(env)
   if (knownFileCredentials) {
-    return knownFileCredentials
+    return { credentials: knownFileCredentials, source: "known_file" }
   }
 
   throw new Error(
@@ -804,6 +815,13 @@ export async function resolveTelegramCredentials(
   )
 }
 
+export async function resolveTelegramCredentials(
+  profileName: string | undefined,
+  env: ProfileStoreEnv = process.env,
+): Promise<TelegramCredentials> {
+  return (await resolveTelegramCredentialSource(profileName, env)).credentials
+}
+
 export function profileInputFromUser(
   name: string | undefined,
   credentials: TelegramCredentials,