Add Telegram MVP UX flow and HF health compatibility

.env.example

@@ -45,9 +45,11 @@ LLM_MODEL=gpt-4o-mini
 # Optional: YouTube URL for real-world archive smoke run
 POCKET_ARCHIVE_SMOKE_YOUTUBE_URL=https://www.youtube.com/watch?v=o053pv_qJVE&t=4274s
 
-# Telegram placeholders (deferred in this patch)
+# Telegram bot integration
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_WEBHOOK_SECRET=
+# Optional: lock bot to one private owner chat
+TELEGRAM_ALLOWED_CHAT_ID=
 
 # Server
 PORT=8787

docs/pocket-archive-telegram-mvp.md

@@ -0,0 +1,89 @@
+# Pocket Archive Telegram MVP
+
+## Kur veikia Telegram backend
+
+Šis MVP Telegram sluoksnis skirtas **HF backend runtime** (`server.js`), ne Vercel serverless funkcijoms.
+
+Nauji endpointai:
+
+- `GET /api/telegram/health`
+- `POST /api/telegram/webhook/:secret`
+
+Webhook apsauga:
+
+- URL path secret turi sutapti su `TELEGRAM_WEBHOOK_SECRET`
+- jei Telegram siunčia `x-telegram-bot-api-secret-token`, jis irgi turi sutapti
+
+## Reikalingi env kintamieji
+
+- `TELEGRAM_BOT_TOKEN` - Telegram bot token
+- `TELEGRAM_WEBHOOK_SECRET` - webhook secret
+- `TELEGRAM_ALLOWED_CHAT_ID` - pasirenkama; jei nurodyta, tik šis chat gali naudoti botą
+- `MONGODB_URI`, `MONGODB_DB_NAME` - MongoDB Atlas/lokalus Mongo
+- `RAPIDAPI_KEY` - fallback transkripcijai, jei nėra YouTube captions
+- `LLM_PROVIDER`, `LLM_BASE_URL`, `LLM_API_KEY`, `LLM_MODEL` - normalize + Q&A
+
+## Webhook nustatymas
+
+1. Įsitikink, kad HF backend pasiekiamas per HTTPS (`HF_BACKEND_BASE_URL`).
+2. Paleisk:
+
+```bash
+npm run telegram:set-webhook
+```
+
+Skriptas sukonfigūruoja Telegram webhook į:
+
+`<HF_BACKEND_BASE_URL>/api/telegram/webhook/<TELEGRAM_WEBHOOK_SECRET>`
+
+## Ką moka botas
+
+- Priima YouTube URL (be komandos) ir paleidžia:
+  - `ingest -> normalize -> segment -> get`
+- Rodo vieną redaguojamą job-status žinutę:
+  - `Queued`
+  - `Transcribing`
+  - `Editing transcript`
+  - `Building summary and outline`
+  - `Saving artifacts`
+  - `Done`
+- Po rezultato rodo inline mygtukus:
+  - `Outline`
+  - `Edited`
+  - `Ask`
+  - `Save`
+  - `Topics`
+- Komandos:
+  - `/help`
+  - `/library`
+  - `/inbox`
+  - `/list [state]`
+  - `/get <video_key>`
+  - `/summary [video_key]`
+  - `/outline [video_key]`
+  - `/topics [video_key]`
+  - `/edited [video_key]`
+  - `/md [video_key]`
+  - `/ask [video_key] <klausimas>`
+  - `/save [video_key] [category]`
+  - `/discard [video_key]`
+  - `/category [video_key] <category>`
+  - `/categories`
+  - `/note [video_key] <tekstas>`
+  - `/rebuild <video_key|youtube_url>`
+
+## UX taisyklės
+
+- Idempotency pagal URL:
+  - jei video jau pilnai apdorotas ir `rebuild` neprašytas, botas grąžina esamą rezultatą ir nepaleidžia pilno pipeline iš naujo.
+- Kontekstas per user/chat session:
+  - botas prisimena `last_video_key`, paskutinį artifact rinkinį ir paskutinę kategoriją.
+- Dalinis rezultatas:
+  - jei dalis etapų nulūžta, bet yra bent `summary` ar `edited`, botas grąžina turimą rezultatą su aiškia klaidos pastaba.
+
+## Pastabos
+
+- Botas naudoja esamus `services/archive/*` modulius, todėl Telegram ir Web dirba su tais pačiais Mongo įrašais.
+- `raw` transcript lieka source-of-truth.
+- `summary/outline/edited` gaunami iš `video_texts` artefaktų.
+- Ilgi tekstai Telegram’e siunčiami dalimis arba `.md` dokumentu.

lib/config.js

@@ -50,5 +50,6 @@ export function getConfig() {
     ownerLoginPassword: String(process.env.OWNER_LOGIN_PASSWORD || '').trim(),
     telegramBotToken: String(process.env.TELEGRAM_BOT_TOKEN || '').trim(),
     telegramWebhookSecret: String(process.env.TELEGRAM_WEBHOOK_SECRET || '').trim(),
+    telegramAllowedChatId: String(process.env.TELEGRAM_ALLOWED_CHAT_ID || '').trim(),
   };
 }

package.json

@@ -10,6 +10,7 @@
     "test": "playwright test",
     "test:archive-api": "node --test tests/api/archive-api.contract.test.js",
     "smoke:youtube": "node scripts/pocket-archive-youtube-smoke.js",
+    "telegram:set-webhook": "node scripts/telegram-set-webhook.js",
     "archive:export-md": "node scripts/export-archive-markdown.js",
     "mongo:init": "node scripts/init-mongo.js",
     "mongo:up": "docker compose -f docker/docker-compose.mongo.yml up -d",

scripts/telegram-set-webhook.js

@@ -0,0 +1,51 @@
+import 'dotenv/config';
+
+function required(name) {
+  const value = String(process.env[name] || '').trim();
+  if (!value) {
+    throw new Error(`${name} is required`);
+  }
+  return value;
+}
+
+async function main() {
+  const token = required('TELEGRAM_BOT_TOKEN');
+  const secret = required('TELEGRAM_WEBHOOK_SECRET');
+  const baseUrl = required('HF_BACKEND_BASE_URL').replace(/\/+$/, '');
+  const webhookUrl = `${baseUrl}/api/telegram/webhook/${secret}`;
+
+  const response = await fetch(`https://api.telegram.org/bot${token}/setWebhook`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      url: webhookUrl,
+      secret_token: secret,
+      drop_pending_updates: false,
+      allowed_updates: ['message', 'edited_message'],
+    }),
+  });
+
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok || payload?.ok === false) {
+    throw new Error(payload?.description || `setWebhook failed (${response.status})`);
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        webhook_url: webhookUrl,
+        telegram_result: payload.result || true,
+      },
+      null,
+      2
+    )
+  );
+}
+
+main().catch((error) => {
+  console.error('Failed to set Telegram webhook:', error?.message || String(error));
+  process.exit(1);
+});

server.js

@@ -6,6 +6,8 @@ import { put } from '@vercel/blob';
 import { getSubtitles } from 'youtube-caption-extractor';
 import blobUploadTokenHandler from './api/blob-upload-token.js';
 import hfPostTranscribeHandler from './api/hf/post-transcribe.js';
+import { getConfig } from './lib/config.js';
+import { handleTelegramUpdate } from './services/telegram/bot.js';
 
 dotenv.config();
 
@@ -24,6 +26,32 @@ app.get('/healthz', (_req, res) => {
   return res.status(200).json({ ok: true });
 });
 
+// Compatibility health route for platforms that probe /health.
+app.get('/health', (_req, res) => {
+  return res.status(200).json({ ok: true });
+});
+
+function isTelegramRequestAuthorized(req) {
+  const cfg = getConfig();
+  const expectedSecret = String(cfg.telegramWebhookSecret || '').trim();
+  if (!expectedSecret) {
+    return { ok: false, reason: 'TELEGRAM_WEBHOOK_SECRET is not configured' };
+  }
+
+  const pathSecret = String(req.params?.secret || '').trim();
+  const headerSecret = String(req.headers['x-telegram-bot-api-secret-token'] || '').trim();
+
+  if (pathSecret !== expectedSecret) {
+    return { ok: false, reason: 'webhook path secret mismatch' };
+  }
+
+  if (headerSecret && headerSecret !== expectedSecret) {
+    return { ok: false, reason: 'telegram secret header mismatch' };
+  }
+
+  return { ok: true };
+}
+
 // Supabase configuration
 const SUPABASE_URL = process.env.SUPABASE_URL || process.env.VITE_SUPABASE_URL;
 const SUPABASE_ANON_KEY = process.env.SUPABASE_ANON_KEY || process.env.VITE_SUPABASE_ANON_KEY;
@@ -208,6 +236,36 @@ app.post('/api/hf/post-transcribe', async (req, res) => {
   return hfPostTranscribeHandler(req, res);
 });
 
+// Telegram webhook is intended for HF/container runtime.
+// It acknowledges immediately and processes in background because
+// archive workflow can run longer than a normal webhook request.
+app.get('/api/telegram/health', (_req, res) => {
+  const cfg = getConfig();
+  return res.status(200).json({
+    ok: true,
+    telegram_configured: Boolean(cfg.telegramBotToken && cfg.telegramWebhookSecret),
+  });
+});
+
+app.post('/api/telegram/webhook/:secret', async (req, res) => {
+  const auth = isTelegramRequestAuthorized(req);
+  if (!auth.ok) {
+    return res.status(401).json({
+      message: 'Unauthorized Telegram webhook request',
+      reason: auth.reason,
+    });
+  }
+
+  const update = req.body || {};
+  res.status(200).json({ ok: true });
+
+  setImmediate(() => {
+    handleTelegramUpdate(update).catch((error) => {
+      console.error('[telegram-webhook] update handling failed:', error);
+    });
+  });
+});
+
 // GET /api/me/remaining - returns { used, remaining }
 app.get('/api/me/remaining', requireAuth, async (req, res) => {
   try {
@@ -461,6 +519,6 @@ app.put('/api/blob-upload', express.raw({ type: '*/*', limit: '200mb' }), async
   }
 });
 
-app.listen(PORT, () => {
-  console.log(`Backend listening on http://localhost:${PORT}`);
+app.listen(PORT, '0.0.0.0', () => {
+  console.log(`Backend listening on http://0.0.0.0:${PORT}`);
 });

services/archive/list-categories.js

@@ -0,0 +1,50 @@
+import { getMongoDb } from '../../lib/mongo.js';
+import { ensureArchiveDb } from '../../db/indexes.js';
+import { COLLECTIONS } from '../../db/collections.js';
+
+export async function listArchiveCategories() {
+  const db = await getMongoDb();
+  await ensureArchiveDb(db);
+
+  const videos = db.collection(COLLECTIONS.videos);
+  const rows = await videos
+    .aggregate([
+      {
+        $match: {
+          subscription_topic: { $type: 'string' },
+        },
+      },
+      {
+        $project: {
+          subscription_topic: { $trim: { input: '$subscription_topic' } },
+        },
+      },
+      {
+        $match: {
+          subscription_topic: { $ne: '' },
+        },
+      },
+      {
+        $group: {
+          _id: '$subscription_topic',
+          count: { $sum: 1 },
+        },
+      },
+      {
+        $project: {
+          _id: 0,
+          category: '$_id',
+          count: 1,
+        },
+      },
+      {
+        $sort: {
+          count: -1,
+          category: 1,
+        },
+      },
+    ])
+    .toArray();
+
+  return rows;
+}

services/archive/normalize-video.js

@@ -14,7 +14,15 @@ function appendRun(existingRuns, nextRun) {
   return [...rows, nextRun].slice(-10);
 }
 
-export async function normalizeVideoByKey(videoKey, { targetLanguage = null, outlineProvider = null } = {}) {
+async function reportProgress(onProgress, stage, meta = {}) {
+  if (typeof onProgress !== 'function') return;
+  await onProgress(stage, meta);
+}
+
+export async function normalizeVideoByKey(
+  videoKey,
+  { targetLanguage = null, outlineProvider = null, onProgress = null } = {}
+) {
   const key = String(videoKey || '').trim();
   if (!key) {
     const error = new Error('video_key is required');
@@ -46,12 +54,19 @@ export async function normalizeVideoByKey(videoKey, { targetLanguage = null, out
   const cleaned = cleanupTranscript(textDoc.content_raw);
 
   try {
+    await reportProgress(onProgress, 'editing_transcript', {
+      video_key: key,
+    });
     const literary = await literaryNormalize(cleaned);
     const inferredLanguage = inferLanguageFromText(literary.content, {
       fallback: textDoc.language || video.language_original || 'en',
     });
     const resolvedLanguage = normalizeLanguageCode(targetLanguage) || inferredLanguage;
 
+    await reportProgress(onProgress, 'building_summary_outline', {
+      video_key: key,
+      language: resolvedLanguage,
+    });
     const topicMemory = await extractTopicMap({
       editedTranscript: literary.content,
       video: {
@@ -160,6 +175,9 @@ export async function normalizeVideoByKey(videoKey, { targetLanguage = null, out
       }
     );
 
+    await reportProgress(onProgress, 'saving_artifacts', {
+      video_key: key,
+    });
     await texts.updateOne(
       { _id: textDoc._id },
       {

services/archive/set-video-category.js

@@ -0,0 +1,54 @@
+import { ObjectId } from 'mongodb';
+import { getMongoDb } from '../../lib/mongo.js';
+import { ensureArchiveDb } from '../../db/indexes.js';
+import { COLLECTIONS } from '../../db/collections.js';
+
+export async function setVideoCategory({ videoKey, category = null, actor = 'telegram-owner' } = {}) {
+  const key = String(videoKey || '').trim();
+  if (!key) {
+    const error = new Error('video_key is required');
+    error.status = 400;
+    throw error;
+  }
+
+  const normalizedCategory = category == null ? null : String(category).trim();
+
+  const db = await getMongoDb();
+  await ensureArchiveDb(db);
+
+  const videos = db.collection(COLLECTIONS.videos);
+  const actions = db.collection(COLLECTIONS.reviewActions);
+
+  const video = await videos.findOne({ video_key: key });
+  if (!video) {
+    const error = new Error('Video not found');
+    error.status = 404;
+    throw error;
+  }
+
+  const now = new Date();
+  await videos.updateOne(
+    { _id: video._id },
+    {
+      $set: {
+        subscription_topic: normalizedCategory || null,
+        updated_at: now,
+      },
+    }
+  );
+
+  await actions.insertOne({
+    _id: new ObjectId(),
+    video_id: video._id,
+    video_key: key,
+    action: normalizedCategory ? 'set-category' : 'clear-category',
+    actor: String(actor || 'telegram-owner'),
+    note: normalizedCategory || null,
+    created_at: now,
+  });
+
+  return {
+    video_key: key,
+    subscription_topic: normalizedCategory || null,
+  };
+}

services/telegram/bot.js

@@ -0,0 +1,1514 @@
+import { getConfig } from '../../lib/config.js';
+import { logger } from '../../lib/logger.js';
+import { generateText } from '../../lib/llm-provider.js';
+import { ingestVideo } from '../archive/ingest-video.js';
+import { normalizeVideoByKey } from '../archive/normalize-video.js';
+import { segmentVideoByKey } from '../archive/segment-video.js';
+import { getVideoByKey } from '../archive/get-video.js';
+import { listVideos } from '../archive/list-videos.js';
+import { setReviewState } from '../archive/review-video.js';
+import { addEditorialNote } from '../archive/add-note.js';
+import { setVideoCategory } from '../archive/set-video-category.js';
+import { listArchiveCategories } from '../archive/list-categories.js';
+import {
+  buildTelegramResponsePayload,
+  buildUserFacingArtifact,
+  renderUserFacingMarkdown,
+} from '../archive/user-facing-artifacts.js';
+import {
+  answerTelegramCallbackQuery,
+  editTelegramText,
+  sendTelegramChatAction,
+  sendTelegramDocument,
+  sendTelegramText,
+} from './telegram-client.js';
+
+const REVIEW_STATES = new Set(['inbox', 'reviewed', 'saved', 'discarded', 'publication-candidate']);
+const sessionStore = new Map();
+
+const STATUS_STEPS = [
+  'queued',
+  'transcribing',
+  'editing_transcript',
+  'building_summary_outline',
+  'saving_artifacts',
+  'done',
+];
+
+function sessionKey(chatId, userId) {
+  return `${String(chatId)}:${String(userId || chatId)}`;
+}
+
+function getSession(chatId, userId) {
+  const key = sessionKey(chatId, userId);
+  if (!sessionStore.has(key)) {
+    sessionStore.set(key, {
+      lastVideoKey: '',
+      lastArtifacts: null,
+      lastCategory: null,
+      recentCategories: [],
+      categoryOptionsByVideo: {},
+      topicOptionsByVideo: {},
+    });
+  }
+
+  if (sessionStore.size > 5000) {
+    const first = sessionStore.keys().next().value;
+    if (first) sessionStore.delete(first);
+  }
+
+  return sessionStore.get(key);
+}
+
+function extractMessage(update) {
+  return update?.message || update?.edited_message || null;
+}
+
+function extractCallbackQuery(update) {
+  return update?.callback_query || null;
+}
+
+function extractYouTubeUrl(text) {
+  const value = String(text || '');
+  const match = value.match(/https?:\/\/(?:www\.)?(?:youtube\.com\/watch\?[^\s]+|youtu\.be\/[^\s]+)/i);
+  return match ? match[0] : null;
+}
+
+function parseCommand(text) {
+  const value = String(text || '').trim();
+  if (!value.startsWith('/')) return null;
+
+  const parts = value.split(/\s+/);
+  const first = parts.shift() || '';
+  const [commandRaw] = first.slice(1).split('@');
+  const command = String(commandRaw || '').trim().toLowerCase();
+  return {
+    command,
+    args: parts,
+    argsText: parts.join(' ').trim(),
+  };
+}
+
+function truncateText(text, max = 120) {
+  const value = String(text || '').replace(/\s+/g, ' ').trim();
+  if (value.length <= max) return value;
+  return `${value.slice(0, Math.max(0, max - 1)).trimEnd()}...`;
+}
+
+function resolveVideoKey(session, explicitKey) {
+  const key = String(explicitKey || '').trim();
+  if (key) return key;
+  return String(session?.lastVideoKey || '').trim();
+}
+
+function rememberCategory(session, category) {
+  const normalized = String(category || '').trim();
+  if (!normalized) return;
+  session.lastCategory = normalized;
+  session.recentCategories = [normalized, ...(session.recentCategories || []).filter((item) => item !== normalized)].slice(
+    0,
+    8
+  );
+}
+
+function rememberVideo(session, archiveItem) {
+  const videoKey = String(archiveItem?.video?.video_key || '').trim();
+  if (!videoKey) return;
+
+  session.lastVideoKey = videoKey;
+  if (archiveItem?.video?.subscription_topic) {
+    rememberCategory(session, archiveItem.video.subscription_topic);
+  }
+
+  const text = archiveItem?.video_text || {};
+  session.lastArtifacts = {
+    video_key: videoKey,
+    has_summary: Boolean(String(text.content_summary_1p || '').trim()),
+    has_outline: Boolean(String(text.content_outline_thematic || '').trim()),
+    has_edited: Boolean(String(text.content_literary || '').trim()),
+    has_topic_map: Array.isArray(text?.content_topic_map?.topics) && text.content_topic_map.topics.length > 0,
+    updated_at: new Date().toISOString(),
+  };
+}
+
+function buildHelpText() {
+  return [
+    'Pocket Archive Telegram komandos:',
+    '/library - vienas vaizdas: recent + categories',
+    '/inbox - naujausi inbox irasai',
+    '/list [state] - sarasas (pvz. /list saved)',
+    '/get <video_key> - summary + veiksmai',
+    '/summary [video_key] - tik summary',
+    '/outline [video_key] - thematic outline',
+    '/topics [video_key] - temos su mygtukais',
+    '/edited [video_key] - edited transcript MD failas',
+    '/md [video_key] - master MD failas',
+    '/ask [video_key] <klausimas> - klausimai apie irasa',
+    '/save [video_key] [category] - save + kategorija',
+    '/discard [video_key] - discard',
+    '/category [video_key] <category> - nustatyti kategorija',
+    '/categories - kategoriju sarasas',
+    '/note [video_key] <tekstas> - prideti pastaba',
+    '/rebuild <video_key|youtube_url> - priverstinai pergen.',
+    '',
+    'Taip pat gali tiesiog atsiusti YouTube URL.',
+  ].join('\n');
+}
+
+function buildMainActionsKeyboard(videoKey) {
+  return {
+    inline_keyboard: [
+      [
+        { text: 'Outline', callback_data: `a|out|${videoKey}` },
+        { text: 'Edited', callback_data: `a|ed|${videoKey}` },
+      ],
+      [
+        { text: 'Ask', callback_data: `a|ask|${videoKey}` },
+        { text: 'Save', callback_data: `a|save|${videoKey}` },
+        { text: 'Topics', callback_data: `a|topics|${videoKey}` },
+      ],
+    ],
+  };
+}
+
+function composeJobStatusText(currentStage, note = '') {
+  const currentIndex = STATUS_STEPS.indexOf(currentStage);
+  const effectiveIndex = currentIndex === -1 ? 0 : currentIndex;
+
+  const lines = ['Job status'];
+  const labels = [
+    ['queued', 'Queued'],
+    ['transcribing', 'Transcribing'],
+    ['editing_transcript', 'Editing transcript'],
+    ['building_summary_outline', 'Building summary and outline'],
+    ['saving_artifacts', 'Saving artifacts'],
+    ['done', 'Done'],
+  ];
+
+  for (let index = 0; index < labels.length; index += 1) {
+    const [stepKey, stepLabel] = labels[index];
+    const statusMark = index < effectiveIndex ? 'x' : index === effectiveIndex ? '...' : '-';
+    lines.push(`${statusMark} ${stepLabel}`);
+    if (stepKey === currentStage && note) {
+      lines.push(`   ${note}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+async function startJobStatus({ cfg, chatId, replyToMessageId = null }) {
+  const sent = await sendTelegramText({
+    botToken: cfg.telegramBotToken,
+    chatId,
+    replyToMessageId,
+    text: composeJobStatusText('queued'),
+  });
+
+  const first = Array.isArray(sent) && sent.length > 0 ? sent[0] : null;
+  return {
+    chatId,
+    messageId: first?.message_id || null,
+    currentStage: 'queued',
+  };
+}
+
+async function updateJobStatus({ cfg, jobStatus, stage, note = '' }) {
+  if (!jobStatus?.messageId) return;
+  if (jobStatus.currentStage === stage && !note) return;
+
+  const text = composeJobStatusText(stage, note);
+  await editTelegramText({
+    botToken: cfg.telegramBotToken,
+    chatId: jobStatus.chatId,
+    messageId: jobStatus.messageId,
+    text,
+  });
+
+  jobStatus.currentStage = stage;
+}
+
+function buildEditedMd(archiveItem) {
+  const artifact = buildUserFacingArtifact(
+    {
+      video: archiveItem.video,
+      videoText: archiveItem.video_text,
+    },
+    { includeEdited: true }
+  );
+  const title = archiveItem.video?.title_original || archiveItem.video?.video_key || 'Archive Item';
+  return `# ${title}\n\n## Edited Transcript\n\n${artifact.content_edited || '_Edited transcript not available yet._'}\n`;
+}
+
+function collectTopicButtons(session, videoKey, archiveItem) {
+  const topics = Array.isArray(archiveItem?.video_text?.content_topic_map?.topics)
+    ? archiveItem.video_text.content_topic_map.topics
+    : [];
+
+  if (topics.length === 0) {
+    session.topicOptionsByVideo[videoKey] = [];
+    return {
+      keyboard: null,
+      count: 0,
+    };
+  }
+
+  const maxTopics = Math.min(10, topics.length);
+  const options = [];
+  const rows = [];
+
+  for (let index = 0; index < maxTopics; index += 1) {
+    const topic = topics[index];
+    options.push({
+      topic_id: topic?.topic_id || `t${index + 1}`,
+      label: topic?.label || `Topic ${index + 1}`,
+    });
+    rows.push([
+      {
+        text: truncateText(topic?.label || `Topic ${index + 1}`, 36),
+        callback_data: `t|${videoKey}|${index}`,
+      },
+    ]);
+  }
+
+  session.topicOptionsByVideo[videoKey] = options;
+  return {
+    keyboard: {
+      inline_keyboard: rows,
+    },
+    count: options.length,
+  };
+}
+
+function buildCategoryKeyboard(session, videoKey, globalCategories = []) {
+  const fromSession = Array.isArray(session.recentCategories) ? session.recentCategories : [];
+  const fromGlobal = Array.isArray(globalCategories)
+    ? globalCategories.map((item) => String(item?.category || '').trim()).filter(Boolean)
+    : [];
+
+  const merged = [...new Set([...fromSession, ...fromGlobal])].slice(0, 6);
+  session.categoryOptionsByVideo[videoKey] = merged;
+
+  const rows = merged.map((category, index) => [
+    {
+      text: truncateText(category, 30),
+      callback_data: `c|${videoKey}|${index}`,
+    },
+  ]);
+
+  rows.push([
+    {
+      text: 'New category',
+      callback_data: `c|${videoKey}|new`,
+    },
+  ]);
+
+  return {
+    inline_keyboard: rows,
+  };
+}
+
+async function sendSummaryResult({
+  cfg,
+  chatId,
+  archiveItem,
+  session,
+  replyToMessageId = null,
+  note = '',
+  includeKeyboard = true,
+}) {
+  rememberVideo(session, archiveItem);
+
+  const payload = buildTelegramResponsePayload(
+    {
+      video: archiveItem.video,
+      videoText: archiveItem.video_text,
+    },
+    {
+      includeEdited: false,
+      editedCommand: `/edited ${archiveItem.video.video_key}`,
+    }
+  );
+
+  const title = payload?.title || archiveItem.video.video_key;
+  const summary = payload?.content_summary_1p || 'Summary dar neparuostas. Pabandyk /rebuild.';
+
+  const lines = [title, '', 'Summary:', summary];
+  if (note) {
+    lines.push('', note);
+  }
+
+  await sendTelegramText({
+    botToken: cfg.telegramBotToken,
+    chatId,
+    replyToMessageId,
+    text: lines.join('\n'),
+    replyMarkup: includeKeyboard ? buildMainActionsKeyboard(archiveItem.video.video_key) : null,
+  });
+}
+
+async function sendOutlineText({ cfg, chatId, archiveItem }) {
+  const outline = buildUserFacingArtifact({
+    video: archiveItem.video,
+    videoText: archiveItem.video_text,
+  }).content_outline_thematic;
+
+  await sendTelegramText({
+    botToken: cfg.telegramBotToken,
+    chatId,
+    text: outline || 'Outline dar nera. Paleisk /rebuild.',
+  });
+}
+
+function formatTopicDetail(topic) {
+  const lines = [topic?.label || 'Theme'];
+  if (topic?.thesis) {
+    lines.push('', `Thesis: ${String(topic.thesis).trim()}`);
+  }
+  if (topic?.micro_summary) {
+    lines.push('', String(topic.micro_summary).trim());
+  }
+  const points = Array.isArray(topic?.key_points) ? topic.key_points.filter(Boolean).slice(0, 6) : [];
+  if (points.length > 0) {
+    lines.push('', 'Key points:');
+    for (const point of points) {
+      lines.push(`- ${String(point).trim()}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function resolveTopicByIndex(session, archiveItem, videoKey, indexValue) {
+  const index = Number(indexValue);
+  if (!Number.isInteger(index) || index < 0) return null;
+
+  const topics = Array.isArray(archiveItem?.video_text?.content_topic_map?.topics)
+    ? archiveItem.video_text.content_topic_map.topics
+    : [];
+
+  const sessionOptions = Array.isArray(session.topicOptionsByVideo[videoKey]) ? session.topicOptionsByVideo[videoKey] : [];
+  if (sessionOptions[index]?.topic_id) {
+    const found = topics.find((topic) => String(topic?.topic_id || '') === String(sessionOptions[index].topic_id));
+    if (found) return found;
+  }
+
+  return topics[index] || null;
+}
+
+function extractSeqFromRef(ref) {
+  const value = String(ref || '');
+  const match = value.match(/(\d+)/);
+  if (!match) return null;
+  const seq = Number(match[1]);
+  return Number.isInteger(seq) ? seq : null;
+}
+
+function buildTopicEvidence(topic, segments) {
+  const refs = Array.isArray(topic?.segment_refs) ? topic.segment_refs : [];
+  if (refs.length === 0) {
+    return 'Evidence: segment refs not available for this topic.';
+  }
+
+  const wantedSeq = refs.map(extractSeqFromRef).filter((value) => Number.isInteger(value));
+  if (wantedSeq.length === 0) {
+    return 'Evidence: segment refs are not mappable to segment sequence.';
+  }
+
+  const segmentMap = new Map((Array.isArray(segments) ? segments : []).map((segment) => [segment.seq, segment]));
+  const picked = wantedSeq
+    .map((seq) => segmentMap.get(seq))
+    .filter(Boolean)
+    .slice(0, 4)
+    .map((segment) => `- [${segment.seq}] ${truncateText(segment.text, 240)}`);
+
+  if (picked.length === 0) {
+    return 'Evidence: referenced segments were not found in current segment set.';
+  }
+
+  return ['Evidence:', ...picked].join('\n');
+}
+
+function describePipelineError(stage, error, archiveItem = null) {
+  const message = String(error?.message || '').trim();
+  const lower = message.toLowerCase();
+
+  if (stage === 'transcribing') {
+    if (/youtube|caption|transcript|rapidapi|unavailable|forbidden|blocked|failed to fetch media/i.test(lower)) {
+      return 'Nepavyko pasiekti transkripcijos saltinio.';
+    }
+    return `Nepavyko gauti transkripcijos: ${message || 'nezinoma klaida'}`;
+  }
+
+  if (stage === 'building_summary_outline' || stage === 'editing_transcript') {
+    const hasSummary = Boolean(String(archiveItem?.video_text?.content_summary_1p || '').trim());
+    const hasOutline = Boolean(String(archiveItem?.video_text?.content_outline_thematic || '').trim());
+
+    if (hasSummary && !hasOutline) {
+      return 'Transkriptas gautas, bet outline sugeneruoti nepavyko.';
+    }
+    if (!hasSummary && hasOutline) {
+      return 'Transkriptas gautas, bet summary sugeneruoti nepavyko.';
+    }
+    return `Normalize etapas nepavyko: ${message || 'nezinoma klaida'}`;
+  }
+
+  if (stage === 'saving_artifacts') {
+    return `Artefaktu issaugojimas nepavyko: ${message || 'nezinoma klaida'}`;
+  }
+
+  return message || 'Nepavyko apdoroti uzduoties.';
+}
+
+async function answerQuestionAboutVideo({ question, archiveItem }) {
+  const video = archiveItem.video || {};
+  const text = archiveItem.video_text || {};
+  const promptContext = [
+    `Video key: ${video.video_key || ''}`,
+    `Title: ${video.title_original || ''}`,
+    `Source URL: ${video.source_url || ''}`,
+    '',
+    'Summary:',
+    text.content_summary_1p || '',
+    '',
+    'Thematic outline:',
+    text.content_outline_thematic || '',
+    '',
+    'Edited transcript excerpt:',
+    String(text.content_literary || '').slice(0, 14000),
+  ].join('\n');
+
+  const response = await generateText({
+    systemPrompt:
+      'You answer questions about one transcript source. ' +
+      'Use only provided context. Keep answer concise, plain language, and factual. ' +
+      'If context is insufficient, explicitly say what is missing.',
+    userPrompt: `Question: ${String(question || '').trim()}\n\nContext:\n${promptContext}`,
+    temperature: 0.15,
+    maxTokens: 900,
+  });
+
+  return response.text;
+}
+
+function hasCompletedArtifacts(archiveItem) {
+  const text = archiveItem?.video_text || {};
+  return Boolean(String(text.content_summary_1p || '').trim()) &&
+    Boolean(String(text.content_outline_thematic || '').trim()) &&
+    Boolean(String(text.content_literary || '').trim());
+}
+
+function hasSegments(archiveItem) {
+  return Array.isArray(archiveItem?.segments) && archiveItem.segments.length > 0;
+}
+
+async function runRebuildByVideoKey({ cfg, chatId, session, videoKey, replyToMessageId = null }) {
+  const key = String(videoKey || '').trim();
+  if (!key) {
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      text: 'Nurodyk video_key: /rebuild vid_xxx',
+    });
+    return true;
+  }
+
+  const jobStatus = await startJobStatus({ cfg, chatId, replyToMessageId });
+
+  try {
+    await normalizeVideoByKey(key, {
+      onProgress: async (stage) => {
+        await updateJobStatus({ cfg, jobStatus, stage });
+      },
+    });
+
+    await updateJobStatus({ cfg, jobStatus, stage: 'saving_artifacts' });
+    await segmentVideoByKey(key);
+
+    const archiveItem = await getVideoByKey(key);
+    if (!archiveItem) {
+      throw new Error('Archive item not found after rebuild');
+    }
+
+    rememberVideo(session, archiveItem);
+    await updateJobStatus({ cfg, jobStatus, stage: 'done' });
+    await sendSummaryResult({ cfg, chatId, session, archiveItem, note: 'Rebuild baigtas.' });
+    return true;
+  } catch (error) {
+    const archiveItem = await getVideoByKey(key).catch(() => null);
+    const note = describePipelineError(jobStatus.currentStage, error, archiveItem);
+    await updateJobStatus({ cfg, jobStatus, stage: 'done', note: 'Completed with warnings' });
+
+    if (archiveItem && (archiveItem.video_text?.content_summary_1p || archiveItem.video_text?.content_literary)) {
+      rememberVideo(session, archiveItem);
+      await sendSummaryResult({
+        cfg,
+        chatId,
+        session,
+        archiveItem,
+        note,
+      });
+    } else {
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: note,
+      });
+    }
+
+    logger.error('Telegram rebuild failed', {
+      stage: jobStatus.currentStage,
+      videoKey: key,
+      chatId: String(chatId),
+      message: error?.message || String(error),
+    });
+
+    return true;
+  }
+}
+
+async function runYoutubeWorkflow({
+  cfg,
+  chatId,
+  session,
+  sourceText,
+  replyToMessageId = null,
+  forceRebuild = false,
+}) {
+  const url = extractYouTubeUrl(sourceText);
+  if (!url) return false;
+
+  const jobStatus = await startJobStatus({ cfg, chatId, replyToMessageId });
+  let videoKey = '';
+
+  try {
+    await updateJobStatus({ cfg, jobStatus, stage: 'transcribing' });
+    await sendTelegramChatAction({ botToken: cfg.telegramBotToken, chatId, action: 'typing' });
+
+    const ingest = await ingestVideo({ url });
+    videoKey = ingest.video_key;
+
+    let archiveItem = await getVideoByKey(videoKey);
+    if (!archiveItem) {
+      throw new Error('Archive item not found after ingest');
+    }
+
+    rememberVideo(session, archiveItem);
+
+    const reusedAndComplete = Boolean(ingest.reused) && hasCompletedArtifacts(archiveItem) && hasSegments(archiveItem);
+    if (reusedAndComplete && !forceRebuild) {
+      await updateJobStatus({
+        cfg,
+        jobStatus,
+        stage: 'done',
+        note: 'Video already in library. Returned existing artifacts.',
+      });
+      await sendSummaryResult({
+        cfg,
+        chatId,
+        session,
+        archiveItem,
+        note: 'Video jau yra bibliotekoje. Grąžintas esamas rezultatas.',
+      });
+      return true;
+    }
+
+    const needNormalize =
+      forceRebuild ||
+      !Boolean(String(archiveItem?.video_text?.content_literary || '').trim()) ||
+      !Boolean(String(archiveItem?.video_text?.content_summary_1p || '').trim()) ||
+      !Boolean(String(archiveItem?.video_text?.content_outline_thematic || '').trim());
+
+    if (needNormalize) {
+      await normalizeVideoByKey(videoKey, {
+        onProgress: async (stage) => {
+          await updateJobStatus({ cfg, jobStatus, stage });
+        },
+      });
+    }
+
+    await updateJobStatus({ cfg, jobStatus, stage: 'saving_artifacts' });
+
+    const archiveAfterNormalize = await getVideoByKey(videoKey);
+    if (!archiveAfterNormalize) {
+      throw new Error('Archive item not found after normalize');
+    }
+
+    const needSegments = forceRebuild || !hasSegments(archiveAfterNormalize);
+    if (needSegments) {
+      await segmentVideoByKey(videoKey);
+    }
+
+    archiveItem = await getVideoByKey(videoKey);
+    if (!archiveItem) {
+      throw new Error('Archive item not found after segments');
+    }
+
+    rememberVideo(session, archiveItem);
+    await updateJobStatus({ cfg, jobStatus, stage: 'done' });
+
+    const note = ingest.reused ? 'Video jau buvo bibliotekoje, artefaktai atnaujinti.' : '';
+    await sendSummaryResult({ cfg, chatId, session, archiveItem, note });
+    return true;
+  } catch (error) {
+    const archiveItem = videoKey ? await getVideoByKey(videoKey).catch(() => null) : null;
+    const errorText = describePipelineError(jobStatus.currentStage, error, archiveItem);
+
+    await updateJobStatus({
+      cfg,
+      jobStatus,
+      stage: 'done',
+      note: 'Completed with warnings',
+    });
+
+    if (archiveItem && (archiveItem.video_text?.content_summary_1p || archiveItem.video_text?.content_literary)) {
+      rememberVideo(session, archiveItem);
+      await sendSummaryResult({
+        cfg,
+        chatId,
+        session,
+        archiveItem,
+        note: errorText,
+      });
+    } else {
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: errorText,
+      });
+    }
+
+    logger.error('Telegram YouTube workflow failed', {
+      stage: jobStatus.currentStage,
+      chatId: String(chatId),
+      videoKey,
+      message: error?.message || String(error),
+    });
+
+    return true;
+  }
+}
+
+function ensureAllowedChat(cfg, chatId) {
+  const allowed = String(cfg.telegramAllowedChatId || '').trim();
+  if (!allowed) return true;
+  return String(chatId) === allowed;
+}
+
+async function sendLibraryView({ cfg, chatId }) {
+  const recent = await listVideos({ limit: 12 });
+  const categories = await listArchiveCategories();
+
+  const lines = ['Library'];
+  lines.push('');
+  lines.push('Recent:');
+  if (recent.items.length === 0) {
+    lines.push('- no items');
+  } else {
+    for (const item of recent.items.slice(0, 8)) {
+      const cat = item.subscription_topic ? ` | ${item.subscription_topic}` : '';
+      lines.push(`- ${item.video_key} | ${item.review_state}${cat} | ${truncateText(item.title_original || item.youtube_video_id, 52)}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('By category:');
+  if (categories.length === 0) {
+    lines.push('- no categories');
+  } else {
+    for (const row of categories.slice(0, 10)) {
+      lines.push(`- ${row.category} (${row.count})`);
+    }
+  }
+
+  const languageCounts = new Map();
+  for (const item of recent.items) {
+    const lang = String(item.language_original || '').trim();
+    if (!lang) continue;
+    languageCounts.set(lang, (languageCounts.get(lang) || 0) + 1);
+  }
+
+  if (languageCounts.size > 0) {
+    lines.push('');
+    lines.push('By language (recent sample):');
+    for (const [lang, count] of [...languageCounts.entries()].sort((a, b) => b[1] - a[1])) {
+      lines.push(`- ${lang} (${count})`);
+    }
+  }
+
+  await sendTelegramText({
+    botToken: cfg.telegramBotToken,
+    chatId,
+    text: lines.join('\n'),
+  });
+}
+
+async function sendSaveWithCategoryHints({ cfg, chatId, session, videoKey, baseMessage }) {
+  const globalCategories = await listArchiveCategories().catch(() => []);
+  const keyboard = buildCategoryKeyboard(session, videoKey, globalCategories);
+
+  await sendTelegramText({
+    botToken: cfg.telegramBotToken,
+    chatId,
+    text: baseMessage,
+    replyMarkup: keyboard,
+  });
+}
+
+async function handleTopicListRequest({ cfg, chatId, session, videoKey }) {
+  const archiveItem = await getVideoByKey(videoKey);
+  if (!archiveItem) {
+    await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Irasas nerastas.' });
+    return;
+  }
+
+  rememberVideo(session, archiveItem);
+  const { keyboard, count } = collectTopicButtons(session, videoKey, archiveItem);
+  if (!keyboard || count === 0) {
+    await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Topic map dar neparuostas.' });
+    return;
+  }
+
+  await sendTelegramText({
+    botToken: cfg.telegramBotToken,
+    chatId,
+    text: `Temos (${count}):`,
+    replyMarkup: keyboard,
+  });
+}
+
+async function handleCommand({ cfg, chatId, userId, messageId, command, args, argsText, session }) {
+  if (command === 'start' || command === 'help') {
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      replyToMessageId: messageId,
+      text: buildHelpText(),
+    });
+    return;
+  }
+
+  if (command === 'library') {
+    await sendLibraryView({ cfg, chatId });
+    return;
+  }
+
+  if (command === 'inbox') {
+    const result = await listVideos({ reviewState: 'inbox', limit: 15 });
+    if (result.items.length === 0) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Inbox tuscias.' });
+      return;
+    }
+
+    const lines = ['Inbox:'];
+    for (const item of result.items) {
+      const category = item.subscription_topic ? ` | ${item.subscription_topic}` : '';
+      lines.push(`- ${item.video_key} | ${truncateText(item.title_original || item.youtube_video_id, 70)}${category}`);
+    }
+
+    await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: lines.join('\n') });
+    return;
+  }
+
+  if (command === 'list') {
+    const stateArg = args[0] && REVIEW_STATES.has(args[0]) ? args[0] : null;
+    const result = await listVideos({ reviewState: stateArg, limit: 20 });
+    if (result.items.length === 0) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Irasu nerasta.' });
+      return;
+    }
+
+    const lines = [`Irasai${stateArg ? ` (${stateArg})` : ''}:`];
+    for (const item of result.items) {
+      lines.push(`- ${item.video_key} | ${item.review_state} | ${truncateText(item.title_original || item.youtube_video_id, 64)}`);
+    }
+
+    await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: lines.join('\n') });
+    return;
+  }
+
+  if (command === 'categories') {
+    const categories = await listArchiveCategories();
+    if (categories.length === 0) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Kategoriju dar nera.' });
+      return;
+    }
+
+    const lines = ['Kategorijos:'];
+    for (const category of categories) {
+      lines.push(`- ${category.category} (${category.count})`);
+    }
+
+    await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: lines.join('\n') });
+    return;
+  }
+
+  if (command === 'rebuild') {
+    const target = String(argsText || '').trim();
+    if (!target) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Naudojimas: /rebuild <video_key|youtube_url>' });
+      return;
+    }
+
+    const maybeUrl = extractYouTubeUrl(target);
+    if (maybeUrl) {
+      await runYoutubeWorkflow({
+        cfg,
+        chatId,
+        session,
+        sourceText: maybeUrl,
+        replyToMessageId: messageId,
+        forceRebuild: true,
+      });
+      return;
+    }
+
+    await runRebuildByVideoKey({
+      cfg,
+      chatId,
+      session,
+      videoKey: target,
+      replyToMessageId: messageId,
+    });
+    return;
+  }
+
+  if (command === 'get' || command === 'summary') {
+    const videoKey = resolveVideoKey(session, args[0]);
+    if (!videoKey) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Nurodyk video_key. Pvz: /get vid_xxx' });
+      return;
+    }
+
+    const archiveItem = await getVideoByKey(videoKey);
+    if (!archiveItem) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Irasas nerastas.' });
+      return;
+    }
+
+    rememberVideo(session, archiveItem);
+    await sendSummaryResult({ cfg, chatId, session, archiveItem, replyToMessageId: messageId });
+    return;
+  }
+
+  if (command === 'outline') {
+    const videoKey = resolveVideoKey(session, args[0]);
+    if (!videoKey) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Nurodyk video_key: /outline vid_xxx' });
+      return;
+    }
+
+    const archiveItem = await getVideoByKey(videoKey);
+    if (!archiveItem) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Irasas nerastas.' });
+      return;
+    }
+
+    rememberVideo(session, archiveItem);
+    await sendOutlineText({ cfg, chatId, archiveItem });
+    return;
+  }
+
+  if (command === 'topics') {
+    const videoKey = resolveVideoKey(session, args[0]);
+    if (!videoKey) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Nurodyk video_key: /topics vid_xxx' });
+      return;
+    }
+
+    await handleTopicListRequest({ cfg, chatId, session, videoKey });
+    return;
+  }
+
+  if (command === 'edited') {
+    const videoKey = resolveVideoKey(session, args[0]);
+    if (!videoKey) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Nurodyk video_key: /edited vid_xxx' });
+      return;
+    }
+
+    const archiveItem = await getVideoByKey(videoKey);
+    if (!archiveItem) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Irasas nerastas.' });
+      return;
+    }
+
+    rememberVideo(session, archiveItem);
+    await sendTelegramDocument({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      filename: `${videoKey}.edited.md`,
+      caption: `Edited transcript: ${videoKey}`,
+      content: buildEditedMd(archiveItem),
+    });
+    return;
+  }
+
+  if (command === 'md') {
+    const videoKey = resolveVideoKey(session, args[0]);
+    if (!videoKey) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Nurodyk video_key: /md vid_xxx' });
+      return;
+    }
+
+    const archiveItem = await getVideoByKey(videoKey);
+    if (!archiveItem) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Irasas nerastas.' });
+      return;
+    }
+
+    rememberVideo(session, archiveItem);
+    const content = renderUserFacingMarkdown(
+      {
+        video: archiveItem.video,
+        videoText: archiveItem.video_text,
+        segments: archiveItem.segments || [],
+      },
+      {
+        includeEdited: true,
+        debug: false,
+      }
+    );
+
+    await sendTelegramDocument({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      filename: `${videoKey}.md`,
+      caption: `Master markdown: ${videoKey}`,
+      content,
+    });
+    return;
+  }
+
+  if (command === 'save') {
+    const explicitKey = args[0] && String(args[0]).startsWith('vid_') ? args[0] : '';
+    const videoKey = resolveVideoKey(session, explicitKey);
+    const categoryText = explicitKey ? args.slice(1).join(' ').trim() : args.join(' ').trim();
+
+    if (!videoKey) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Naudojimas: /save [video_key] [category]' });
+      return;
+    }
+
+    await setReviewState({ videoKey, reviewState: 'saved', note: 'telegram-save' });
+
+    if (categoryText) {
+      const updated = await setVideoCategory({ videoKey, category: categoryText, actor: 'telegram-owner' });
+      if (updated.subscription_topic) rememberCategory(session, updated.subscription_topic);
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: `Issaugota: ${videoKey} | category: ${categoryText}`,
+      });
+      return;
+    }
+
+    await sendSaveWithCategoryHints({
+      cfg,
+      chatId,
+      session,
+      videoKey,
+      baseMessage: `Issaugota: ${videoKey}. Pasirink kategorija:`,
+    });
+    return;
+  }
+
+  if (command === 'discard') {
+    const videoKey = resolveVideoKey(session, args[0]);
+    if (!videoKey) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Naudojimas: /discard [video_key]' });
+      return;
+    }
+
+    await setReviewState({ videoKey, reviewState: 'discarded', note: 'telegram-discard' });
+    session.lastVideoKey = videoKey;
+    await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: `Discarded: ${videoKey}` });
+    return;
+  }
+
+  if (command === 'category' || command === 'dir') {
+    const explicitKey = args[0] && String(args[0]).startsWith('vid_') ? args[0] : '';
+    const videoKey = resolveVideoKey(session, explicitKey);
+    const category = explicitKey ? args.slice(1).join(' ').trim() : args.join(' ').trim();
+
+    if (!videoKey || !category) {
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: 'Naudojimas: /category [video_key] <category>',
+      });
+      return;
+    }
+
+    const nextCategory = category === '-' ? null : category;
+    const updated = await setVideoCategory({ videoKey, category: nextCategory, actor: 'telegram-owner' });
+    if (updated.subscription_topic) rememberCategory(session, updated.subscription_topic);
+    session.lastVideoKey = videoKey;
+
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      text: updated.subscription_topic
+        ? `Kategorija nustatyta: ${videoKey} -> ${updated.subscription_topic}`
+        : `Kategorija isvalyta: ${videoKey}`,
+    });
+    return;
+  }
+
+  if (command === 'note') {
+    const explicitKey = args[0] && String(args[0]).startsWith('vid_') ? args[0] : '';
+    const videoKey = resolveVideoKey(session, explicitKey);
+    const noteBody = explicitKey ? args.slice(1).join(' ').trim() : args.join(' ').trim();
+
+    if (!videoKey || !noteBody) {
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: 'Naudojimas: /note [video_key] <tekstas>',
+      });
+      return;
+    }
+
+    const note = await addEditorialNote({
+      videoKey,
+      noteType: 'telegram-note',
+      body: noteBody,
+    });
+
+    session.lastVideoKey = videoKey;
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      text: `Pastaba issaugota: ${note.note_key}`,
+    });
+    return;
+  }
+
+  if (command === 'ask') {
+    let videoKey = '';
+    let question = '';
+
+    if (args[0] && String(args[0]).startsWith('vid_')) {
+      videoKey = args[0];
+      question = args.slice(1).join(' ').trim();
+    } else {
+      videoKey = resolveVideoKey(session, '');
+      question = argsText;
+    }
+
+    if (!videoKey || !question) {
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: 'Naudojimas: /ask [video_key] <klausimas>',
+      });
+      return;
+    }
+
+    const archiveItem = await getVideoByKey(videoKey);
+    if (!archiveItem) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Irasas nerastas.' });
+      return;
+    }
+
+    rememberVideo(session, archiveItem);
+    await sendTelegramChatAction({ botToken: cfg.telegramBotToken, chatId, action: 'typing' });
+    const answer = await answerQuestionAboutVideo({ question, archiveItem });
+
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      text: answer,
+    });
+    return;
+  }
+
+  await sendTelegramText({
+    botToken: cfg.telegramBotToken,
+    chatId,
+    text: `Neatpazinta komanda: /${command}\n\n${buildHelpText()}`,
+  });
+}
+
+async function handleNaturalLanguageFallback({ cfg, chatId, text, session }) {
+  const key = resolveVideoKey(session, '');
+  if (!key) {
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      text: 'Atsiusk YouTube URL arba /help.',
+    });
+    return;
+  }
+
+  if (/\boutline\b/i.test(text)) {
+    const archiveItem = await getVideoByKey(key);
+    if (!archiveItem) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Irasas nerastas.' });
+      return;
+    }
+    rememberVideo(session, archiveItem);
+    await sendOutlineText({ cfg, chatId, archiveItem });
+    return;
+  }
+
+  if (/\bsummary\b|santrau/i.test(text)) {
+    const archiveItem = await getVideoByKey(key);
+    if (!archiveItem) {
+      await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Irasas nerastas.' });
+      return;
+    }
+    rememberVideo(session, archiveItem);
+    await sendSummaryResult({ cfg, chatId, session, archiveItem });
+    return;
+  }
+
+  if (/\bsave\b|issaug|išsaug/i.test(text)) {
+    await setReviewState({ videoKey: key, reviewState: 'saved', note: 'telegram-save-natural' });
+
+    const categoryMatch = text.match(/\b(?:i|į)\s+([^.,!?\n]{2,60})$/i);
+    if (categoryMatch?.[1]) {
+      const category = categoryMatch[1].trim();
+      const updated = await setVideoCategory({ videoKey: key, category, actor: 'telegram-owner' });
+      if (updated.subscription_topic) rememberCategory(session, updated.subscription_topic);
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: `Issaugota i kategorija: ${category}`,
+      });
+      return;
+    }
+
+    await sendSaveWithCategoryHints({
+      cfg,
+      chatId,
+      session,
+      videoKey: key,
+      baseMessage: `Issaugota: ${key}. Pasirink kategorija:`,
+    });
+    return;
+  }
+
+  const archiveItem = await getVideoByKey(key);
+  if (!archiveItem) {
+    await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: 'Irasas nerastas.' });
+    return;
+  }
+
+  rememberVideo(session, archiveItem);
+  await sendTelegramChatAction({ botToken: cfg.telegramBotToken, chatId, action: 'typing' });
+  const answer = await answerQuestionAboutVideo({ question: text, archiveItem });
+  await sendTelegramText({ botToken: cfg.telegramBotToken, chatId, text: answer });
+}
+
+async function handleCallback({ cfg, callback }) {
+  const callbackId = callback?.id;
+  const data = String(callback?.data || '').trim();
+  const chatId = callback?.message?.chat?.id;
+  const userId = callback?.from?.id || chatId;
+
+  if (!chatId || !data) {
+    if (callbackId) {
+      await answerTelegramCallbackQuery({
+        botToken: cfg.telegramBotToken,
+        callbackQueryId: callbackId,
+      }).catch(() => {});
+    }
+    return;
+  }
+
+  const session = getSession(chatId, userId);
+  const parts = data.split('|');
+  const type = parts[0] || '';
+
+  const ack = async (text = '') => {
+    if (!callbackId) return;
+    await answerTelegramCallbackQuery({
+      botToken: cfg.telegramBotToken,
+      callbackQueryId: callbackId,
+      text,
+      showAlert: false,
+    }).catch(() => {});
+  };
+
+  if (type === 'a') {
+    const action = parts[1] || '';
+    const videoKey = parts[2] || '';
+    const archiveItem = await getVideoByKey(videoKey);
+
+    if (!archiveItem) {
+      await ack('Irasas nerastas');
+      return;
+    }
+
+    rememberVideo(session, archiveItem);
+
+    if (action === 'out') {
+      await ack('Outline');
+      await sendOutlineText({ cfg, chatId, archiveItem });
+      return;
+    }
+
+    if (action === 'ed') {
+      await ack('Edited transcript');
+      await sendTelegramDocument({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        filename: `${videoKey}.edited.md`,
+        caption: `Edited transcript: ${videoKey}`,
+        content: buildEditedMd(archiveItem),
+      });
+      return;
+    }
+
+    if (action === 'ask') {
+      await ack('Ask mode');
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: `Užduok klausimą apie ${videoKey}. Gali rašyti tiesiog tekstą arba /ask <klausimas>.`,
+      });
+      return;
+    }
+
+    if (action === 'save') {
+      await setReviewState({ videoKey, reviewState: 'saved', note: 'telegram-save-button' });
+      await ack('Saved');
+      await sendSaveWithCategoryHints({
+        cfg,
+        chatId,
+        session,
+        videoKey,
+        baseMessage: `Issaugota: ${videoKey}. Pasirink kategorija:`,
+      });
+      return;
+    }
+
+    if (action === 'topics') {
+      await ack('Topics');
+      await handleTopicListRequest({ cfg, chatId, session, videoKey });
+      return;
+    }
+
+    await ack('Unknown action');
+    return;
+  }
+
+  if (type === 'c') {
+    const videoKey = parts[1] || '';
+    const indexRaw = parts[2] || '';
+
+    if (indexRaw === 'new') {
+      await ack('New category');
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: `Nauja kategorija: /category ${videoKey} <category>`,
+      });
+      return;
+    }
+
+    const idx = Number(indexRaw);
+    const options = Array.isArray(session.categoryOptionsByVideo[videoKey]) ? session.categoryOptionsByVideo[videoKey] : [];
+    const category = Number.isInteger(idx) && idx >= 0 ? options[idx] : null;
+
+    if (!category) {
+      await ack('Category not found');
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: 'Kategorijos pasirinkimas nebegalioja. Pakartok /save.',
+      });
+      return;
+    }
+
+    const updated = await setVideoCategory({ videoKey, category, actor: 'telegram-owner' });
+    if (updated.subscription_topic) rememberCategory(session, updated.subscription_topic);
+
+    await ack('Category saved');
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      text: `Kategorija nustatyta: ${videoKey} -> ${category}`,
+    });
+    return;
+  }
+
+  if (type === 't') {
+    const videoKey = parts[1] || '';
+    const indexRaw = parts[2] || '';
+    const archiveItem = await getVideoByKey(videoKey);
+
+    if (!archiveItem) {
+      await ack('Irasas nerastas');
+      return;
+    }
+
+    rememberVideo(session, archiveItem);
+    const topic = resolveTopicByIndex(session, archiveItem, videoKey, indexRaw);
+    if (!topic) {
+      await ack('Topic not found');
+      return;
+    }
+
+    await ack('Topic');
+    const idx = Number(indexRaw);
+    const detailKeyboard = {
+      inline_keyboard: [[{ text: 'Show evidence', callback_data: `e|${videoKey}|${idx}` }]],
+    };
+
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      text: formatTopicDetail(topic),
+      replyMarkup: detailKeyboard,
+    });
+    return;
+  }
+
+  if (type === 'e') {
+    const videoKey = parts[1] || '';
+    const indexRaw = parts[2] || '';
+    const archiveItem = await getVideoByKey(videoKey);
+
+    if (!archiveItem) {
+      await ack('Irasas nerastas');
+      return;
+    }
+
+    const topic = resolveTopicByIndex(session, archiveItem, videoKey, indexRaw);
+    if (!topic) {
+      await ack('Topic not found');
+      return;
+    }
+
+    await ack('Evidence');
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      text: buildTopicEvidence(topic, archiveItem.segments || []),
+    });
+    return;
+  }
+
+  await ack('Unsupported action');
+}
+
+export async function handleTelegramUpdate(update) {
+  const cfg = getConfig();
+  if (!cfg.telegramBotToken) {
+    logger.warn('Telegram update skipped: TELEGRAM_BOT_TOKEN missing');
+    return;
+  }
+
+  const callback = extractCallbackQuery(update);
+  if (callback) {
+    const chatId = callback?.message?.chat?.id;
+    if (chatId && !ensureAllowedChat(cfg, chatId)) {
+      await answerTelegramCallbackQuery({
+        botToken: cfg.telegramBotToken,
+        callbackQueryId: callback.id,
+        text: 'Unauthorized chat',
+        showAlert: true,
+      }).catch(() => {});
+      return;
+    }
+
+    try {
+      await handleCallback({ cfg, callback });
+    } catch (error) {
+      logger.error('Telegram callback failed', {
+        chatId: String(chatId || ''),
+        message: error?.message || String(error),
+      });
+      if (callback?.id) {
+        await answerTelegramCallbackQuery({
+          botToken: cfg.telegramBotToken,
+          callbackQueryId: callback.id,
+          text: 'Klaida apdorojant veiksmą',
+          showAlert: true,
+        }).catch(() => {});
+      }
+    }
+    return;
+  }
+
+  const message = extractMessage(update);
+  if (!message || !message.chat?.id) {
+    return;
+  }
+
+  const chatId = message.chat.id;
+  const userId = message.from?.id || chatId;
+  const messageId = message.message_id || null;
+  const text = String(message.text || '').trim();
+  if (!text) return;
+
+  if (!ensureAllowedChat(cfg, chatId)) {
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      text: 'Sis botas konfiguruotas tik savininko chat ID.',
+      replyToMessageId: messageId,
+    });
+    return;
+  }
+
+  const session = getSession(chatId, userId);
+
+  const handledByUrl = await runYoutubeWorkflow({
+    cfg,
+    chatId,
+    session,
+    sourceText: text,
+    replyToMessageId: messageId,
+  });
+  if (handledByUrl) return;
+
+  const parsed = parseCommand(text);
+  if (!parsed) {
+    try {
+      await handleNaturalLanguageFallback({
+        cfg,
+        chatId,
+        text,
+        session,
+      });
+    } catch (error) {
+      logger.error('Telegram natural message failed', {
+        chatId: String(chatId),
+        userId: String(userId),
+        message: error?.message || String(error),
+      });
+      await sendTelegramText({
+        botToken: cfg.telegramBotToken,
+        chatId,
+        text: `Klaida: ${error?.message || 'nezinoma klaida'}`,
+      });
+    }
+    return;
+  }
+
+  try {
+    await handleCommand({
+      cfg,
+      chatId,
+      userId,
+      messageId,
+      command: parsed.command,
+      args: parsed.args,
+      argsText: parsed.argsText,
+      session,
+    });
+  } catch (error) {
+    logger.error('Telegram command failed', {
+      command: parsed.command,
+      chatId: String(chatId),
+      message: error?.message || String(error),
+    });
+    await sendTelegramText({
+      botToken: cfg.telegramBotToken,
+      chatId,
+      text: `Klaida: ${error?.message || 'nezinoma klaida'}`,
+    });
+  }
+}

services/telegram/telegram-client.js

@@ -0,0 +1,176 @@
+import { logger } from '../../lib/logger.js';
+
+const TELEGRAM_API_ROOT = 'https://api.telegram.org';
+const TELEGRAM_MAX_TEXT = 3800;
+
+function assertToken(botToken) {
+  const token = String(botToken || '').trim();
+  if (!token) {
+    throw new Error('TELEGRAM_BOT_TOKEN is not configured');
+  }
+  return token;
+}
+
+function buildUrl(botToken, method) {
+  return `${TELEGRAM_API_ROOT}/bot${botToken}/${method}`;
+}
+
+async function callTelegram(botToken, method, body, { isFormData = false } = {}) {
+  const token = assertToken(botToken);
+  const response = await fetch(buildUrl(token, method), {
+    method: 'POST',
+    headers: isFormData ? undefined : { 'Content-Type': 'application/json' },
+    body: isFormData ? body : JSON.stringify(body),
+  });
+
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok || payload?.ok === false) {
+    const description = payload?.description || `Telegram API error (${response.status})`;
+    throw new Error(description);
+  }
+  return payload.result;
+}
+
+export function splitTelegramText(input, maxLength = TELEGRAM_MAX_TEXT) {
+  const text = String(input || '').trim();
+  if (!text) return [];
+  if (text.length <= maxLength) return [text];
+
+  const lines = text.split('\n');
+  const chunks = [];
+  let current = '';
+
+  for (const line of lines) {
+    if (!current) {
+      if (line.length <= maxLength) {
+        current = line;
+        continue;
+      }
+
+      const words = line.split(' ');
+      let wordChunk = '';
+      for (const word of words) {
+        const candidate = wordChunk ? `${wordChunk} ${word}` : word;
+        if (candidate.length > maxLength) {
+          if (wordChunk) chunks.push(wordChunk);
+          wordChunk = word;
+        } else {
+          wordChunk = candidate;
+        }
+      }
+      if (wordChunk) {
+        current = wordChunk;
+      }
+      continue;
+    }
+
+    const candidate = `${current}\n${line}`;
+    if (candidate.length > maxLength) {
+      chunks.push(current);
+      current = line;
+    } else {
+      current = candidate;
+    }
+  }
+
+  if (current) chunks.push(current);
+  return chunks;
+}
+
+export async function sendTelegramText({
+  botToken,
+  chatId,
+  text,
+  disableWebPagePreview = true,
+  replyToMessageId = null,
+  replyMarkup = null,
+} = {}) {
+  const chunks = splitTelegramText(text);
+  if (chunks.length === 0) return [];
+
+  const results = [];
+  for (let index = 0; index < chunks.length; index += 1) {
+    const chunk = chunks[index];
+    const payload = {
+      chat_id: chatId,
+      text: chunk,
+      disable_web_page_preview: disableWebPagePreview,
+    };
+    if (replyToMessageId) {
+      payload.reply_to_message_id = replyToMessageId;
+    }
+    if (replyMarkup && index === chunks.length - 1) {
+      payload.reply_markup = replyMarkup;
+    }
+    const sent = await callTelegram(botToken, 'sendMessage', payload);
+    results.push(sent);
+  }
+  return results;
+}
+
+export async function editTelegramText({
+  botToken,
+  chatId,
+  messageId,
+  text,
+  disableWebPagePreview = true,
+  replyMarkup = null,
+} = {}) {
+  const payload = {
+    chat_id: chatId,
+    message_id: messageId,
+    text: String(text || '').trim(),
+    disable_web_page_preview: disableWebPagePreview,
+  };
+  if (replyMarkup) {
+    payload.reply_markup = replyMarkup;
+  }
+
+  return callTelegram(botToken, 'editMessageText', payload);
+}
+
+export async function sendTelegramChatAction({ botToken, chatId, action = 'typing' } = {}) {
+  try {
+    await callTelegram(botToken, 'sendChatAction', {
+      chat_id: chatId,
+      action,
+    });
+  } catch (error) {
+    logger.debug('Telegram chat action failed', {
+      action,
+      message: error?.message || String(error),
+    });
+  }
+}
+
+export async function sendTelegramDocument({
+  botToken,
+  chatId,
+  filename,
+  content,
+  caption = '',
+} = {}) {
+  const data = new FormData();
+  data.append('chat_id', String(chatId));
+  if (caption) data.append('caption', String(caption));
+  data.append(
+    'document',
+    new Blob([String(content || '')], { type: 'text/markdown;charset=utf-8' }),
+    String(filename || 'artifact.md')
+  );
+
+  return callTelegram(botToken, 'sendDocument', data, { isFormData: true });
+}
+
+export async function answerTelegramCallbackQuery({
+  botToken,
+  callbackQueryId,
+  text = '',
+  showAlert = false,
+} = {}) {
+  return callTelegram(botToken, 'answerCallbackQuery', {
+    callback_query_id: callbackQueryId,
+    text: String(text || ''),
+    show_alert: Boolean(showAlert),
+  });
+}