@uniquedivine/tg-sai 0.0.4 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,491 @@
1
+ import { basename } from "node:path"
2
+
3
+ import type { ProfileStoreEnv } from "../profiles"
4
+ import {
5
+ LOG_EVENT_PREFIX,
6
+ LOG_LEVELS,
7
+ openTelemetrySink,
8
+ RUN_END_EVENT,
9
+ RUN_START_EVENT,
10
+ uuidv7,
11
+ } from "./db"
12
+ import type {
13
+ LogLevel,
14
+ TelemetryEvent,
15
+ TelemetryOutcome,
16
+ TelemetrySink,
17
+ TelemetrySubsystem,
18
+ } from "./db"
19
+ import { safeErrorText } from "./middleware"
20
+ import type { ClientTelemetry, TelemetryContext } from "./middleware"
21
+ import { summarizeTl } from "./summarize"
22
+
23
+ export const FLOOD_MAX_WAIT_ENV = "TG_SAI_FLOOD_MAX_WAIT_MS"
24
+ /** mtcute's own default; CLI commands sleep through waits up to this. */
25
+ export const CLI_FLOOD_MAX_WAIT_MS = 10_000
26
+ /** The worker is unattended, so it rides out somewhat longer waits. */
27
+ export const WORKER_FLOOD_MAX_WAIT_MS = 30_000
28
+ /**
29
+ * `ops sai-bootstrap` walks a reviewed batch; sleeping up to five minutes
30
+ * beats stopping the batch. Longer waits stop it (see `floodStopFor`).
31
+ */
32
+ export const BOOTSTRAP_FLOOD_MAX_WAIT_MS = 300_000
33
+
34
+ /**
35
+ * Flood-wait sleep threshold for this process: `TG_SAI_FLOOD_MAX_WAIT_MS`
36
+ * when it is a non-negative integer, else `fallback`, else the subsystem
37
+ * default.
38
+ */
39
+ export function floodMaxWaitMs(
40
+ subsystem: TelemetrySubsystem,
41
+ env: ProfileStoreEnv = process.env,
42
+ fallback?: number,
43
+ ): number {
44
+ const raw = env[FLOOD_MAX_WAIT_ENV]?.trim()
45
+ if (raw && /^\d+$/.test(raw)) return Number(raw)
46
+ if (fallback !== undefined) return fallback
47
+ return subsystem === "worker"
48
+ ? WORKER_FLOOD_MAX_WAIT_MS
49
+ : CLI_FLOOD_MAX_WAIT_MS
50
+ }
51
+
52
+ export const REDACTED = "[redacted]"
53
+
54
+ /** Subcommand words kept as-is when they lead argv. */
55
+ const COMMAND_WORDS = new Set([
56
+ "add",
57
+ "add-bot",
58
+ "add-owner",
59
+ "audit",
60
+ "chat",
61
+ "counts",
62
+ "events",
63
+ "export",
64
+ "find",
65
+ "floods",
66
+ "health",
67
+ "list",
68
+ "ops",
69
+ "prepare",
70
+ "profile",
71
+ "provision",
72
+ "remove",
73
+ "resolve",
74
+ "runs",
75
+ "sai-bootstrap",
76
+ "sai-find",
77
+ "show",
78
+ "stats",
79
+ "status",
80
+ "tail",
81
+ "uncertain",
82
+ "use",
83
+ "worker",
84
+ ])
85
+
86
+ /** Flags that take no value; kept as-is. */
87
+ const BOOLEAN_FLAGS = new Set([
88
+ "--dry-run",
89
+ "--errors",
90
+ "--help",
91
+ "--interactive",
92
+ "--json",
93
+ "--local",
94
+ "--login",
95
+ "--no-env-write",
96
+ "--no-transfer-owner",
97
+ "--offline",
98
+ "--once",
99
+ "--online",
100
+ "--phone",
101
+ "--qr",
102
+ "--run",
103
+ "--session-output",
104
+ "--version",
105
+ "-i",
106
+ ])
107
+
108
+ const NUMBER = /^\d+$/
109
+ const CHAT_ID = /^-?\d+$/
110
+ /** Durations (`15m`) and ISO-like timestamps; no free text. */
111
+ const SINCE = /^\d[0-9A-Za-z:.+-]{0,39}$/
112
+
113
+ /** Value flags whose values are kept when they have the expected shape. */
114
+ const SAFE_VALUE_FLAGS: Record<string, (value: string) => string | null> = {
115
+ "--limit": (v) => (NUMBER.test(v) ? v : null),
116
+ "--interval-ms": (v) => (NUMBER.test(v) ? v : null),
117
+ "--delay-ms": (v) => (NUMBER.test(v) ? v : null),
118
+ "--timeout-ms": (v) => (NUMBER.test(v) ? v : null),
119
+ "--since": (v) => (SINCE.test(v) ? v : null),
120
+ "--chat": (v) => (CHAT_ID.test(v) ? v : null),
121
+ "--chat-id": (v) => (CHAT_ID.test(v) ? v : null),
122
+ "--file": (v) => basename(v) || null,
123
+ }
124
+
125
+ /**
126
+ * Value-taking flags whose values are always redacted. The next token is
127
+ * their value even when it starts with `-` (e.g. `--password -hunter2`).
128
+ */
129
+ const REDACTED_VALUE_FLAGS = new Set([
130
+ "--account",
131
+ "--api-hash",
132
+ "--api-id",
133
+ "--archived",
134
+ "--by",
135
+ "--custody-profile",
136
+ "--display-name",
137
+ "--handle",
138
+ "--layer",
139
+ "--method",
140
+ "--name",
141
+ "--out",
142
+ "--password",
143
+ "--profile",
144
+ "--reason",
145
+ "--request-id",
146
+ "--session-string",
147
+ "--src",
148
+ "--target-peer",
149
+ "--target-user",
150
+ "--user-id",
151
+ ])
152
+
153
+ function isFlag(arg: string): boolean {
154
+ return arg.startsWith("--") || /^-[A-Za-z]$/.test(arg)
155
+ }
156
+
157
+ /** Kept value for `flag`, or `REDACTED`. */
158
+ function flagValue(flag: string, value: string): string {
159
+ const keep = SAFE_VALUE_FLAGS[flag]
160
+ return (keep ? keep(value) : null) ?? REDACTED
161
+ }
162
+
163
+ /**
164
+ * Allowlist view of argv for telemetry rows. Keeps leading subcommand words,
165
+ * flag names, boolean flags, and the values of a few known flags whose
166
+ * values have a safe shape (numbers, durations, numeric chat IDs, the
167
+ * `--file` basename). Every other value and positional becomes `[redacted]`.
168
+ */
169
+ export function sanitizeArgv(argv: readonly string[]): string[] {
170
+ const out: string[] = []
171
+ let leading = true
172
+ for (let i = 0; i < argv.length; i += 1) {
173
+ const arg = argv[i] ?? ""
174
+ if (arg === "--") {
175
+ out.push(arg, ...argv.slice(i + 1).map(() => REDACTED))
176
+ break
177
+ }
178
+ if (!isFlag(arg)) {
179
+ const keep = leading && COMMAND_WORDS.has(arg)
180
+ if (!keep) leading = false
181
+ out.push(keep ? arg : REDACTED)
182
+ continue
183
+ }
184
+ leading = false
185
+ const eq = arg.indexOf("=")
186
+ const flag = eq === -1 ? arg : arg.slice(0, eq)
187
+ if (eq !== -1) {
188
+ out.push(`${flag}=${flagValue(flag, arg.slice(eq + 1))}`)
189
+ continue
190
+ }
191
+ out.push(flag)
192
+ if (BOOLEAN_FLAGS.has(flag)) continue
193
+ const takesValue = flag in SAFE_VALUE_FLAGS || REDACTED_VALUE_FLAGS.has(flag)
194
+ const next = argv[i + 1]
195
+ // Unknown flags: a following positional is redacted on its own pass.
196
+ if (!takesValue || next === undefined) continue
197
+ out.push(flagValue(flag, next))
198
+ i += 1
199
+ }
200
+ return out
201
+ }
202
+
203
+ /** Longest `msg` stored on a log row; longer text is cut. */
204
+ export const LOG_MSG_MAX_CHARS = 120
205
+
206
+ /** Event names reserved for Telegram call and run rows. */
207
+ const RESERVED_EVENT = /^(?:tg|run)\./
208
+ /** Dotted lowercase names such as `log.worker` or `worker.job.claimed`. */
209
+ const LOG_EVENT_NAME = /^[a-z][a-z0-9_]*(?:\.[a-z0-9_-]+)+$/
210
+
211
+ /** Optional row fields a log line may carry besides its run context. */
212
+ export interface LogFields {
213
+ jobId?: string | null
214
+ requestId?: string | null
215
+ accountId?: number | null
216
+ profile?: string | null
217
+ method?: string | null
218
+ durationMs?: number | null
219
+ tsMs?: number
220
+ }
221
+
222
+ /** Writes one app log row; see `logEventFor` for the rules. */
223
+ export type LogFn = (
224
+ level: LogLevel,
225
+ event: string,
226
+ msg: string,
227
+ attrs?: unknown,
228
+ fields?: LogFields,
229
+ ) => void
230
+
231
+ function isLogLevel(value: unknown): value is LogLevel {
232
+ return (LOG_LEVELS as readonly unknown[]).includes(value)
233
+ }
234
+
235
+ /**
236
+ * `event` when it is a dotted lowercase name outside the reserved `tg.*` and
237
+ * `run.*` namespaces; otherwise `log.<subsystem>`.
238
+ */
239
+ export function logEventName(event: string, subsystem: string): string {
240
+ if (LOG_EVENT_NAME.test(event) && !RESERVED_EVENT.test(event)) return event
241
+ return `${LOG_EVENT_PREFIX}${subsystem}`
242
+ }
243
+
244
+ /** Strips control characters and caps the length at `LOG_MSG_MAX_CHARS`. */
245
+ export function cleanLogMsg(msg: string): string {
246
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping them
247
+ const text = String(msg).replace(/[\u0000-\u001f\u007f]+/g, " ").trim()
248
+ return text.length > LOG_MSG_MAX_CHARS
249
+ ? text.slice(0, LOG_MSG_MAX_CHARS)
250
+ : text
251
+ }
252
+
253
+ /**
254
+ * Builds one app log row for the `event` table.
255
+ *
256
+ * - `msg` must be a short constant written in tg-sai code, such as
257
+ * `"setup held for flood wait"`. Never interpolate user data, chat titles,
258
+ * usernames, message text, or error messages into it; put values in
259
+ * `attrs` instead.
260
+ * - `attrs` pass through `summarizeTl`: numbers, booleans, and `_`
261
+ * constructor names survive, every string becomes its length, and
262
+ * secret-looking keys are dropped.
263
+ * - `outcome` is `error` at error level and `ok` otherwise.
264
+ */
265
+ export function logEventFor(
266
+ context: TelemetryContext,
267
+ level: LogLevel,
268
+ event: string,
269
+ msg: string,
270
+ attrs?: unknown,
271
+ fields: LogFields = {},
272
+ ): TelemetryEvent {
273
+ const safeLevel: LogLevel = isLogLevel(level) ? level : "info"
274
+ return {
275
+ runId: context.runId,
276
+ subsystem: context.subsystem,
277
+ command: context.command,
278
+ version: context.version,
279
+ accountId: fields.accountId ?? context.accountId ?? null,
280
+ profile: fields.profile ?? context.profile ?? null,
281
+ jobId: fields.jobId ?? null,
282
+ requestId: fields.requestId ?? null,
283
+ method: fields.method ?? null,
284
+ durationMs: fields.durationMs ?? null,
285
+ ...(fields.tsMs === undefined ? {} : { tsMs: fields.tsMs }),
286
+ event: logEventName(event, context.subsystem),
287
+ outcome: safeLevel === "error" ? "error" : "ok",
288
+ level: safeLevel,
289
+ msg: cleanLogMsg(msg),
290
+ attrs: attrs === undefined ? null : summarizeTl(attrs),
291
+ }
292
+ }
293
+
294
+ /** Records one log row in `sink`; never throws. */
295
+ export function recordLog(
296
+ sink: TelemetrySink,
297
+ context: TelemetryContext,
298
+ ...args: Parameters<LogFn>
299
+ ): void {
300
+ try {
301
+ sink.record(logEventFor(context, ...args))
302
+ } catch {
303
+ // Logging must not break the caller.
304
+ }
305
+ }
306
+
307
+ export interface StandaloneLogOptions {
308
+ env?: ProfileStoreEnv
309
+ subsystem?: TelemetrySubsystem
310
+ command?: string | null
311
+ version?: string
312
+ /** Test seam; defaults to `openTelemetrySink(env)`, closed after use. */
313
+ sink?: TelemetrySink
314
+ }
315
+
316
+ /**
317
+ * Writes one app log row from anywhere. Uses the active run when this
318
+ * process has one; otherwise opens the telemetry DB for this one row under a
319
+ * fresh `run_id`. Honors `TG_SAI_TELEMETRY=off`. Never throws.
320
+ */
321
+ export function log(
322
+ level: LogLevel,
323
+ event: string,
324
+ msg: string,
325
+ attrs?: unknown,
326
+ fields?: LogFields,
327
+ options: StandaloneLogOptions = {},
328
+ ): void {
329
+ const run = options.sink ? null : activeRun
330
+ if (run) {
331
+ run.log(level, event, msg, attrs, fields)
332
+ return
333
+ }
334
+ try {
335
+ const version = options.version ?? "unknown"
336
+ const sink =
337
+ options.sink ??
338
+ openTelemetrySink(options.env ?? process.env, { version })
339
+ const context: TelemetryContext = {
340
+ runId: uuidv7(),
341
+ subsystem: options.subsystem ?? "cli",
342
+ command: options.command ?? null,
343
+ version,
344
+ }
345
+ recordLog(sink, context, level, event, msg, attrs, fields)
346
+ if (!options.sink) sink.close()
347
+ } catch {
348
+ // Logging must not break the caller.
349
+ }
350
+ }
351
+
352
+ export interface RunEndInput {
353
+ exitCode: number
354
+ error?: unknown
355
+ outcome?: TelemetryOutcome
356
+ }
357
+
358
+ /** One process-level run: identity, sink, and flood threshold. */
359
+ export interface TelemetryRun {
360
+ readonly context: TelemetryContext
361
+ readonly sink: TelemetrySink
362
+ readonly floodMaxWaitMs: number
363
+ /** Telemetry for one client; `overrides` add account and profile. */
364
+ client(overrides?: {
365
+ accountId?: number | null
366
+ profile?: string | null
367
+ }): ClientTelemetry
368
+ /** Writes one app log row for this run; see `logEventFor`. */
369
+ log: LogFn
370
+ /** Records the run as aborted (signal) when it ends. */
371
+ markAborted(): void
372
+ /** Writes `run.end` and closes the sink. Idempotent. */
373
+ end(input: RunEndInput): void
374
+ }
375
+
376
+ export interface StartRunOptions {
377
+ subsystem: TelemetrySubsystem
378
+ command: string | null
379
+ argv: readonly string[]
380
+ version: string
381
+ env?: ProfileStoreEnv
382
+ /** Flood-wait threshold when `TG_SAI_FLOOD_MAX_WAIT_MS` is unset. */
383
+ floodMaxWaitMs?: number
384
+ /** Test seam; defaults to `openTelemetrySink(env, {version})`. */
385
+ sink?: TelemetrySink
386
+ stderr?: (line: string) => void
387
+ }
388
+
389
+ let activeRun: TelemetryRun | null = null
390
+
391
+ /** The run started by this process's entry point, if any. */
392
+ export function activeTelemetryRun(): TelemetryRun | null {
393
+ return activeRun
394
+ }
395
+
396
+ /**
397
+ * Opens the sink once and writes `run.start`. Never throws: a DB failure
398
+ * only drops telemetry.
399
+ */
400
+ export function startTelemetryRun(options: StartRunOptions): TelemetryRun {
401
+ const env = options.env ?? process.env
402
+ const stderr =
403
+ options.stderr ??
404
+ ((line: string) => {
405
+ try {
406
+ process.stderr.write(`${line}\n`)
407
+ } catch {
408
+ // Nothing to report to.
409
+ }
410
+ })
411
+ const runId = uuidv7()
412
+ const context: TelemetryContext = {
413
+ runId,
414
+ subsystem: options.subsystem,
415
+ command: options.command,
416
+ version: options.version,
417
+ }
418
+ const sink =
419
+ options.sink ?? openTelemetrySink(env, { version: options.version, stderr })
420
+ const maxWait = floodMaxWaitMs(
421
+ options.subsystem,
422
+ env,
423
+ options.floodMaxWaitMs,
424
+ )
425
+ const startedAt = Date.now()
426
+ let ended = false
427
+ let aborted = false
428
+
429
+ const base = () => ({
430
+ runId,
431
+ subsystem: context.subsystem,
432
+ command: context.command,
433
+ version: context.version,
434
+ })
435
+
436
+ sink.record({
437
+ ...base(),
438
+ event: RUN_START_EVENT,
439
+ outcome: "started",
440
+ req: {
441
+ argv: sanitizeArgv(options.argv),
442
+ floodMaxWaitMs: maxWait,
443
+ },
444
+ })
445
+
446
+ const run: TelemetryRun = {
447
+ context,
448
+ sink,
449
+ floodMaxWaitMs: maxWait,
450
+ client(overrides = {}) {
451
+ const clientContext: TelemetryContext = {
452
+ ...context,
453
+ accountId: overrides.accountId ?? null,
454
+ profile: overrides.profile ?? null,
455
+ }
456
+ return {
457
+ sink,
458
+ context: () => clientContext,
459
+ floodWaiter: { maxWait },
460
+ }
461
+ },
462
+ log(level, event, msg, attrs, fields) {
463
+ if (ended) return
464
+ recordLog(sink, context, level, event, msg, attrs, fields)
465
+ },
466
+ markAborted() {
467
+ aborted = true
468
+ },
469
+ end(input) {
470
+ if (ended) return
471
+ ended = true
472
+ const outcome: TelemetryOutcome =
473
+ input.outcome ??
474
+ (aborted ? "aborted" : input.exitCode === 0 ? "ok" : "error")
475
+ sink.record({
476
+ ...base(),
477
+ event: RUN_END_EVENT,
478
+ outcome,
479
+ durationMs: Date.now() - startedAt,
480
+ // Process exit code; read by `tg-sai events runs`.
481
+ errorCode: input.exitCode,
482
+ err: input.error === undefined ? null : safeErrorText(input.error),
483
+ res: { exitCode: input.exitCode, dropped: sink.dropped() },
484
+ })
485
+ sink.close()
486
+ if (activeRun === run) activeRun = null
487
+ },
488
+ }
489
+ activeRun = run
490
+ return run
491
+ }
@@ -0,0 +1,4 @@
1
+ declare module "*.sql" {
2
+ const text: string
3
+ export default text
4
+ }
@@ -0,0 +1,219 @@
1
+ /**
2
+ * Type-based summaries of TL objects for telemetry `req`/`res` columns.
3
+ *
4
+ * The summarizer is an allowlist by value type, not by method: numbers,
5
+ * booleans, null, and `_` constructor names survive; every string and byte
6
+ * buffer becomes its length; secret-looking keys are dropped outright.
7
+ */
8
+
9
+ export type Summary =
10
+ | number
11
+ | boolean
12
+ | null
13
+ | string
14
+ | Summary[]
15
+ | { [key: string]: Summary }
16
+
17
+ export interface SummarizeOptions {
18
+ /** Object nesting levels kept below the root. Default 3. */
19
+ maxDepth?: number
20
+ /** Serialized size cap in bytes. Default 2048. */
21
+ maxBytes?: number
22
+ }
23
+
24
+ export const DEFAULT_MAX_DEPTH = 3
25
+ export const DEFAULT_MAX_BYTES = 2048
26
+ export const ARRAY_ID_LIMIT = 5
27
+
28
+ /** Keys never recorded, whatever their value (case-insensitive). */
29
+ export const SENSITIVE_KEY =
30
+ /accessHash|hash|password|phone|bytes|session|token|srp/i
31
+
32
+ /**
33
+ * SRP proof fields (`inputCheckPasswordSRP.A`, `.M1`), matched exactly so a
34
+ * lowercase `a` key survives.
35
+ */
36
+ export const SENSITIVE_EXACT_KEYS: ReadonlySet<string> = new Set(["A", "M1"])
37
+
38
+ export function isSensitiveKey(key: string): boolean {
39
+ return SENSITIVE_EXACT_KEYS.has(key) || SENSITIVE_KEY.test(key)
40
+ }
41
+
42
+ /** Keys whose numeric values identify a peer or object in arrays. */
43
+ export const ID_KEYS = ["userId", "channelId", "chatId", "id"] as const
44
+
45
+ /** Methods recorded by name only: their payloads carry credentials. */
46
+ export const NAME_ONLY_METHODS: ReadonlySet<string> = new Set([
47
+ "account.getPassword",
48
+ "account.checkPassword",
49
+ "account.getPasswordSettings",
50
+ "account.updatePasswordSettings",
51
+ ])
52
+
53
+ /** Methods whose `password` field is stripped before summarizing. */
54
+ export const PASSWORD_FIELD_METHODS: ReadonlySet<string> = new Set([
55
+ "channels.editCreator",
56
+ "messages.getBotCallbackAnswer",
57
+ "payments.sendStarsForm",
58
+ ])
59
+
60
+ type Plain = Record<string, unknown>
61
+
62
+ function isPlainObject(value: unknown): value is Plain {
63
+ return typeof value === "object" && value !== null
64
+ }
65
+
66
+ function isBytes(value: unknown): value is ArrayBufferView | ArrayBuffer {
67
+ return ArrayBuffer.isView(value) || value instanceof ArrayBuffer
68
+ }
69
+
70
+ /** Long.js-style 64-bit values (`{low, high, unsigned}`). */
71
+ function isLongLike(value: Plain): boolean {
72
+ return (
73
+ typeof value.low === "number" &&
74
+ typeof value.high === "number" &&
75
+ typeof value.unsigned === "boolean" &&
76
+ typeof value.toString === "function"
77
+ )
78
+ }
79
+
80
+ function byteLength(value: ArrayBufferView | ArrayBuffer): number {
81
+ return value.byteLength
82
+ }
83
+
84
+ /** Numeric id from a Long, bigint, or number; null otherwise. */
85
+ function numericId(value: unknown): number | string | null {
86
+ if (typeof value === "number" && Number.isFinite(value)) return value
87
+ if (typeof value === "bigint") return value.toString()
88
+ if (isPlainObject(value) && isLongLike(value)) return String(value)
89
+ return null
90
+ }
91
+
92
+ /**
93
+ * Collects up to `limit` peer/object ids from array elements, looking at the
94
+ * element itself and one level down (e.g. `inputUser.userId`,
95
+ * `inputPeerChannel.channelId`).
96
+ */
97
+ export function collectIds(
98
+ items: readonly unknown[],
99
+ limit: number = ARRAY_ID_LIMIT,
100
+ ): (number | string)[] {
101
+ const ids: (number | string)[] = []
102
+ const visit = (value: unknown, depth: number): void => {
103
+ if (ids.length >= limit || !isPlainObject(value) || isBytes(value)) return
104
+ for (const key of ID_KEYS) {
105
+ const id = numericId(value[key])
106
+ if (id !== null) {
107
+ ids.push(id)
108
+ return
109
+ }
110
+ }
111
+ if (depth > 0) {
112
+ for (const [key, child] of Object.entries(value)) {
113
+ if (isSensitiveKey(key)) continue
114
+ visit(child, depth - 1)
115
+ if (ids.length >= limit) return
116
+ }
117
+ }
118
+ }
119
+ for (const item of items) {
120
+ const id = numericId(item)
121
+ if (id !== null) ids.push(id)
122
+ else visit(item, 1)
123
+ if (ids.length >= limit) break
124
+ }
125
+ return ids
126
+ }
127
+
128
+ function elementType(value: unknown): string {
129
+ if (value === null) return "null"
130
+ if (Array.isArray(value)) return "array"
131
+ if (isBytes(value)) return "bytes"
132
+ if (isPlainObject(value)) {
133
+ return typeof value._ === "string" ? value._ : "object"
134
+ }
135
+ return typeof value
136
+ }
137
+
138
+ function summarizeAt(value: unknown, depth: number, maxDepth: number): Summary {
139
+ if (value === null || value === undefined) return null
140
+ if (typeof value === "number") return Number.isFinite(value) ? value : null
141
+ if (typeof value === "boolean") return value
142
+ if (typeof value === "bigint") return value.toString()
143
+ if (typeof value === "string") return { len: value.length }
144
+ if (typeof value === "function" || typeof value === "symbol") return null
145
+ if (isBytes(value)) return { len: byteLength(value) }
146
+ if (Array.isArray(value)) {
147
+ const out: { [key: string]: Summary } = { n: value.length }
148
+ if (value.length > 0) {
149
+ out.ids = collectIds(value)
150
+ out.of = elementType(value[0])
151
+ }
152
+ return out
153
+ }
154
+ if (!isPlainObject(value)) return null
155
+ if (isLongLike(value)) return String(value)
156
+ const out: { [key: string]: Summary } = {}
157
+ if (typeof value._ === "string") out._ = value._
158
+ if (depth >= maxDepth) {
159
+ if (out._ === undefined) out.truncated = "depth"
160
+ return out
161
+ }
162
+ for (const [key, child] of Object.entries(value)) {
163
+ if (key === "_" || isSensitiveKey(key)) continue
164
+ if (child === undefined) continue
165
+ out[key] = summarizeAt(child, depth + 1, maxDepth)
166
+ }
167
+ return out
168
+ }
169
+
170
+ function serializedBytes(summary: Summary): number {
171
+ return new TextEncoder().encode(JSON.stringify(summary)).length
172
+ }
173
+
174
+ /**
175
+ * Summarizes any TL-shaped value. If the result exceeds `maxBytes`, retries
176
+ * at shallower depths down to 1, then falls back to a `{_, truncated, bytes}` marker
177
+ * (always valid JSON for the `json_valid` column checks).
178
+ */
179
+ export function summarizeTl(
180
+ value: unknown,
181
+ opts: SummarizeOptions = {},
182
+ ): Summary {
183
+ const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH
184
+ const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES
185
+ let bytes = 0
186
+ for (let depth = maxDepth; depth >= Math.min(1, maxDepth); depth -= 1) {
187
+ const summary = summarizeAt(value, 0, depth)
188
+ bytes = serializedBytes(summary)
189
+ if (bytes <= maxBytes) return summary
190
+ }
191
+ const marker: { [key: string]: Summary } = { truncated: "size", bytes }
192
+ if (isPlainObject(value) && typeof value._ === "string") {
193
+ return { _: value._, ...marker }
194
+ }
195
+ return marker
196
+ }
197
+
198
+ /** True for methods whose request is recorded by name only. */
199
+ export function isNameOnlyMethod(method: string): boolean {
200
+ return method.startsWith("auth.") || NAME_ONLY_METHODS.has(method)
201
+ }
202
+
203
+ /**
204
+ * Summarizes an outgoing request. Credential-bearing methods record only
205
+ * `{_}`; methods with a `password` argument (e.g. `channels.editCreator`)
206
+ * keep their peer ids but never the password object.
207
+ */
208
+ export function summarizeRequest(
209
+ method: string,
210
+ request: unknown,
211
+ opts: SummarizeOptions = {},
212
+ ): Summary {
213
+ if (isNameOnlyMethod(method)) return { _: method }
214
+ if (PASSWORD_FIELD_METHODS.has(method) && isPlainObject(request)) {
215
+ const { password: _password, ...rest } = request
216
+ return summarizeTl(rest, opts)
217
+ }
218
+ return summarizeTl(request, opts)
219
+ }