Add Telegram export parser

Author: ndbroadbent

README.md

@@ -7,10 +7,10 @@ Transform chat exports into geocoded activity suggestions.
 
 ## Overview
 
-ChatToMap extracts "things to do" from WhatsApp and iMessage exports - restaurants to try, places to visit, trips to take. It finds suggestions buried in years of chat history and puts them on a map.
+ChatToMap extracts "things to do" from WhatsApp, iMessage, and Telegram exports - restaurants to try, places to visit, trips to take. It finds suggestions buried in years of chat history and puts them on a map.
 
 **Features:**
-- Parse WhatsApp (iOS/Android) and iMessage exports
+- Parse WhatsApp (iOS/Android), iMessage, and Telegram Desktop JSON exports
 - Extract suggestions using multilingual regex patterns, embeddings, and URL detection
 - Classify with AI (activity vs errand, mappable vs general)
 - Scrape metadata from TikTok and YouTube links
@@ -50,6 +50,9 @@ chat-to-map preview <input>
 # Full analysis with exports
 chat-to-map analyze <input>
 
+# Telegram Desktop exports
+chat-to-map analyze "/path/to/ChatExport_2026-04-26/result.json"
+
 # List previously processed chats
 chat-to-map list
 ```
@@ -150,7 +153,7 @@ export CHAT_TO_MAP_CONFIG=/path/to/config.json
 
 ```typescript
 import {
-  parseWhatsAppChat,
+  parseChat,
   extractCandidatesByHeuristics,
   extractCandidates,  // combined: heuristics + embeddings
   classifyMessages,
@@ -164,7 +167,7 @@ const scan = quickScan(chatText)
 console.log(`Found ${scan.candidates.length} candidates`)
 
 // Parse messages
-const messages = parseWhatsAppChat(chatText)
+const messages = parseChat(chatText)
 
 // Extract candidates (heuristics only - sync, free)
 const { candidates } = extractCandidatesByHeuristics(messages)

src/cli/commands/parse.ts

@@ -7,6 +7,7 @@
 import { writeFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import { VERSION } from '../../index'
+import type { ChatSource } from '../../types'
 import type { CLIArgs } from '../args'
 import { ensureDir } from '../io'
 import type { Logger } from '../logger'
@@ -15,8 +16,10 @@ import { initContext, stepParse } from '../steps/index'
 /**
  * Format chat source for display.
  */
-function formatSource(source: 'whatsapp' | 'imessage'): string {
-  return source === 'whatsapp' ? 'WhatsApp' : 'iMessage'
+function formatSource(source: ChatSource): string {
+  if (source === 'whatsapp') return 'WhatsApp'
+  if (source === 'imessage') return 'iMessage'
+  return 'Telegram'
 }
 
 /**

src/cli/input.test.ts

@@ -47,6 +47,15 @@ describe('getInputMetadata', () => {
     expect(metadata.baseName).toBe('chat')
   })
 
+  it('removes .json extension', async () => {
+    const filePath = join(TEST_DIR, 'result.json')
+    await writeFile(filePath, '{"messages":[]}')
+
+    const metadata = await getInputMetadata(filePath)
+
+    expect(metadata.baseName).toBe('result')
+  })
+
   it('generates different hash for different mtimes', async () => {
     const filePath = join(TEST_DIR, 'chat.txt')
     await writeFile(filePath, 'test')
@@ -119,6 +128,16 @@ describe('readInputFileWithMetadata', () => {
     const result = await readInputFileWithMetadata(filePath)
     expect(result.content).toBe('Chat content')
   })
+
+  it('reads Telegram result.json files', async () => {
+    const filePath = join(TEST_DIR, 'result.json')
+    await writeFile(filePath, '{"messages":[]}')
+
+    const result = await readInputFileWithMetadata(filePath)
+
+    expect(result.content).toBe('{"messages":[]}')
+    expect(result.metadata.baseName).toBe('result')
+  })
 })
 
 describe('PipelineCache chat content caching', () => {

src/cli/io.test.ts

@@ -23,6 +23,15 @@ describe('readInputFile', () => {
 
       expect(content).toBe('Hello, world!')
     })
+
+    it('reads a direct Telegram result.json file', async () => {
+      const filePath = join(TEST_DIR, 'result.json')
+      await writeFile(filePath, '{"messages":[]}')
+
+      const content = await readInputFile(filePath)
+
+      expect(content).toBe('{"messages":[]}')
+    })
   })
 
   describe('zip files', () => {
@@ -54,7 +63,21 @@ describe('readInputFile', () => {
       expect(content).toBe('Chat via _chat.txt')
     })
 
-    it('throws when no .txt file found in zip', async () => {
+    it('reads result.json from a Telegram zip archive', async () => {
+      const JSZip = await import('jszip')
+      const zip = new JSZip.default()
+      zip.file('ChatExport/result.json', '{"messages":[]}')
+
+      const zipContent = await zip.generateAsync({ type: 'uint8array' })
+      const filePath = join(TEST_DIR, 'telegram.zip')
+      await writeFile(filePath, zipContent)
+
+      const content = await readInputFile(filePath)
+
+      expect(content).toBe('{"messages":[]}')
+    })
+
+    it('throws when no supported chat file is found in zip', async () => {
       const JSZip = await import('jszip')
       const zip = new JSZip.default()
       zip.file('readme.md', 'Not a chat file')
@@ -78,6 +101,27 @@ describe('readInputFile', () => {
       expect(content).toBe('iMessage content')
     })
 
+    it('reads result.json from a Telegram export directory', async () => {
+      const subDir = join(TEST_DIR, 'telegram-export')
+      await mkdir(subDir, { recursive: true })
+      await writeFile(join(subDir, 'result.json'), '{"messages":[]}')
+
+      const content = await readInputFile(subDir)
+
+      expect(content).toBe('{"messages":[]}')
+    })
+
+    it('prefers Telegram result.json over text files in a directory', async () => {
+      const subDir = join(TEST_DIR, 'telegram-export-with-files')
+      await mkdir(subDir, { recursive: true })
+      await writeFile(join(subDir, 'result.json'), '{"messages":[]}')
+      await writeFile(join(subDir, 'captions.txt'), 'caption attachment')
+
+      const content = await readInputFile(subDir)
+
+      expect(content).toBe('{"messages":[]}')
+    })
+
     it('concatenates multiple .txt files from a directory', async () => {
       const subDir = join(TEST_DIR, 'multi-export')
       await mkdir(subDir, { recursive: true })
@@ -90,19 +134,19 @@ describe('readInputFile', () => {
       expect(content).toBe('First chat\nSecond chat')
     })
 
-    it('throws when directory contains no .txt files', async () => {
+    it('throws when directory contains no supported chat files', async () => {
       const subDir = join(TEST_DIR, 'empty-export')
       await mkdir(subDir, { recursive: true })
       await writeFile(join(subDir, 'readme.md'), 'Not a txt file')
 
-      await expect(readInputFile(subDir)).rejects.toThrow('No .txt files found')
+      await expect(readInputFile(subDir)).rejects.toThrow('No .txt or result.json files found')
     })
 
     it('throws when directory is empty', async () => {
       const subDir = join(TEST_DIR, 'empty-dir')
       await mkdir(subDir, { recursive: true })
 
-      await expect(readInputFile(subDir)).rejects.toThrow('No .txt files found')
+      await expect(readInputFile(subDir)).rejects.toThrow('No .txt or result.json files found')
     })
 
     it('ignores non-.txt files in directory', async () => {

src/cli/io.ts

@@ -7,14 +7,22 @@
 import { mkdir, readdir, readFile, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 
+function isTelegramResultJson(name: string): boolean {
+  return name === 'result.json' || name.endsWith('/result.json')
+}
+
 /**
- * Find .txt files in a directory (non-recursive).
+ * Find supported chat files in a directory (non-recursive).
  */
-async function findTxtFilesInDir(dirPath: string): Promise<string[]> {
+async function findChatFilesInDir(dirPath: string): Promise<string[]> {
   const entries = await readdir(dirPath)
   const txtFiles: string[] = []
 
   for (const entry of entries) {
+    if (entry === 'result.json') {
+      return [join(dirPath, entry)]
+    }
+
     if (entry.endsWith('.txt')) {
       txtFiles.push(join(dirPath, entry))
     }
@@ -27,35 +35,35 @@ async function findTxtFilesInDir(dirPath: string): Promise<string[]> {
  * Read an input file, handling zip archives and directories.
  *
  * Supports:
- * - .zip files (WhatsApp exports)
- * - Directories containing .txt files (iMessage exports, extracted WhatsApp)
- * - Direct .txt file paths
+ * - .zip files (WhatsApp and Telegram exports)
+ * - Directories containing result.json or .txt files
+ * - Direct file paths
  */
 export async function readInputFile(path: string): Promise<string> {
   const stats = await stat(path)
 
   // Handle directory input
   if (stats.isDirectory()) {
-    const txtFiles = await findTxtFilesInDir(path)
+    const chatFiles = await findChatFilesInDir(path)
 
-    if (txtFiles.length === 0) {
-      throw new Error(`No .txt files found in directory: ${path}`)
+    if (chatFiles.length === 0) {
+      throw new Error(`No .txt or result.json files found in directory: ${path}`)
     }
 
     // If multiple files, concatenate them (common for iMessage exports)
-    if (txtFiles.length > 1) {
+    if (chatFiles.length > 1) {
       const contents: string[] = []
-      for (const file of txtFiles) {
+      for (const file of chatFiles) {
         const content = await readFile(file, 'utf-8')
         contents.push(content)
       }
       return contents.join('\n')
     }
 
     // Single file
-    const singleFile = txtFiles[0]
+    const singleFile = chatFiles[0]
     if (!singleFile) {
-      throw new Error(`No .txt files found in directory: ${path}`)
+      throw new Error(`No .txt or result.json files found in directory: ${path}`)
     }
     return readFile(singleFile, 'utf-8')
   }
@@ -66,10 +74,13 @@ export async function readInputFile(path: string): Promise<string> {
     const zipBuffer = await readFile(path)
     const zip = await JSZip.default.loadAsync(new Uint8Array(zipBuffer))
 
+    const fileNames = Object.keys(zip.files)
+
     // Find the chat file in the zip
-    const chatFile = Object.keys(zip.files).find(
-      (name) => name.endsWith('.txt') || name === '_chat.txt'
-    )
+    const chatFile =
+      fileNames.find(isTelegramResultJson) ??
+      fileNames.find((name) => name === '_chat.txt') ??
+      fileNames.find((name) => name.endsWith('.txt'))
 
     if (!chatFile) {
       throw new Error('No chat file found in zip archive')

src/cli/steps/parse.ts

@@ -14,7 +14,7 @@ import type { PipelineContext } from './context'
 export interface ParseResult {
   /** Parsed messages */
   readonly messages: readonly ParsedMessage[]
-  /** Detected chat source (whatsapp or imessage) */
+  /** Detected chat source */
   readonly source: ChatSource
   /** Whether result was from cache */
   readonly fromCache: boolean

src/cli/steps/read.ts

@@ -39,6 +39,7 @@ function sanitizeForDirectory(name: string): string {
   return name
     .replace(/\.zip$/i, '')
     .replace(/\.txt$/i, '')
+    .replace(/\.json$/i, '')
     .replace(/[^a-zA-Z0-9_-]/g, '_')
     .replace(/_+/g, '_')
     .replace(/^_|_$/g, '')

src/core/index.ts

@@ -151,11 +151,13 @@ export {
 export {
   detectChatSource,
   detectFormat,
+  isTelegramExport,
   parseChat,
   parseChatStream,
   parseChatWithStats,
   parseIMessageChat,
   parseIMessageChatStream,
+  parseTelegramExport,
   parseWhatsAppChat,
   parseWhatsAppChatStream
 } from '../parser/index'

src/parser/imessage.ts

@@ -16,15 +16,12 @@
  */
 
 import type { ParsedMessage } from '../types'
-import { chunkMessage, createChunkedMessages, normalizeApostrophes } from './index'
+import { chunkMessage, createChunkedMessages, extractUrls, normalizeApostrophes } from './index'
 
 // Timestamp line pattern: Apr 02, 2025  8:52:29 AM (optional read receipt)
 const TIMESTAMP_PATTERN =
   /^([A-Z][a-z]{2} \d{1,2}, \d{4})\s+(\d{1,2}:\d{2}:\d{2} [AP]M)(?:\s*\(.*\))?$/
 
-// URL extraction pattern
-const URL_PATTERN = /https?:\/\/[^\s<>"')\]]+/gi
-
 // Month name to number mapping
 const MONTHS: Record<string, number> = {
   Jan: 0,
@@ -78,18 +75,6 @@ function parseTimestamp(dateStr: string, timeStr: string): Date {
   )
 }
 
-/**
- * Extract all URLs from message content.
- */
-function extractUrls(content: string): string[] {
-  const matches = content.match(URL_PATTERN)
-  if (!matches) {
-    return []
-  }
-
-  return matches.map((url) => url.replace(/[.,;:!?]+$/, '')).filter((url) => url.length > 0)
-}
-
 interface MessageBuilder {
   timestamp: Date
   sender: string