@stack.thefennec.dev/telegram-export-parser/dist/types/text-entities.d.ts

TypeScript library for parsing Telegram Desktop's data export with full type safety

import { Actor, ExportedFile } from './index';
/**
 * Comprehensive constants for all Telegram text entity types.
 *
 * Text entities represent rich formatting, links, mentions, and special
 * elements within message text. Each entity has a specific type that
 * determines how it should be rendered and what additional data it contains.
 *
 * @example
 * ```typescript
 * // Check entity types
 * if (entity.type === TEXT_ENTITY_TYPES.BOLD) {
 *   console.log('Bold text:', entity.text)
 * }
 *
 * // Render as Markdown
 * const markdown = entity.toMarkdown() // "**bold text**"
 * ```
 */
export declare const TEXT_ENTITY_TYPES: {
    /** Unformatted plain text segment */
    readonly PLAIN: "plain";
    /** Bold text formatting (**text**) */
    readonly BOLD: "bold";
    /** Italic text formatting (*text*) */
    readonly ITALIC: "italic";
    /** Strikethrough text formatting (~~text~~) */
    readonly STRIKETHROUGH: "strikethrough";
    /** Underlined text formatting */
    readonly UNDERLINE: "underline";
    /** Bank card number formatting (for security) */
    readonly BANK_CARD: "bank_card";
    /** Spoiler text that's initially hidden */
    readonly SPOILER: "spoiler";
    /** Inline code formatting (`code`) */
    readonly CODE: "code";
    /** Code block formatting with optional language */
    readonly PRE: "pre";
    /** Clickable text link with custom URL */
    readonly TEXT_LINK: "text_link";
    /** Auto-detected URL link */
    readonly LINK: "link";
    /** Hashtag (#hashtag) */
    readonly HASHTAG: "hashtag";
    /** Stock ticker/cashtag ($TICKER) */
    readonly CASHTAG: "cashtag";
    /** Bot command (/command) */
    readonly BOT_COMMAND: "bot_command";
    /** Email address (auto-detected) */
    readonly EMAIL: "email";
    /** Phone number (auto-detected) */
    readonly PHONE: "phone";
    /** Username mention (@username) */
    readonly MENTION: "mention";
    /** User mention by display name */
    readonly MENTION_NAME: "mention_name";
    /** Custom emoji or sticker */
    readonly CUSTOM_EMOJI: "custom_emoji";
    /** Block quote formatting */
    readonly BLOCKQUOTE: "blockquote";
};
/**
 * Plain text entity type - no special formatting or behavior.
 */
export type PlainTextEntityType = typeof TEXT_ENTITY_TYPES.PLAIN;
/**
 * Text formatting entity types that affect visual appearance.
 *
 * These entities change how text is displayed (bold, italic, etc.)
 * but don't add interactive behavior or external references.
 *
 * @example
 * ```typescript
 * const formatText = (entity: FormattedTextEntity): string => {
 *   switch (entity.type) {
 *     case 'bold': return `**${entity.text}**`
 *     case 'italic': return `*${entity.text}*`
 *     case 'strikethrough': return `~~${entity.text}~~`
 *   }
 * }
 * ```
 */
export type FormattedTextEntityType = typeof TEXT_ENTITY_TYPES.BOLD | typeof TEXT_ENTITY_TYPES.ITALIC | typeof TEXT_ENTITY_TYPES.STRIKETHROUGH | typeof TEXT_ENTITY_TYPES.UNDERLINE | typeof TEXT_ENTITY_TYPES.BANK_CARD;
/**
 * Spoiler text entity type - text that's initially hidden.
 */
export type SpoilerTextEntityType = typeof TEXT_ENTITY_TYPES.SPOILER;
/**
 * Code entity types for programming code and technical content.
 *
 * Includes both inline code snippets and multi-line code blocks
 * with optional syntax highlighting.
 *
 * @example
 * ```typescript
 * if (entity.type === 'pre' && entity.language === 'javascript') {
 *   // Apply JavaScript syntax highlighting
 * }
 * ```
 */
export type CodeTextEntityType = typeof TEXT_ENTITY_TYPES.CODE | typeof TEXT_ENTITY_TYPES.PRE;
/**
 * Link entity types that reference external URLs or special actions.
 *
 * These entities make text clickable and can open URLs, trigger
 * commands, or perform other interactive actions.
 *
 * @example
 * ```typescript
 * const handleLinkClick = (entity: LinkTextEntity) => {
 *   if (entity.type === 'bot_command') {
 *     executeCommand(entity.text)
 *   } else if (entity.url) {
 *     window.open(entity.url)
 *   }
 * }
 * ```
 */
export type LinkTextEntityType = typeof TEXT_ENTITY_TYPES.TEXT_LINK | typeof TEXT_ENTITY_TYPES.LINK | typeof TEXT_ENTITY_TYPES.HASHTAG | typeof TEXT_ENTITY_TYPES.CASHTAG | typeof TEXT_ENTITY_TYPES.BOT_COMMAND | typeof TEXT_ENTITY_TYPES.EMAIL | typeof TEXT_ENTITY_TYPES.PHONE;
/**
 * Mention entity types that reference specific users.
 *
 * These entities link to Telegram users either by username
 * or by display name with user ID.
 *
 * @example
 * ```typescript
 * const getUserFromMention = (entity: MentionTextEntity): Actor => {
 *   return entity.mention // Full Actor object with user details
 * }
 * ```
 */
export type MentionTextEntityType = typeof TEXT_ENTITY_TYPES.MENTION | typeof TEXT_ENTITY_TYPES.MENTION_NAME;
/**
 * Custom emoji entity type for premium emoji and stickers.
 */
export type CustomEmojiTextEntityType = typeof TEXT_ENTITY_TYPES.CUSTOM_EMOJI;
/**
 * Block quote entity type for quoted text sections.
 */
export type QuoteTextEntityType = typeof TEXT_ENTITY_TYPES.BLOCKQUOTE;
/**
 * Base interface for all text entities with rendering capabilities.
 *
 * All text entities share common properties and methods for converting
 * their content to different output formats like Markdown and HTML.
 *
 * @example
 * ```typescript
 * const renderEntity = (entity: BaseTextEntity): string => {
 *   // Get plain text
 *   console.log('Text:', entity.text)
 *
 *   // Render as Markdown
 *   console.log('Markdown:', entity.toMarkdown())
 *
 *   // Render as HTML
 *   console.log('HTML:', entity.toHTML())
 * }
 * ```
 */
export interface BaseTextEntity {
    /** The raw text content of this entity */
    text: string;
    /** Convert this entity to Markdown format */
    toMarkdown(): string;
    /** Convert this entity to HTML format */
    toHTML(): string;
}
/**
 * Plain text entity without any special formatting.
 *
 * Represents regular text segments that don't have formatting,
 * links, or other special behaviors.
 *
 * @example
 * ```typescript
 * const plainEntity: PlainTextEntity = {
 *   type: 'plain',
 *   text: 'Hello world',
 *   toMarkdown: () => 'Hello world',
 *   toHTML: () => 'Hello world'
 * }
 * ```
 */
export interface PlainTextEntity extends BaseTextEntity {
    type: PlainTextEntityType;
}
/**
 * Text entity with visual formatting (bold, italic, etc.).
 *
 * Represents text that has visual styling applied but no
 * interactive behavior or external references.
 *
 * @example
 * ```typescript
 * // Bold text entity
 * const boldEntity: FormattedTextEntity = {
 *   type: 'bold',
 *   text: 'Important',
 *   toMarkdown: () => '**Important**',
 *   toHTML: () => '<strong>Important</strong>'
 * }
 * ```
 */
export interface FormattedTextEntity extends BaseTextEntity {
    type: FormattedTextEntityType;
}
/**
 * Spoiler text entity that's initially hidden from view.
 *
 * Spoiler text is blurred or hidden by default and requires
 * user interaction to reveal the content.
 *
 * @example
 * ```typescript
 * const spoilerEntity: SpoilerTextEntity = {
 *   type: 'spoiler',
 *   text: 'Secret information',
 *   toMarkdown: () => '||Secret information||',
 *   toHTML: () => '<span class="spoiler">Secret information</span>'
 * }
 * ```
 */
export interface SpoilerTextEntity extends BaseTextEntity {
    type: SpoilerTextEntityType;
}
/**
 * Code entity for programming code and technical content.
 *
 * Supports both inline code (`code`) and code blocks with
 * optional syntax highlighting based on language.
 *
 * @example
 * ```typescript
 * const codeEntity: CodeTextEntity = {
 *   type: 'pre',
 *   text: 'const x = 42;',
 *   language: 'javascript',
 *   toMarkdown: () => '```javascript\nconst x = 42;\n```',
 *   toHTML: () => '<pre><code class="language-javascript">const x = 42;</code></pre>'
 * }
 * ```
 */
export interface CodeTextEntity extends BaseTextEntity {
    type: CodeTextEntityType;
    /** Programming language for syntax highlighting (undefined for plain code) */
    language: string | undefined;
}
/**
 * Link entity that references URLs or performs actions.
 *
 * Includes various types of clickable links from web URLs to
 * bot commands, hashtags, and contact information.
 *
 * @example
 * ```typescript
 * const linkEntity: LinkTextEntity = {
 *   type: 'text_link',
 *   text: 'Click here',
 *   url: 'https://example.com',
 *   toMarkdown: () => '[Click here](https://example.com)',
 *   toHTML: () => '<a href="https://example.com">Click here</a>'
 * }
 * ```
 */
export interface LinkTextEntity extends BaseTextEntity {
    type: LinkTextEntityType;
    /** Target URL or action identifier */
    url: string;
}
/**
 * Mention entity that references a Telegram user.
 *
 * Contains full Actor information for the mentioned user,
 * enabling rich user profiles and interaction.
 *
 * @example
 * ```typescript
 * const mentionEntity: MentionTextEntity = {
 *   type: 'mention',
 *   text: '@username',
 *   mention: {
 *     id: 123456789,
 *     type: 'user',
 *     username: 'username',
 *     displayName: 'John Doe'
 *   },
 *   toMarkdown: () => '@username',
 *   toHTML: () => '<a href="https://t.me/username">@username</a>'
 * }
 * ```
 */
export interface MentionTextEntity extends BaseTextEntity {
    type: MentionTextEntityType;
    /** Complete user information for the mentioned user */
    mention: Actor;
}
/**
 * Custom emoji entity for premium emoji and animated stickers.
 *
 * References custom emoji files that can be displayed as
 * enhanced alternatives to standard Unicode emoji.
 *
 * @example
 * ```typescript
 * const emojiEntity: CustomEmojiTextEntity = {
 *   type: 'custom_emoji',
 *   text: '🎉',
 *   documentURL: new URL('https://cdn.example.com/emoji/party.webp'),
 *   toMarkdown: () => '🎉',
 *   toHTML: () => '<img src="https://cdn.example.com/emoji/party.webp" alt="🎉" class="custom-emoji">'
 * }
 * ```
 */
export interface CustomEmojiTextEntity extends BaseTextEntity {
    type: CustomEmojiTextEntityType;
    /** URL or file reference to the custom emoji image */
    documentURL: ExportedFile;
}
/**
 * Block quote entity for quoted text sections.
 *
 * Represents text that should be rendered as a quotation,
 * with optional collapsed state for long quotes.
 *
 * @example
 * ```typescript
 * const quoteEntity: QuoteTextEntity = {
 *   type: 'blockquote',
 *   text: 'This is a quote from someone important.',
 *   collapsed: false,
 *   toMarkdown: () => '> This is a quote from someone important.',
 *   toHTML: () => '<blockquote>This is a quote from someone important.</blockquote>'
 * }
 * ```
 */
export interface QuoteTextEntity extends BaseTextEntity {
    type: QuoteTextEntityType;
    /** Whether the quote is initially collapsed (for long quotes) */
    collapsed: boolean;
}
/**
 * Array of all formatting entity types for easy iteration and validation.
 * Used by type guards and processing functions.
 */
export declare const FORMATTED_TEXT_ENTITY_TYPES: readonly ["bold", "italic", "strikethrough", "underline", "bank_card"];
/**
 * Array of all code entity types for easy iteration and validation.
 * Used by type guards and processing functions.
 */
export declare const CODE_TEXT_ENTITY_TYPES: readonly ["code", "pre"];
/**
 * Array of all link entity types for easy iteration and validation.
 * Used by type guards and processing functions.
 */
export declare const LINK_TEXT_ENTITY_TYPES: readonly ["text_link", "link", "hashtag", "cashtag", "bot_command", "email", "phone"];
/**
 * Array of all mention entity types for easy iteration and validation.
 * Used by type guards and processing functions.
 */
export declare const MENTION_TEXT_ENTITY_TYPES: readonly ["mention", "mention_name"];
/**
 * Union type for all possible text entity type strings.
 *
 * Used for type checking and validation of raw entity data
 * before converting to specific entity objects.
 */
export type TextEntityType = PlainTextEntityType | FormattedTextEntityType | SpoilerTextEntityType | CodeTextEntityType | LinkTextEntityType | MentionTextEntityType | CustomEmojiTextEntityType | QuoteTextEntityType;
/**
 * Union type representing all possible text entity objects.
 *
 * This is the main type used throughout the system for text processing.
 * Use type guards to narrow down to specific entity types for proper handling.
 *
 * @example
 * ```typescript
 * const processTextEntities = (entities: TextEntity[]): string => {
 *   return entities.map(entity => {
 *     if (isLinkTextEntity(entity)) {
 *       return `<a href="${entity.url}">${entity.text}</a>`
 *     } else if (isFormattedTextEntity(entity)) {
 *       return entity.toHTML()
 *     } else {
 *       return entity.text
 *     }
 *   }).join('')
 * }
 * ```
 */
export type TextEntity = PlainTextEntity | FormattedTextEntity | SpoilerTextEntity | CodeTextEntity | LinkTextEntity | MentionTextEntity | CustomEmojiTextEntity | QuoteTextEntity;
/**
 * Type guard to check if a text entity is plain text without formatting.
 *
 * @param entity - The text entity to check
 * @returns True if the entity is plain text
 *
 * @example
 * ```typescript
 * if (isPlainTextEntity(entity)) {
 *   // No special processing needed, just use entity.text
 *   console.log(entity.text)
 * }
 * ```
 */
export declare function isPlainTextEntity(entity: TextEntity): entity is PlainTextEntity;
/**
 * Type guard to check if a text entity has visual formatting.
 *
 * Includes bold, italic, strikethrough, underline, and bank card formatting.
 *
 * @param entity - The text entity to check
 * @returns True if the entity has formatting
 *
 * @example
 * ```typescript
 * if (isFormattedTextEntity(entity)) {
 *   // Apply visual styling based on entity.type
 *   const styled = entity.toHTML() // <strong>text</strong>, <em>text</em>, etc.
 *   console.log(styled)
 * }
 * ```
 */
export declare function isFormattedTextEntity(entity: TextEntity): entity is FormattedTextEntity;
/**
 * Type guard to check if a text entity is spoiler text.
 *
 * Spoiler text should be initially hidden and require user interaction to reveal.
 *
 * @param entity - The text entity to check
 * @returns True if the entity is spoiler text
 *
 * @example
 * ```typescript
 * if (isSpoilerTextEntity(entity)) {
 *   // Render with spoiler styling
 *   console.log(`<span class="spoiler" onclick="reveal()">${entity.text}</span>`)
 * }
 * ```
 */
export declare function isSpoilerTextEntity(entity: TextEntity): entity is SpoilerTextEntity;
/**
 * Type guard to check if a text entity contains code.
 *
 * Includes both inline code and code blocks with optional syntax highlighting.
 *
 * @param entity - The text entity to check
 * @returns True if the entity contains code
 *
 * @example
 * ```typescript
 * if (isCodeTextEntity(entity)) {
 *   if (entity.type === 'pre' && entity.language) {
 *     // Apply syntax highlighting for the specified language
 *     console.log(`Code block in ${entity.language}: ${entity.text}`)
 *   } else {
 *     // Render as inline or plain code
 *     console.log(`Code: ${entity.text}`)
 *   }
 * }
 * ```
 */
export declare function isCodeTextEntity(entity: TextEntity): entity is CodeTextEntity;
/**
 * Type guard to check if a text entity is a clickable link.
 *
 * Includes web links, bot commands, hashtags, contact info, and more.
 *
 * @param entity - The text entity to check
 * @returns True if the entity is a link
 *
 * @example
 * ```typescript
 * if (isLinkTextEntity(entity)) {
 *   switch (entity.type) {
 *     case 'text_link':
 *       return `<a href="${entity.url}">${entity.text}</a>`
 *     case 'bot_command':
 *       return `<button onclick="executeCommand('${entity.text}')">${entity.text}</button>`
 *     case 'hashtag':
 *       return `<a href="/search?q=${encodeURIComponent(entity.text)}">${entity.text}</a>`
 *     default:
 *       return `<a href="${entity.url}">${entity.text}</a>`
 *   }
 * }
 * ```
 */
export declare function isLinkTextEntity(entity: TextEntity): entity is LinkTextEntity;
/**
 * Type guard to check if a text entity mentions a user.
 *
 * Contains full user information through the mention property.
 *
 * @param entity - The text entity to check
 * @returns True if the entity mentions a user
 *
 * @example
 * ```typescript
 * if (isMentionTextEntity(entity)) {
 *   const user = entity.mention
 *   console.log(`Mentioned user: ${user.displayName} (@${user.username})`)
 *
 *   // Render as user profile link
 *   const userUrl = user.username ? `https://t.me/${user.username}` : '#'
 *   return `<a href="${userUrl}" class="user-mention">${entity.text}</a>`
 * }
 * ```
 */
export declare function isMentionTextEntity(entity: TextEntity): entity is MentionTextEntity;
/**
 * Type guard to check if a text entity is a custom emoji.
 *
 * Custom emojis have associated image files for enhanced display.
 *
 * @param entity - The text entity to check
 * @returns True if the entity is a custom emoji
 *
 * @example
 * ```typescript
 * if (isCustomEmojiTextEntity(entity)) {
 *   if (entity.documentURL) {
 *     // Display custom emoji image
 *     console.log(`<img src="${entity.documentURL}" alt="${entity.text}" class="custom-emoji">`)
 *   } else {
 *     // Fallback to text representation
 *     console.log(entity.text)
 *   }
 * }
 * ```
 */
export declare function isCustomEmojiTextEntity(entity: TextEntity): entity is CustomEmojiTextEntity;
/**
 * Type guard to check if a text entity is a block quote.
 *
 * Block quotes should be rendered with special styling and may be collapsible.
 *
 * @param entity - The text entity to check
 * @returns True if the entity is a block quote
 *
 * @example
 * ```typescript
 * if (isQuoteTextEntity(entity)) {
 *   const collapseClass = entity.collapsed ? 'collapsed' : 'expanded'
 *   console.log(`<blockquote class="${collapseClass}">${entity.text}</blockquote>`)
 * }
 * ```
 */
export declare function isQuoteTextEntity(entity: TextEntity): entity is QuoteTextEntity;
//# sourceMappingURL=text-entities.d.ts.map