koztv-blog-tools

Shared utilities for Telegram-based blog sites. Export posts from Telegram channels, translate with LLM APIs, and generate markdown for static site generators.

Installation

npm install koztv-blog-tools

Features

• Telegram Export — Export full channel history via MTProto (gramjs)
• Translation — Translate posts using OpenAI-compatible APIs (GLM, OpenAI, etc.)
• Multi-language — Export to multiple languages simultaneously
• Markdown Generation — Create markdown files with YAML frontmatter
• Media Download — Download photos, videos, and documents
• Incremental Export — Track processed posts, skip duplicates

Quick Start

Export + Translate

const { exportAndTranslate } = require('koztv-blog-tools');

const result = await exportAndTranslate({
  // Telegram credentials (from https://my.telegram.org)
  apiId: 12345678,
  apiHash: 'your_api_hash',
  session: 'saved_session_string', // from previous auth

  // Target channel
  channel: '@channelname',

  // Output
  outputDir: './content/posts',
  mediaDir: './public/media',

  // Translation (optional)
  translate: {
    apiKey: 'your_llm_api_key',
    apiUrl: 'https://api.openai.com/v1', // or GLM, etc.
    model: 'gpt-4',
    sourceLang: 'ru',
    targetLangs: ['en', 'de'],  // translate to multiple languages
    keepOriginal: true,         // also save original language
  },

  // Callbacks
  onProgress: (msg) => console.log(msg),
  onSession: (s) => saveSession(s), // save for future use
});

console.log(`Exported: ${result.exported}, Processed: ${result.processed}`);

Export Only (no translation)

const { exportTelegramChannel } = require('koztv-blog-tools');

const result = await exportTelegramChannel({
  apiId: 12345678,
  apiHash: 'your_api_hash',
  session: 'saved_session_string',
  target: '@channelname',
  outputDir: './export',
  downloadMedia: true,
  limit: 100, // optional: limit number of posts
  since: new Date('2024-01-01'), // optional: filter by date
});

Translate Text

const { translateContent, translateTitle } = require('koztv-blog-tools');

const translated = await translateContent('Привет мир', {
  apiKey: 'your_api_key',
  apiUrl: 'https://api.openai.com/v1',
  model: 'gpt-4',
  sourceLang: 'ru',
  targetLang: 'en',
});
// => "Hello world"

Authentication

First-time authentication requires QR code login. See scripts/qr-login.js in your project:

// Example QR login script
const { TelegramClient } = require('telegram');
const { StringSession } = require('telegram/sessions');

const client = new TelegramClient(
  new StringSession(''),
  API_ID,
  API_HASH,
  { connectionRetries: 5 }
);

await client.start({
  phoneNumber: async () => prompt('Phone: '),
  password: async () => prompt('2FA: '),
  phoneCode: async () => prompt('Code: '),
  onError: console.error,
});

console.log('Session:', client.session.save());

Output Structure

With multi-language enabled (targetLangs + keepOriginal):

content/posts/
  en/
    my-post-slug/
      index.md
  ru/
    my-post-slug/
      index.md
public/media/
  000123/
    image1.jpg
    image2.jpg

Markdown format:

---
title: "Post Title"
date: 2024-01-15
lang: en
original_link: "https://t.me/channel/123"
translated_from: "ru"
---

Post content here...

![](/media/000123/image1.jpg)

Environment Variables

For GitHub Actions / CI:

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_SESSION=base64_session_string
TELEGRAM_CHANNEL=@channelname

LLM_API_KEY=your_llm_key
LLM_API_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4

TARGET_LANGS=en,de      # comma-separated
KEEP_ORIGINAL=true      # keep source language

API Reference

exportAndTranslate(options)

Main function for export + translation workflow.

Options:

• apiId, apiHash, session — Telegram credentials
• channel — Target channel (@username or ID)
• outputDir — Where to save markdown files
• mediaDir — Where to save media (optional)
• limit — Max posts to export (optional)
• since — Export posts after this date (optional)
• downloadMedia — Download media files (default: true)
• translate — Translation config (optional)
• onProgress — Progress callback
• onSession — Session save callback
• processedLog — Object tracking processed posts
• onProcessedLog — Callback to save processed log

exportTelegramChannel(options)

Low-level Telegram export.

translateContent(text, options)

Translate text content.

translateTitle(title, options)

Translate title (optimized prompt for short text).

generateEnglishSlug(title, options)

Generate URL-friendly slug from any language title.

Used By

• koz.tv — Personal blog with Telegram sync
• staskoz.com — Another blog using this package

Related

• k-engine — Static site generator with multi-language support

License

MIT