data-ark 0.1.0 → 0.1.2

package/README.md

@@ -1,50 +1,89 @@
 # data-ark
 
-Cắt file lớn thành từng chunk 1.8GB và lưu trữ trên Telegram, khôi phục lại được nguyên vẹn.
+Split large files into 1.8GB chunks, store them on Telegram, and restore them intact.
 
-## Dùng ngay
+## Quick start
 
 ```bash
-npx data-ark login                        # chỉ cần một lần
-npx data-ark data.tar --to @kho_backup    # đích được ghi nhớ cho lần sau
-npx data-ark data.tar                     # từ lần thứ hai trở đi
+npx data-ark login                        # once only
+npx data-ark data.tar --to @my_backups    # the destination is remembered
+npx data-ark --to @my_backups             # only change the destination, upload nothing
+npx data-ark status                       # account, destination, unfinished backups
+npx data-ark list                         # what is already stored in the destination
+npx data-ark data.tar                     # from the second run on
 npx data-ark restore ark-20260905-7f3a91
 ```
 
-## Cần chuẩn bị
+## What you need
 
-- Node.js 18 trở lên.
-- `api_id` và `api_hash` lấy tại <https://my.telegram.org> → API development tools. Lệnh `login` sẽ hỏi hai giá trị này, kèm số điện thoại và mã xác nhận.
+- Node.js 18 or newer.
+- An `api_id` and `api_hash` from <https://my.telegram.org> → API development tools. The `login` command asks for both, plus your phone number and the verification code.
 
-data-ark đăng nhập bằng chính tài khoản Telegram của bạn (MTProto), không phải bot. Đây là điều kiện bắt buộc: Bot API chỉ cho upload 50MB mỗi file, còn tài khoản người dùng được 2GB.
+data-ark signs in with your own Telegram account (MTProto), not a bot. That is a hard requirement: the Bot API caps uploads at 50MB per file, while a user account gets 2GB.
 
-## Tuỳ chọn
+## Options
 
-| Cờ | Mặc định | Ý nghĩa |
+| Flag | Default | Meaning |
 |---|---|---|
-| `--to <chat>` | đích đã ghi nhớ | `@username`, `-100123…`, hoặc `me` |
-| `--chunk-size <n>` | `1800MB` | Ví dụ `1.8GB`, `500MB`. Trần cứng 1950MB. |
-| `--concurrency <n>` | `8` | Số phần 512KB gửi song song. Phải là số nguyên từ 1 đến 64. |
-| `--out <đường-dẫn>` | basename của tên trong manifest | Nơi ghi file khi restore, tính từ thư mục hiện tại nếu là đường dẫn tương đối |
+| `--to <chat>` | the remembered destination | `@username`, `-100123…`, or `me`. `upload` and `status` remember it; `list` and `restore` only look there. A negative channel id works either way: `--to -100123…` or `--to=-100123…` |
+| `--chunk-size <n>` | `1800MB` | e.g. `1.8GB`, `500MB`. Hard ceiling 1950MB. |
+| `--concurrency <n>` | `8` | 512KB parts sent in parallel. An integer from 1 to 64. |
+| `--out <path>` | the basename from the manifest | Where to write the restored file; relative paths resolve against the current directory |
+| `--limit <n>` | `20` | How many backups `list` shows, newest first |
+| `--verbose` | off | Show the Telegram client's own connection logs, hidden by default so they do not break up the progress bar |
 
-## Hoạt động thế nào
+## What the chat looks like
 
-Mỗi lần chạy sinh ra một `backupId`. File được đọc thẳng theo offset, không tạo file tạm, và đẩy lên thành các document tên `<backupId>.partNNNN`. Xong hết, data-ark gửi thêm một manifest JSON liệt kê message id và sha256 của từng chunk. Restore chỉ cần `backupId`: nó tìm manifest trong chat, tải từng chunk về đúng vị trí trong một file `.partial`, đối chiếu sha256 và kích thước từng chunk, và chỉ đổi tên thành file thật sau khi *toàn bộ* chunk đã khớp.
+Every chunk goes up as a document captioned `📦 <backupId> · 3/12`, and the manifest that
+follows carries a summary card:
 
-Đứt mạng giữa chừng lúc **upload** thì cứ chạy lại đúng lệnh cũ — tiến độ nằm ở `~/.data-ark/state/`, những chunk đã xong sẽ được bỏ qua (`backupId` giữ nguyên). Vài lưu ý về việc chạy lại:
+```
+🗄 data.tar
+━━━━━━━━━━━━━━━
+💾 21.4 GB · 12 chunks
+🆔 ark-20260905-7f3a91
+📅 2026-09-05 16:40 UTC
+
+↩ npx data-ark restore ark-20260905-7f3a91
+#dataark
+```
+
+`npx data-ark list` reads those cards straight out of the chat — one search, no downloads —
+and lays them out as a table:
+
+```
+Destination  https://web.telegram.org/k/#@my_backups
+
+BACKUP ID            FILE            SIZE  CHUNKS  CREATED
+ark-20260905-7f3a91  data.tar     21.4 GB      12  2026-09-05
+ark-20260901-9de447  photos.zip  940.3 MB       1  2026-09-01
+
+2 backups. Restore with: npx data-ark restore <backup-id>
+```
+
+A backup uploaded before the card existed still gets a row, with dashes where the caption
+says nothing — `list` reports what the chat holds and never fills gaps with guesses.
+`--to` here only chooses which chat to look at; it does not move the destination the way
+`status --to` does.
+
+## How it works
+
+Every run mints a `backupId`. The file is read directly by offset — no temporary copies — and uploaded as documents named `<backupId>.partNNNN`. Once every chunk is up, data-ark sends a JSON manifest listing the message id and sha256 of each one. Restore needs only the `backupId`: it finds the manifest in the chat, downloads each chunk to its exact position in a `.partial` file, checks every chunk's sha256 and size, and renames it to the real file only after *all* chunks match.
+
+If the connection drops during an **upload**, just run the same command again — progress lives in `~/.data-ark/state/` and finished chunks are skipped, keeping the same `backupId`. Two things to know about rerunning:
 
-- Nếu chạy lại với `--to` khác với đích đã lưu trong tiến độ dở dang, data-ark **từ chối chạy** thay vì tự chuyển hướng — một backup không thể tách làm hai đích. Thông báo lỗi chỉ đường: bỏ `--to` để tiếp tục gửi vào đích cũ, hoặc xoá file trạng thái để bắt đầu backup mới.
-- Nếu chạy lại với `--chunk-size` khác, data-ark coi đó là một backup mới hoàn toàn (backup id mới), không resume.
+- Running again with a `--to` that differs from the destination stored in the unfinished progress makes data-ark **refuse to run** rather than silently redirect — one backup cannot be split across two destinations. The error points the way out: drop `--to` to keep sending to the original destination, or delete the state file to start a new backup.
+- Running again with a different `--chunk-size` is treated as an entirely new backup (new backup id), not a resume.
 
-**Restore không có trạng thái để resume.** Nhấn `Ctrl-C` giữa lúc restore thì không có gì được lưu — chạy lại sẽ tải lại từ đầu.
+**Restore keeps no state to resume from.** Pressing `Ctrl-C` mid-restore saves nothing — running again starts over.
 
-## Giới hạn cần biết
+## Limits worth knowing
 
-- Chunk không thể vượt 1950MB: Telegram nhận tối đa 4000 phần 512KB mỗi file, tức trần số học khoảng 1953MB, và data-ark chốt ở 1950MB để chừa biên an toàn.
-- Dữ liệu **không** được mã hoá. Đừng đẩy thứ gì bạn không muốn nằm trên hạ tầng của người khác.
-- Xoá message chunk trên Telegram là mất backup, không có cách cứu.
-- Giữ lấy `backupId`. Không có nó thì phải tự tìm manifest trong chat bằng tay.
+- A chunk cannot exceed 1950MB: Telegram accepts at most 4000 parts of 512KB per file, an arithmetic ceiling of about 1953MB, and data-ark stops at 1950MB to leave a safety margin.
+- The data is **not** encrypted. Don't upload anything you would mind sitting on someone else's infrastructure.
+- Deleting a chunk message on Telegram destroys the backup, with no way to recover it.
+- Keep the `backupId`. Without it you have to hunt for the manifest in the chat by hand.
 
-## Cấu hình lưu ở đâu
+## Where the config lives
 
-`~/.data-ark/config.json` (quyền 600) chứa `apiId`, `apiHash`, session và đích lưu mặc định. `npx data-ark logout` **chỉ xoá bản session lưu dưới máy** và giữ lại phần còn lại — phiên đăng nhập vẫn còn sống phía Telegram. Muốn cắt hẳn quyền truy cập thì vào Telegram → Settings → Devices (Active sessions) và thu hồi phiên đó.
+`~/.data-ark/config.json` (mode 600) holds `apiId`, `apiHash`, the session and the default destination. `npx data-ark logout` **only deletes the locally stored session** and keeps the rest — the session is still alive on Telegram's side. To revoke access for good, open Telegram → Settings → Devices (Active sessions) and terminate that session.

package/bin/data-ark.js

@@ -1,26 +1,29 @@
 #!/usr/bin/env node
 import { route, HELP } from '../src/cli.js'
 import { runLogin } from '../src/commands/login.js'
+import { runList } from '../src/commands/list.js'
 import { runLogout } from '../src/commands/logout.js'
 import { runRestore } from '../src/commands/restore.js'
+import { runSetDestination } from '../src/commands/set-destination.js'
+import { runStatus } from '../src/commands/status.js'
 import { runUpload } from '../src/commands/upload.js'
 
 const SIGINT_EXIT_CODE = 130
 
-// Lệnh đang chạy khi Ctrl-C xảy ra — mỗi lệnh có một sự thật khác nhau về việc
-// tiến độ có được lưu hay không, nên phải biết đang ở lệnh nào mới chọn đúng câu.
+// Which command is running when Ctrl-C arrives — each one tells a different truth
+// about whether progress was saved, so we need to know which to pick the right line.
 let currentCommand = null
 
 function sigintMessage(command) {
   if (command === 'upload') {
-    return '\nĐã dừng. Tiến độ đã lưu, chạy lại lệnh cũ để đi tiếp.\n'
+    return '\nStopped. Progress is saved, run the same command again to continue.\n'
   }
 
   if (command === 'restore') {
-    return '\nĐã dừng. Chưa lưu tiến độ tải, chạy lại sẽ tải lại từ đầu.\n'
+    return '\nStopped. Download progress is not saved, running again starts over.\n'
   }
 
-  return '\nĐã dừng.\n'
+  return '\nStopped.\n'
 }
 
 process.on('SIGINT', () => {
@@ -34,7 +37,7 @@ async function main() {
   try {
     parsed = route(process.argv.slice(2))
   } catch (err) {
-    process.stderr.write(`Lỗi: ${err.message}\n\n${HELP}`)
+    process.stderr.write(`Error: ${err.message}\n\n${HELP}`)
     process.exitCode = 2
     return
   }
@@ -47,37 +50,49 @@ async function main() {
       return
 
     case 'login':
-      await runLogin()
+      await runLogin({ verbose: parsed.options.verbose })
       return
 
     case 'logout':
       await runLogout()
       return
 
+    case 'list':
+      await runList(parsed.options)
+      return
+
+    case 'status':
+      await runStatus(parsed.options)
+      return
+
+    case 'set-destination':
+      await runSetDestination(parsed.options)
+      return
+
     case 'upload':
       await runUpload(parsed.args[0], parsed.options)
       return
 
     case 'restore':
       if (!parsed.args[0]) {
-        throw new Error('Thiếu backup id. Ví dụ: npx data-ark restore ark-20260905-7f3a91')
+        throw new Error('Missing backup id. Example: npx data-ark restore ark-20260905-7f3a91')
       }
       await runRestore(parsed.args[0], parsed.options)
       return
 
     default:
-      throw new Error(`Lệnh không nhận ra: ${parsed.command}`)
+      throw new Error(`Unknown command: ${parsed.command}`)
   }
 }
 
-// GramJS giữ lại các "exported sender" cùng một timer 30 giây để giải phóng
-// chúng, và client.disconnect()/destroy() không dọn nổi: cả hai map đó là Map
-// nhưng code duyệt bằng Object.values nên bỏ sót sạch. Hệ quả: lệnh in "Xong"
-// rồi vẫn treo thêm ~30 giây, và Ctrl-C trong khoảng đó lại báo sai rằng chưa
-// lưu được gì. Chạy xong việc là thoát hẳn, không nấn ná.
+// GramJS keeps "exported senders" around together with a 30-second timer to release
+// them, and neither client.disconnect() nor destroy() cleans them up: both of those
+// maps are Maps, but the code walks them with Object.values and so misses everything.
+// The result is a command that prints "Done" and then hangs for another ~30 seconds,
+// during which Ctrl-C falsely reports that nothing was saved. Finish the work, exit.
 function exitWhenFlushed(code) {
-  // Ghi rỗng chỉ để mượn callback: nó chạy sau khi mọi thứ xếp hàng trước đó đã
-  // xả xuống pipe, nên không mất chữ nào khi stdout/stderr không phải TTY.
+  // The empty writes exist only to borrow their callbacks: they fire after everything
+  // queued earlier has flushed, so nothing is lost when stdout/stderr is not a TTY.
   let pending = 2
 
   const done = () => {
@@ -85,7 +100,7 @@ function exitWhenFlushed(code) {
     if (pending === 0) process.exit(code)
   }
 
-  // Lưới an toàn: nếu callback không bao giờ tới (pipe đã đóng) thì vẫn thoát.
+  // Safety net: exit anyway if a callback never arrives (the pipe is already closed).
   setTimeout(() => process.exit(code), 2000).unref()
 
   process.stdout.write('', done)
@@ -97,7 +112,7 @@ main().then(
     exitWhenFlushed(process.exitCode ?? 0)
   },
   (err) => {
-    process.stderr.write(`Lỗi: ${err.message}\n`)
+    process.stderr.write(`Error: ${err.message}\n`)
     process.exitCode = 1
     exitWhenFlushed(1)
   },

package/package.json

@@ -1,9 +1,27 @@
 {
   "name": "data-ark",
-  "version": "0.1.0",
-  "description": "Cắt file lớn thành chunk và lưu trữ trên Telegram",
+  "version": "0.1.2",
+  "description": "Split large files into chunks and store them on Telegram",
+  "keywords": [
+    "telegram",
+    "backup",
+    "chunk",
+    "split",
+    "restore",
+    "cli",
+    "mtproto"
+  ],
+  "homepage": "https://github.com/shovity/data-ark#readme",
+  "bugs": {
+    "url": "https://github.com/shovity/data-ark/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shovity/data-ark.git"
+  },
   "type": "module",
   "license": "MIT",
+  "author": "shovity",
   "bin": {
     "data-ark": "bin/data-ark.js"
   },

package/src/caption.js

@@ -0,0 +1,63 @@
+import { formatBytes } from './progress.js'
+
+// Captions are plain text on purpose. Telegram would render bold through a parse mode,
+// but that turns every file name into something that has to be escaped correctly, and
+// the fake client the tests talk to would never notice a mistake there.
+
+const DIVIDER = '━'.repeat(15)
+
+// The hashtag is what `list` searches for, and it lives on the manifest alone: chunk
+// captions stay out of that search so a twelve-chunk backup is one hit, not thirteen.
+export const MANIFEST_TAG = '#dataark'
+
+// A file name may legally contain a newline or a tab, and either one would push the
+// rest of the card down a row and take its shape apart.
+function oneLine(name) {
+  return String(name).replace(/\s+/g, ' ').trim()
+}
+
+function utcMinutes(createdAt) {
+  return `${new Date(createdAt).toISOString().slice(0, 16).replace('T', ' ')} UTC`
+}
+
+export function chunkCaption({ id, number, total }) {
+  return `📦 ${id} · ${number}/${total}`
+}
+
+export function manifestCaption({ id, name, size, chunks, createdAt }) {
+  return [
+    `🗄 ${oneLine(name)}`,
+    DIVIDER,
+    `💾 ${formatBytes(size)} · ${chunks} chunk${chunks === 1 ? '' : 's'}`,
+    `🆔 ${id}`,
+    `📅 ${utcMinutes(createdAt)}`,
+    '',
+    `↩ npx data-ark restore ${id}`,
+    MANIFEST_TAG,
+  ].join('\n')
+}
+
+function marker(lines, emoji) {
+  const found = lines.find((line) => line.startsWith(`${emoji} `))
+  return found ? found.slice(emoji.length + 1).trim() : null
+}
+
+// list reads what the chat shows, and a caption is text a person can edit. Anything that
+// does not carry the whole card is reported as unknown rather than half-guessed: a backup
+// listed with invented numbers is worse than one listed with dashes.
+export function parseManifestCaption(text) {
+  const lines = String(text ?? '').split('\n')
+
+  const name = marker(lines, '🗄')
+  const totals = marker(lines, '💾')
+  const id = marker(lines, '🆔')
+  const createdAt = marker(lines, '📅')
+
+  if (!name || !totals || !id || !createdAt) return null
+
+  const match = /^(.+) · (\d+) chunks?$/.exec(totals)
+
+  if (!match) return null
+
+  return { id, name, size: match[1], chunks: Number(match[2]), createdAt }
+}

package/src/chunking.js

@@ -17,28 +17,34 @@ export function parseSize(input) {
   const match = text.match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/)
 
   if (!match) {
-    throw new Error(`Kích thước không hợp lệ: "${input}". Ví dụ hợp lệ: 1800MB, 1.8GB, 524288.`)
+    throw new Error(`Invalid size: "${input}". Valid examples: 1800MB, 1.8GB, 524288.`)
   }
 
   const bytes = Math.floor(Number(match[1]) * UNITS[match[2] ?? 'b'])
 
   if (bytes <= 0) {
-    throw new Error('Kích thước phải lớn hơn 0.')
+    throw new Error('Size must be greater than 0.')
   }
 
   if (bytes > MAX_CHUNK_SIZE) {
     throw new Error(
-      'Chunk tối đa là 1950MB. Telegram chỉ nhận 4000 phần 512KB cho mỗi file, ' +
-        'tức trần số học khoảng 1953MB, nên cần chừa biên an toàn.',
+      'Maximum chunk size is 1950MB. Telegram accepts only 4000 parts of 512KB per file, ' +
+        'an arithmetic ceiling of about 1953MB, so a safety margin is needed.',
     )
   }
 
   return bytes
 }
 
+// How many chunks a file of this size splits into. planChunks builds them and parseManifest
+// checks them against this same rule, so the layout has one definition, not three.
+export function countChunks(fileSize, chunkSize) {
+  return Math.ceil(fileSize / chunkSize)
+}
+
 export function planChunks(fileSize, chunkSize) {
   if (fileSize <= 0) {
-    throw new Error('File rỗng, không có gì để upload.')
+    throw new Error('File is empty, nothing to upload.')
   }
 
   const chunks = []

package/src/cli.js

@@ -1,40 +1,80 @@
 import { parseArgs } from 'node:util'
 
-const SUBCOMMANDS = new Set(['login', 'logout', 'restore', 'help'])
+const SUBCOMMANDS = new Set(['login', 'logout', 'list', 'restore', 'status', 'help'])
 
 const OPTIONS = {
   to: { type: 'string' },
   'chunk-size': { type: 'string' },
   concurrency: { type: 'string' },
   out: { type: 'string' },
+  limit: { type: 'string' },
+  verbose: { type: 'boolean' },
   help: { type: 'boolean', short: 'h' },
 }
 
-export const HELP = `data-ark — cắt file lớn thành chunk và lưu trữ trên Telegram
+export const HELP = `data-ark — split large files into chunks and store them on Telegram
 
-Cách dùng:
-  npx data-ark login                        Đăng nhập Telegram, chỉ cần chạy một lần
-  npx data-ark <file>                       Cắt file và đẩy lên Telegram
-  npx data-ark restore <backup-id>          Tải về và ghép lại file gốc
-  npx data-ark logout                       Xoá phiên đăng nhập đã lưu
+Usage:
+  npx data-ark login                        Log in to Telegram, only needed once
+  npx data-ark <file>                       Split a file and upload it to Telegram
+  npx data-ark list                         List the backups stored in the destination
+  npx data-ark restore <backup-id>          Download the chunks and reassemble the file
+  npx data-ark status                       Show the account, the destination and unfinished backups
+  npx data-ark --to <chat>                  Set the destination without uploading anything
+  npx data-ark logout                       Remove the saved session
 
-Tuỳ chọn:
-  --to <chat>            Đích lưu: @username, -100123..., hoặc me. Được ghi nhớ cho lần sau.
-  --chunk-size <n>       Kích thước mỗi chunk, mặc định 1800MB. Ví dụ: 1.8GB, 500MB.
-  --concurrency <n>      Số phần 512KB gửi song song, mặc định 8, tối đa 64.
-  --out <đường-dẫn>      Nơi ghi file khi restore. Mặc định lấy basename của tên trong manifest.
-  -h, --help             Hiện trợ giúp này.
+Options:
+  --to <chat>            Destination: @username, -100123..., or me. upload and status
+                         remember it; list and restore only look there.
+  --chunk-size <n>       Size of each chunk, default 1800MB. Examples: 1.8GB, 500MB.
+  --concurrency <n>      512KB parts sent in parallel, default 8, max 64.
+  --out <path>           Where to write the restored file. Defaults to the basename in the manifest.
+  --limit <n>            How many backups list shows, default 20.
+  --verbose              Show Telegram connection logs, hidden by default.
+  -h, --help             Show this help.
 `
 
+// A channel id is negative, and typing it separated by a space is the natural reflex —
+// but parseArgs rejects any value starting with a dash as ambiguous. Join the pair itself
+// so `--to -100123` works like `--to=-100123`. Only a bare negative integer qualifies, so
+// `--to --verbose` still reports the missing value instead of eating the next flag, and
+// everything after `--` is left alone because it is no longer an option there.
+function joinNegativeChatId(argv) {
+  const joined = []
+
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--') {
+      joined.push(...argv.slice(i))
+      return joined
+    }
+
+    if (argv[i] === '--to' && /^-\d+$/.test(argv[i + 1] ?? '')) {
+      joined.push(`--to=${argv[i + 1]}`)
+      i += 1
+      continue
+    }
+
+    joined.push(argv[i])
+  }
+
+  return joined
+}
+
 export function route(argv) {
   const { values, positionals } = parseArgs({
-    args: argv,
+    args: joinNegativeChatId(argv),
     options: OPTIONS,
     allowPositionals: true,
   })
 
   const [first, ...rest] = positionals
 
+  // `data-ark --to @chan` with no file is not a malformed upload, it is someone changing
+  // where the next upload goes. Help would be an unhelpful answer to a clear request.
+  if (first === undefined && values.to && !values.help) {
+    return { command: 'set-destination', args: [], options: values }
+  }
+
   if (values.help || first === undefined || first === 'help') {
     return { command: 'help', args: [], options: values }
   }

package/src/client.js

@@ -1,11 +1,21 @@
-import { TelegramClient } from 'telegram'
+import { Api, TelegramClient } from 'telegram'
+import { Logger } from 'telegram/extensions/index.js'
+import { LogLevel } from 'telegram/extensions/Logger.js'
 import { StringSession } from 'telegram/sessions/index.js'
 
+// GramJS narrates its version, every connection and every disconnect at info level, and
+// those timestamped lines land in the middle of the progress bar. The client reads this
+// logger before it prints anything, so LogLevel.NONE silences all of it; --verbose asks
+// for the running commentary back when a connection needs diagnosing.
+export function createLogger(verbose) {
+  return new Logger(verbose ? LogLevel.INFO : LogLevel.NONE)
+}
+
 export function normalizeChatTarget(input) {
   const text = String(input).trim()
 
   if (text === '') {
-    throw new Error('Đích lưu không được để rỗng.')
+    throw new Error('Destination must not be empty.')
   }
 
   if (/^-?\d+$/.test(text)) {
@@ -15,13 +25,78 @@ export function normalizeChatTarget(input) {
   return text
 }
 
+// Telegram's web client addresses a chat by putting the raw target in the fragment, which
+// covers both a negative channel id and an @username. Saved Messages is the exception: it
+// is reached by the account's own id, which data-ark does not know, so it gets no link
+// rather than a guessed one that lands somewhere else.
+export function chatUrl(chat) {
+  const text = String(chat)
+
+  if (text === 'me') return null
+
+  return `https://web.telegram.org/k/#${text}`
+}
+
+// How a destination is spoken about. "me" is a target, not a name someone would recognise
+// in a sentence, so every command that mentions a chat in prose goes through here.
+export function chatName(chat) {
+  return String(chat) === 'me' ? 'Saved Messages' : String(chat)
+}
+
+// A destination is worth more as something clickable than as a raw id, but Saved Messages
+// has no link to give, so it is named instead of being dressed up as one.
+export function describeChat(chat) {
+  const url = chatUrl(chat)
+
+  return url ?? `${chat} (${chatName(chat)})`
+}
+
+// The name Telegram shows under a document lives in an attribute, not on the message.
+export function documentFileName(message) {
+  const attributes = message?.media?.document?.attributes ?? []
+  const named = attributes.find((a) => a instanceof Api.DocumentAttributeFilename)
+  return named?.fileName ?? null
+}
+
+// The one place data-ark searches a chat. Both callers want documents and nothing else,
+// and getMessages is preferred over a raw Api.messages.Search because it handles offsets,
+// hashes and pagination itself, so we don't hand-build easily mistyped fields. The raw
+// message is kept alongside the flat fields because downloading needs it whole.
+export async function searchDocuments(client, peer, { search, limit }) {
+  const messages = await client.getMessages(peer, {
+    search,
+    filter: new Api.InputMessagesFilterDocument(),
+    limit,
+  })
+
+  return messages.map((message) => ({
+    id: message.id,
+    fileName: documentFileName(message),
+    caption: message.message ?? '',
+    date: message.date,
+    message,
+  }))
+}
+
+// Every command ends by putting the connection down, and a failure there must never
+// swallow the real error already on its way up. Commands that print progress hand in an
+// onWarn to say so; the quieter ones let it pass, because a connection that will not
+// close cleanly says nothing about the work that already succeeded.
+export async function closeQuietly(client, disconnect, onWarn) {
+  try {
+    await disconnect(client)
+  } catch (err) {
+    if (onWarn) onWarn(err)
+  }
+}
+
 export function requireChat(options, config) {
   const raw = options.to ?? config.defaultChat
 
   if (!raw) {
     throw new Error(
-      'Chưa có đích lưu — chạy lại với --to @kho_backup (hoặc --to me để dùng Saved Messages). ' +
-        'Lần sau data-ark sẽ tự nhớ.',
+      'No destination set — run again with --to @my_backups (or --to me for Saved Messages). ' +
+        'data-ark will remember it next time.',
     )
   }
 
@@ -30,22 +105,23 @@ export function requireChat(options, config) {
 
 export function assertLoggedIn(config) {
   if (!config.session || !config.apiId || !config.apiHash) {
-    throw new Error('Chưa đăng nhập — chạy "npx data-ark login" trước.')
+    throw new Error('Not logged in — run "npx data-ark login" first.')
   }
 }
 
-export async function connect(config) {
+export async function connect(config, { verbose = false } = {}) {
   assertLoggedIn(config)
 
   const client = new TelegramClient(new StringSession(config.session), config.apiId, config.apiHash, {
     connectionRetries: 5,
     floodSleepThreshold: 60,
+    baseLogger: createLogger(verbose),
   })
 
   await client.connect()
 
   if (!(await client.isUserAuthorized())) {
-    throw new Error('Phiên đăng nhập đã hết hạn — chạy "npx data-ark login".')
+    throw new Error('Session expired — run "npx data-ark login".')
   }
 
   return client