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

``bash
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

$3

`javascript
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});
`

$3

`javascript
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
});
`

$3

`javascript
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:

`javascript
// 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:

`yaml
---
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:

`bash
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

$3

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

$3

Low-level Telegram export.

$3

Translate text content.

$3

Translate title (optimized prompt for short text).

$3

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