@soffits/dsh-telegram-bot 0.0.0-stage → 0.4.1

package/src/topics.js

@@ -0,0 +1,211 @@
+/** Topic names known to the bot, send targets and topic errors. */
+
+/**
+ * Pick the topic name a Telegram message announces, if any.
+ * @param message - Telegram message, including service messages.
+ * @returns `{ name, authoritative }`, or undefined.
+ */
+export function topicNameOf(message) {
+  const created = message?.forum_topic_created?.name
+  if (typeof created === 'string' && created.trim().length > 0) return { name: created.trim(), authoritative: true }
+  const edited = message?.forum_topic_edited?.name
+  if (typeof edited === 'string' && edited.trim().length > 0) return { name: edited.trim(), authoritative: true }
+  // Replies in a topic often carry its creation message; use it only to fill
+  // a gap, because it shows the name the topic was created with.
+  const original = message?.reply_to_message?.forum_topic_created?.name
+  if (typeof original === 'string' && original.trim().length > 0) return { name: original.trim(), authoritative: false }
+  return undefined
+}
+
+/** Joins a topic name and the task part of a topic session's title. */
+export const TITLE_SEPARATOR = ' · '
+
+/** The title form earlier versions gave topic sessions: "TG · <topic name>". */
+const LEGACY_PREFIX = 'TG · '
+
+/**
+ * The DSH title of a topic session: the topic name, then what the
+ * conversation is about once DSH has titled it.
+ * @param prefix - the topic's name.
+ * @param task - the conversation's own title, or empty before one exists.
+ * @returns the session title.
+ */
+export function topicTitle(prefix, task) {
+  const rest = typeof task === 'string' ? task.trim() : ''
+  return rest.length === 0 ? prefix : `${prefix}${TITLE_SEPARATOR}${rest}`
+}
+
+/**
+ * Whether a title is one the bot set before any conversation title existed:
+ * a bare topic name (current or earlier) or the old "TG · <name>" form.
+ * @param title - current session title.
+ * @param names - topic names the title may carry.
+ * @returns true for a bot placeholder.
+ */
+export function isPlaceholderTitle(title, names) {
+  return typeof title === 'string' && (title.startsWith(LEGACY_PREFIX) || names.includes(title))
+}
+
+/**
+ * The conversation part of a title, without a topic-name prefix the bot added.
+ * @param title - current session title.
+ * @param names - topic names a prefix may carry, current name first.
+ * @returns the task part; empty when the title is only a prefix.
+ */
+export function topicTask(title, names) {
+  if (isPlaceholderTitle(title, names)) return ''
+  // Longest name first, so "Chat · 2" wins over "Chat" for "Chat · 2 · Fix".
+  for (const name of [...names].sort((a, b) => b.length - a.length)) {
+    if (title.startsWith(`${name}${TITLE_SEPARATOR}`)) return title.slice(name.length + TITLE_SEPARATOR.length).trim()
+  }
+  return title
+}
+
+/**
+ * Commands about the chat as a whole rather than one topic. When one of them
+ * is sent in All, Telegram turns it into a topic of its own; the bot answers
+ * in All instead and removes that topic.
+ */
+export const CHAT_COMMANDS = new Set(['/start', '/help', '/sessions', '/status', '/menu', '/id', '/ping', '/restart'])
+
+/**
+ * Whether a message is a chat-wide command that Telegram moved into a topic it
+ * created for that very message: users who may create topics get one for any
+ * message sent in All, named after the message.
+ * @param command - normalized command token, such as `/start`.
+ * @param text - full message text.
+ * @param topicName - known name of the message's topic, if any.
+ * @param fresh - whether the topic has no session and no earlier activity.
+ * @returns true when the command should be answered in All.
+ */
+export function isAutoCommandTopic(command, text, topicName, fresh) {
+  if (!fresh || !CHAT_COMMANDS.has(command)) return false
+  if (typeof topicName !== 'string' || typeof text !== 'string') return false
+  const name = topicName.trim()
+  // Telegram names the topic after the message, cut to 128 characters.
+  return name.startsWith('/') && text.trim().startsWith(name)
+}
+
+/**
+ * Whether a Bot API error means the topic itself no longer exists, so its
+ * binding can never work again. A closed topic is not gone: it can be reopened.
+ * @param description - Telegram's error description.
+ * @returns true for a deleted or invalid topic.
+ */
+export function isTopicGone(description) {
+  return /message thread not found|(?:topic|thread)[^.]{0,40}(?:not found|deleted)|TOPIC_ID_INVALID|TOPIC_DELETED/iu.test(String(description ?? ''))
+}
+
+/** True when a thread id denotes the chat-wide All topic. */
+function isAllTopic(threadId) {
+  return threadId === undefined || threadId === null || threadId === 0 || threadId === 1
+}
+
+/**
+ * Outbound topic fields for send methods. Private-chat and forum topics use
+ * `message_thread_id`; a cached direct id is used only for chats without a
+ * forum thread (for example channel direct-messages chats).
+ * @param directChats - `{ "<chatId>": true }` for private chats with topics.
+ * @param directTopics - `{ "<chatId>:<threadId>": directTopicId }`.
+ * @param chatId - chat holding the topic.
+ * @param threadId - stored topic thread id.
+ * @returns `{}`, `{ message_thread_id }` or `{ direct_messages_topic_id }`.
+ */
+export function topicTargetFor(directChats, directTopics, chatId, threadId) {
+  if (isAllTopic(threadId)) return {}
+  // Private-chat topics use message_thread_id. If Telegram rejects it with
+  // "message thread not found", call() retries with direct_messages_topic_id.
+  if (directChats?.[String(chatId)] === true) return { message_thread_id: threadId }
+  const direct = directTopics?.[`${chatId}:${threadId}`]
+  if (Number.isSafeInteger(direct)) return { direct_messages_topic_id: direct }
+  return { message_thread_id: threadId }
+}
+
+/**
+ * Whether a Bot API message proves it reached the expected topic. A response
+ * without any topic field is not proof: Telegram may have silently sent the
+ * message into All after the topic was deleted.
+ * @param directChats - `{ "<chatId>": true }` for private chats with topics.
+ * @param directTopics - `{ "<chatId>:<threadId>": directTopicId }`.
+ * @param chatId - chat holding the topic.
+ * @param threadId - stored topic thread id.
+ * @param delivered - Bot API result for the sent message.
+ * @returns whether the message belongs to the expected topic.
+ */
+export function deliveredToTopic(directChats, directTopics, chatId, threadId, delivered) {
+  if (delivered === null || typeof delivered !== 'object') return false
+  if (typeof delivered.message_thread_id === 'number') return delivered.message_thread_id === threadId
+  const direct = delivered.direct_messages_topic?.topic_id
+  if (typeof direct === 'number') {
+    if (directChats?.[String(chatId)] === true) return direct === threadId
+    const expected = directTopics?.[`${chatId}:${threadId}`]
+    return typeof expected !== 'number' || direct === expected
+  }
+  // No topic fields at all: Telegram silently drops a message into All when
+  // the topic is gone, so this is not proof of delivery.
+  return false
+}
+
+/**
+ * Resolve a programmatic send target to the chat that owns the thread.
+ * Thread ids belong to one chat (each private chat has its own topics), so
+ * the chat comes from where the bot saw the thread, never from whichever chat
+ * spoke last. Only numeric thread ids are accepted; topic names are display
+ * text, not addresses.
+ * @param keys - known `"<chatId>:<threadId>"` topic keys.
+ * @param chat - chat id the caller names, or undefined to use the owner.
+ * @param target - thread id, as a number or a string of digits.
+ * @returns `{ chatId, threadId }`.
+ */
+export function resolveSendTarget(keys, chat, target) {
+  const raw = typeof target === 'number' ? String(target) : String(target ?? '').trim()
+  if (raw.length === 0) throw new Error('A Telegram thread id is required.')
+  if (!/^\d+$/u.test(raw)) throw new Error(`"${raw}" is not a Telegram thread id. Topics are addressed by their numeric thread id; /id in a topic shows it.`)
+  const threadId = Number(raw)
+  const owners = [...new Set([...keys]
+    .map((key) => String(key).match(/^(-?\d+):(\d+)$/u))
+    .filter((match) => match !== null && Number(match[2]) === threadId)
+    .map((match) => match[1]))]
+  const wanted = typeof chat === 'number' ? String(chat) : String(chat ?? '').trim()
+  if (wanted.length > 0) {
+    if (!/^-?\d+$/u.test(wanted)) throw new Error(`"${wanted}" is not a Telegram chat id.`)
+    if (!owners.includes(wanted)) throw new Error(`Unknown thread id ${threadId} in chat ${wanted}: the bot knows no topic with that id there. /id in a topic shows its thread id.`)
+    return { chatId: Number(wanted), threadId }
+  }
+  if (owners.length === 0) throw new Error(`Unknown thread id ${threadId}: the bot knows no topic with that id in any chat. /id in a topic shows its thread id.`)
+  if (owners.length > 1) throw new Error(`Thread id ${threadId} exists in several chats (${owners.join(', ')}); name the chat to send to.`)
+  return { chatId: Number(owners[0]), threadId }
+}
+
+/**
+ * Resolve a `/topic delete` target typed by a person: a topic thread id, or a
+ * known topic name compared without regard to case. Programmatic sends use
+ * `resolveSendTarget`, since names can change.
+ * @param names - `{ "<chatId>:<threadId>": name }`.
+ * @param chatId - chat the topics live in.
+ * @param target - topic name or thread id.
+ * @returns `{ threadId, name }`.
+ */
+export function resolveTopicTarget(names, chatId, target) {
+  const raw = typeof target === 'number' ? String(target) : String(target ?? '').trim()
+  if (raw.length === 0) throw new Error('A topic name or thread id is required.')
+  const known = Object.entries(names ?? {})
+    .filter(([key]) => key.startsWith(`${chatId}:`))
+    .map(([key, name]) => ({ threadId: Number(key.slice(String(chatId).length + 1)), name: String(name) }))
+  if (/^\d+$/u.test(raw)) {
+    const threadId = Number(raw)
+    if (!Number.isSafeInteger(threadId) || threadId <= 0 || threadId > 2_147_483_647) {
+      const list = known.map((entry) => `"${entry.name}" (${entry.threadId})`).join(', ')
+      throw new Error(`"${raw}" is not a Telegram topic id. Topic ids are message-thread ids (for example 55221).${list.length > 0 ? ` Known topics: ${list}.` : ''} Send /id inside the topic to see its id.`)
+    }
+    return { threadId, name: known.find((entry) => entry.threadId === threadId)?.name }
+  }
+  const wanted = raw.toLocaleLowerCase()
+  const matches = known.filter((entry) => entry.name.trim().toLocaleLowerCase() === wanted)
+  if (matches.length === 1) return matches[0]
+  if (matches.length > 1) {
+    throw new Error(`Several topics are named "${raw}" (thread ids ${matches.map((entry) => entry.threadId).join(', ')}). Send to a thread id instead.`)
+  }
+  const list = known.map((entry) => `"${entry.name}" (${entry.threadId})`).join(', ')
+  throw new Error(`Unknown Telegram topic "${raw}". ${list.length > 0 ? `Known topics: ${list}.` : 'The bot knows no topic names yet.'} Rename the topic in Telegram or with /rename so the bot learns its name, or send to its thread id (/id in the topic).`)
+}

package/src/update-ledger.js

@@ -0,0 +1,58 @@
+import { messageOf } from './utils.js'
+
+/**
+ * Serialize one Telegram update stream and persist its cursor before side effects.
+ * A pending entry left by a crash is marked uncertain and never replayed.
+ */
+export function createUpdateAdmission({ getState, persist, handle, onError = () => {} }) {
+  let tail = Promise.resolve()
+
+  async function process(update, signal) {
+    if (!Number.isSafeInteger(update?.update_id)) return
+    const state = getState()
+    state.updateLedger ??= {}
+    state.updateOffset ??= 0
+    const key = String(update.update_id)
+    const previous = state.updateLedger[key]
+    if (previous !== undefined) {
+      if (previous === 'pending') {
+        state.updateLedger[key] = 'uncertain'
+        state.updateOffset = Math.max(state.updateOffset, update.update_id + 1)
+        await persist()
+        try {
+          await onError(new Error(`Update ${update.update_id} has an uncertain outcome; refusing to replay`), update, signal)
+        } catch {
+          // Error reporting must never replay the update.
+        }
+      }
+      return
+    }
+    if (update.update_id < state.updateOffset) return
+    state.updateLedger[key] = 'pending'
+    await persist()
+    try {
+      await handle(update, signal)
+      state.updateLedger[key] = 'done'
+      state.updateOffset = Math.max(state.updateOffset, update.update_id + 1)
+      const keys = Object.keys(state.updateLedger).sort((a, b) => Number(b) - Number(a))
+      for (const old of keys.slice(256)) delete state.updateLedger[old]
+      await persist()
+    } catch (error) {
+      // Keep `pending`: after restart it becomes `uncertain`, not replayed.
+      throw error
+    }
+  }
+
+  return {
+    accept(update, signal) {
+      const result = tail.then(() => process(update, signal))
+      tail = result.catch(() => {})
+      return result
+    },
+    idle() {
+      return tail.then(() => undefined)
+    },
+  }
+}
+
+export { messageOf }

package/src/utils.js

@@ -0,0 +1,139 @@
+/** Small dependency-free helpers. */
+import { DEFAULT_TOKEN_REF } from './constants.js'
+
+/**
+ * Read one error without ever touching the token.
+ * @param error - a thrown value.
+ * @returns a short diagnostic.
+ */
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Sleep that settles early when the runtime is stopped.
+ * @param ms - delay in milliseconds.
+ * @param signal - runtime lifetime.
+ * @returns resolves after the delay or the abort.
+ */
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms)
+    signal.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer)
+        resolve()
+      },
+      { once: true },
+    )
+  })
+}
+
+/**
+ * Normalize one allowlist entry for case-insensitive comparison.
+ * @param value - id or @username.
+ * @returns normalized value.
+ */
+function normalizeEntry(value) {
+  return String(value).trim().toLowerCase()
+}
+
+/**
+ * Read a Config field that may be a plain value or a volatile live reference.
+ * @param value - Config field or Volatile reference.
+ * @param fallback - value used when the field is absent.
+ * @returns the current value.
+ */
+function readLive(value, fallback) {
+  if (value !== null && typeof value === 'object' && typeof value.get === 'function') {
+    try {
+      const current = value.get()
+      return current === undefined ? fallback : current
+    } catch {
+      return fallback
+    }
+  }
+  return value === undefined || value === null ? fallback : value
+}
+
+/** @returns the live credential reference for the bot token. */
+function tokenRefOf(config) {
+  const value = readLive(config.tokenRef, DEFAULT_TOKEN_REF)
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : DEFAULT_TOKEN_REF
+}
+
+/** @returns whether the runtime is enabled in the live Config. */
+function isEnabled(config) {
+  return readLive(config.enabled, true) !== false
+}
+
+/** @returns the live allowed-user list. */
+function allowedUsersOf(config) {
+  const value = readLive(config.allowedUsers, [])
+  return Array.isArray(value) ? value : []
+}
+
+/** @returns the live allowed-chat list. */
+function allowedChatsOf(config) {
+  const value = readLive(config.allowedChats, [])
+  return Array.isArray(value) ? value : []
+}
+
+/**
+ * The chat that gets lifecycle notices (bot enabled, Threaded mode warnings):
+ * `controlChat` when set, otherwise the private chat of the first allowed
+ * user, whose chat id is their user id. Both come from config, so a message
+ * from another allowed user never moves it.
+ * @returns a chat id or @channelname, or undefined when there is none (the
+ * first allowed user is a @username and `controlChat` is empty).
+ */
+function controlChatOf(config) {
+  const configured = readLive(config.controlChat, '')
+  const chat = typeof configured === 'string' ? configured.trim() : ''
+  if (chat.length > 0) return /^-?\d+$/u.test(chat) ? Number(chat) : chat
+  const owner = String(allowedUsersOf(config)[0] ?? '').trim()
+  return /^\d+$/u.test(owner) ? Number(owner) : undefined
+}
+
+/**
+ * Whether one user is on the allowlist.
+ * @param from - Telegram user.
+ * @param allowedUsers - configured entries.
+ * @returns whether the user may talk to the bot.
+ */
+function userAllowed(from, allowedUsers) {
+  if (from === undefined || !Array.isArray(allowedUsers)) return false
+  const id = String(from.id)
+  const username = typeof from.username === 'string' ? `@${from.username.toLowerCase()}` : undefined
+  return allowedUsers.some((entry) => entry === id || (username !== undefined && normalizeEntry(entry) === username))
+}
+
+/**
+ * Whether one chat is on the allowlist. An empty chat list allows private
+ * chats only; a non-empty list requires the chat itself to match.
+ * @param chat - Telegram chat.
+ * @param allowedChats - configured entries.
+ * @returns whether the bot may answer in this chat.
+ */
+function chatAllowed(chat, allowedChats) {
+  if (!Array.isArray(allowedChats) || allowedChats.length === 0) return chat.type === 'private'
+  const id = String(chat.id)
+  const username = typeof chat.username === 'string' ? `@${chat.username.toLowerCase()}` : undefined
+  return allowedChats.some((entry) => entry === id || (username !== undefined && normalizeEntry(entry) === username))
+}
+
+
+export {
+  messageOf,
+  sleep,
+  normalizeEntry,
+  readLive,
+  tokenRefOf,
+  isEnabled,
+  allowedUsersOf,
+  allowedChatsOf,
+  controlChatOf,
+  userAllowed,
+  chatAllowed,
+}

package/src/voice.js

@@ -0,0 +1,151 @@
+/** Voice messages, audio files and round video messages: decoding and transcription. */
+import { spawn } from 'node:child_process'
+
+/** Telegram message fields that carry speech, with a default file extension. */
+const SPOKEN = [
+  { field: 'voice', kind: 'voice message', extension: '.ogg' },
+  { field: 'video_note', kind: 'video message', extension: '.mp4' },
+  { field: 'audio', kind: 'audio file', extension: '.mp3' },
+]
+
+/**
+ * The spoken media a message carries, if any.
+ * @param message - Telegram message.
+ * @returns `{ field, kind, file, name, seconds }`, or undefined.
+ */
+export function spokenMediaOf(message) {
+  for (const entry of SPOKEN) {
+    const file = message?.[entry.field]
+    if (typeof file?.file_id !== 'string') continue
+    const id = message.message_id ?? Date.now()
+    const name = typeof file.file_name === 'string' && file.file_name.length > 0
+      ? file.file_name
+      : `telegram-${entry.field.replace('_', '-')}-${id}${entry.extension}`
+    return { field: entry.field, kind: entry.kind, file, name, seconds: typeof file.duration === 'number' ? file.duration : undefined }
+  }
+  return undefined
+}
+
+/**
+ * Wrap raw 16 kHz mono 16-bit PCM in the canonical 44-byte WAV header that
+ * DSH speech providers accept.
+ * @param pcm - little-endian samples.
+ * @returns WAV bytes.
+ */
+export function pcmToWave(pcm) {
+  const data = pcm.length % 2 === 0 ? pcm : pcm.subarray(0, pcm.length - 1)
+  const header = Buffer.alloc(44)
+  header.write('RIFF', 0, 'ascii')
+  header.writeUInt32LE(36 + data.length, 4)
+  header.write('WAVE', 8, 'ascii')
+  header.write('fmt ', 12, 'ascii')
+  header.writeUInt32LE(16, 16)
+  header.writeUInt16LE(1, 20)
+  header.writeUInt16LE(1, 22)
+  header.writeUInt32LE(16000, 24)
+  header.writeUInt32LE(32000, 28)
+  header.writeUInt16LE(2, 32)
+  header.writeUInt16LE(16, 34)
+  header.write('data', 36, 'ascii')
+  header.writeUInt32LE(data.length, 40)
+  return Buffer.concat([header, data])
+}
+
+/**
+ * Run one program and collect its output.
+ * @param argv - program and arguments; no shell is involved.
+ * @param signal - cancellation.
+ * @param timeoutMs - upper bound for the run.
+ * @returns stdout bytes; rejects with stderr on a non-zero exit.
+ */
+export function runProgram(argv, signal, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error('aborted'))
+      return
+    }
+    const child = spawn(argv[0], argv.slice(1), { stdio: ['ignore', 'pipe', 'pipe'] })
+    const out = []
+    const err = []
+    let settled = false
+    const finish = (error, value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', abort)
+      if (error) reject(error)
+      else resolve(value)
+    }
+    const abort = () => {
+      child.kill('SIGKILL')
+      finish(new Error(`${argv[0]} was cancelled`))
+    }
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      finish(new Error(`${argv[0]} took longer than ${Math.round(timeoutMs / 1000)} s`))
+    }, timeoutMs)
+    signal?.addEventListener('abort', abort, { once: true })
+    child.stdout.on('data', (chunk) => out.push(chunk))
+    child.stderr.on('data', (chunk) => err.push(chunk))
+    child.on('error', (error) => finish(new Error(`${argv[0]} could not start: ${error.message}`)))
+    child.on('close', (code) => {
+      if (code === 0) finish(undefined, Buffer.concat(out))
+      else finish(new Error(`${argv[0]} exited with ${code}: ${Buffer.concat(err).toString('utf8').trim().slice(-400)}`))
+    })
+  })
+}
+
+/**
+ * Transcribe one recording.
+ * @param options - `{ mode, path, language, command, ffmpeg, speech, signal, timeoutMs }`:
+ *   `mode` is `dsh` (the DSH speech-to-text service, `speech`), `command`
+ *   (`command` argv, `{file}` replaced by `path`, transcript on stdout) or `off`.
+ * @returns `{ text, by }`; rejects when transcription fails.
+ */
+export async function transcribe(options) {
+  const { mode, path, signal } = options
+  const timeoutMs = options.timeoutMs ?? 180_000
+  if (mode === 'command') {
+    const command = Array.isArray(options.command) ? options.command.filter((part) => typeof part === 'string') : []
+    if (command.length === 0) throw new Error('no transcription command is configured')
+    const argv = command.some((part) => part.includes('{file}'))
+      ? command.map((part) => part.replaceAll('{file}', path))
+      : [...command, path]
+    const text = (await runProgram(argv, signal, timeoutMs)).toString('utf8').trim()
+    return { text, by: 'the configured transcription command' }
+  }
+  if (mode !== 'dsh') throw new Error('transcription is turned off')
+  const speech = options.speech
+  if (speech === undefined || typeof speech.resolve !== 'function') throw new Error('the DSH speech-to-text service is not enabled')
+  const pcm = await runProgram(
+    [options.ffmpeg || 'ffmpeg', '-nostdin', '-hide_banner', '-loglevel', 'error', '-i', path, '-vn', '-ac', '1', '-ar', '16000', '-f', 's16le', 'pipe:1'],
+    signal,
+    timeoutMs,
+  )
+  if (pcm.length === 0) throw new Error('the recording has no audio')
+  const spec = speech.resolve({
+    audio: pcmToWave(pcm),
+    ...(typeof options.language === 'string' && options.language.length > 0 ? { language: options.language } : {}),
+  })
+  const result = await speech.transcribe(spec, signal ?? new AbortController().signal)
+  const provider = spec.provider?.info?.name ?? spec.provider?.info?.id
+  return { text: String(result?.text ?? '').trim(), by: `DSH speech-to-text${provider ? ` (${provider})` : ''}` }
+}
+
+/**
+ * The text the agent reads next to a spoken recording.
+ * @param media - result of {@link spokenMediaOf}.
+ * @param outcome - `{ path, text, by, error }`.
+ * @returns prompt text.
+ */
+export function transcriptNote(media, outcome) {
+  const length = media.seconds === undefined ? '' : `, ${Math.floor(media.seconds / 60)}:${String(media.seconds % 60).padStart(2, '0')}`
+  const where = typeof outcome.path === 'string' ? `the file is attached and saved at ${outcome.path}` : 'the file is attached'
+  if (outcome.error !== undefined) {
+    return `[Telegram ${media.kind} "${media.name}"${length}: not transcribed (${outcome.error}); ${where}]`
+  }
+  if (outcome.text.length === 0) {
+    return `[Telegram ${media.kind} "${media.name}"${length}: ${outcome.by} heard no speech; ${where}]`
+  }
+  return `[Telegram ${media.kind} "${media.name}"${length}, transcribed by ${outcome.by}; the transcript may contain mistakes, and ${where} to check it]\n${outcome.text}`
+}