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

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

import { MESSAGE_TYPES } from './index';
import type { Actor } from './index';
import type { TextEntity } from './text-entities';
import type { TelegramMessage } from './messages';
/**
 * All possible Telegram service event action types.
 *
 * These constants represent the different types of service messages
 * that Telegram can generate (non-user messages that indicate system events).
 *
 * @example
 * ```typescript
 * if (event.action === EVENT_ACTIONS.PHONE_CALL) {
 *   // Handle phone call event
 * }
 * ```
 */
export declare const EVENT_ACTIONS: {
    /** Phone call initiated between users */
    readonly PHONE_CALL: "phone_call";
    /** Group voice/video call started */
    readonly GROUP_CALL: "group_call";
    /** Group call scheduled for future time */
    readonly GROUP_CALL_SCHEDULED: "group_call_scheduled";
    /** Users invited to group/channel */
    readonly INVITE_MEMBERS: "invite_members";
    /** Users removed from group/channel */
    readonly REMOVE_MEMBERS: "remove_members";
    /** Users invited to ongoing group call */
    readonly INVITE_TO_GROUP_CALL: "invite_to_group_call";
    /** User joined group via invite link */
    readonly JOIN_GROUP_BY_LINK: "join_group_by_link";
    /** User joined group via admin approval */
    readonly JOIN_GROUP_BY_REQUEST: "join_group_by_request";
    /** New group chat created */
    readonly CREATE_GROUP: "create_group";
    /** New channel created */
    readonly CREATE_CHANNEL: "create_channel";
    /** Group title/name changed */
    readonly EDIT_GROUP_TITLE: "edit_group_title";
    /** Group photo/avatar changed */
    readonly EDIT_GROUP_PHOTO: "edit_group_photo";
    /** Group migrated from basic to supergroup */
    readonly MIGRATE_FROM_GROUP: "migrate_from_group";
    /** Group converted to supergroup */
    readonly MIGRATE_TO_SUPERGROUP: "migrate_to_supergroup";
    /** Message pinned in chat */
    readonly PIN_MESSAGE: "pin_message";
    /** Premium subscription gifted to user */
    readonly SEND_PREMIUM_GIFT: "send_premium_gift";
    /** Paid message refund processed */
    readonly PAID_MESSAGES_REFUND: "paid_messages_refund";
    /** Game score achieved */
    readonly SCORE_IN_GAME: "score_in_game";
    /** Chat history cleared */
    readonly CLEAR_HISTORY: "clear_history";
    /** Screenshot taken (secret chat) */
    readonly TAKE_SCREENSHOT: "take_screenshot";
};
/**
 * Union type of all possible event action values.
 *
 * @example
 * ```typescript
 * const processEvent = (action: EventAction) => {
 *   // TypeScript knows all possible action values
 * }
 * ```
 */
export type EventAction = typeof EVENT_ACTIONS[keyof typeof EVENT_ACTIONS];
/**
 * Possible reasons why a call was terminated.
 * Used with phone calls and group calls to indicate how they ended.
 */
export declare const CALL_DISCARD_REASONS: readonly ["hangup", "missed", "busy"];
/**
 * Union type for call termination reasons.
 *
 * @example
 * ```typescript
 * if (callEvent.discardReason === 'missed') {
 *   // Handle missed call
 * }
 * ```
 */
export type CallDiscardReason = typeof CALL_DISCARD_REASONS[number];
/**
 * Actions related to voice/video calls.
 * Convenience array for type checking and filtering call-related events.
 */
export declare const CALL_ACTIONS: readonly ["phone_call", "group_call"];
/**
 * Actions related to group/channel membership changes.
 * Includes invites, removals, and different ways users can join.
 */
export declare const MEMBERSHIP_ACTIONS: readonly ["invite_members", "remove_members", "invite_to_group_call", "join_group_by_link", "join_group_by_request"];
/**
 * Actions related to creating new groups or channels.
 * Used when new chat entities are established.
 */
export declare const CREATION_ACTIONS: readonly ["create_group", "create_channel"];
/**
 * Actions related to modifying existing group properties.
 * Includes title changes, photo updates, and migration events.
 */
export declare const GROUP_CHANGE_ACTIONS: readonly ["edit_group_title", "edit_group_photo", "migrate_from_group", "migrate_to_supergroup"];
/**
 * Base interface for all Telegram service events.
 * Contains common properties shared by all event types.
 *
 * @example
 * ```typescript
 * const processBaseEvent = (event: BaseEvent) => {
 *   console.log(`Event ${event.id} at ${event.date}`)
 * }
 * ```
 */
export interface BaseEvent {
    /** Unique identifier for this event */
    id: number;
    /** Always 'service' for service messages/events */
    type: typeof MESSAGE_TYPES.SERVICE;
    /** When the event occurred */
    date: Date;
    /** Who initiated the event (may be undefined for system events) */
    actor: Actor | undefined;
    /** Text formatting entities if the event has displayable text */
    textEntities: TextEntity[];
}
/**
 * Event representing a voice or video call.
 * Includes information about call duration and how it ended.
 *
 * @example
 * ```typescript
 * if (event.discardReason === 'missed') {
 *   console.log(`Missed call lasting ${event.duration}s`)
 * }
 * ```
 */
export interface CallEvent extends BaseEvent {
    /** Type of call (phone_call or group_call) */
    action: typeof CALL_ACTIONS[number];
    /** How the call ended (undefined if ongoing or unknown) */
    discardReason: CallDiscardReason | undefined;
    /** Call duration in seconds (undefined if not available) */
    duration: number | undefined;
}
/**
 * Event for scheduled group calls.
 * Represents when a group call is scheduled for a future time.
 */
export interface CallScheduleEvent extends BaseEvent {
    /** Always 'group_call_scheduled' */
    action: typeof EVENT_ACTIONS.GROUP_CALL_SCHEDULED;
    /** When the call is scheduled for (undefined if not specified) */
    scheduleDate: Date | undefined;
}
/**
 * Event related to group/channel membership changes.
 * Covers inviting, removing, and users joining groups.
 *
 * @example
 * ```typescript
 * if (event.action === 'invite_members') {
 *   console.log(`${event.inviter} invited ${event.members.length} users`)
 * }
 * ```
 */
export interface MembershipEvent extends BaseEvent {
    /** Type of membership action */
    action: typeof MEMBERSHIP_ACTIONS[number];
    /** Who initiated the action (undefined for system actions) */
    inviter: string | undefined;
    /** List of users affected by the membership change */
    members: Actor[];
}
/**
 * Event for creating new groups or channels.
 * Contains information about initial members.
 */
export interface CreationEvent extends BaseEvent {
    /** Type of creation (create_group or create_channel) */
    action: typeof CREATION_ACTIONS[number];
    /** Initial members of the created group/channel */
    members: Actor[];
}
/**
 * Event for changes to group properties.
 * Includes title changes, photo updates, and migrations.
 *
 * @example
 * ```typescript
 * if (event.action === 'edit_group_title') {
 *   // Group title was changed
 * }
 * ```
 */
export interface GroupChangeEvent extends BaseEvent {
    /** Type of group change */
    action: typeof GROUP_CHANGE_ACTIONS[number];
}
/**
 * Event for message pinning in a chat.
 * References the specific message that was pinned.
 */
export interface MessagePinEvent extends BaseEvent {
    /** Always 'pin_message' */
    action: typeof EVENT_ACTIONS.PIN_MESSAGE;
    /** ID of the message that was pinned */
    messageId: number;
}
/**
 * Event for Telegram Premium gift transactions.
 * Contains cost and duration information.
 *
 * @example
 * ```typescript
 * console.log(`Premium gift: ${event.months} months for ${event.cost} stars`)
 * ```
 */
export interface SendPremiumGiftEvent extends BaseEvent {
    /** Always 'send_premium_gift' */
    action: typeof EVENT_ACTIONS.SEND_PREMIUM_GIFT;
    /** Cost of the gift in Telegram Stars */
    cost: number;
    /** Duration of premium subscription in months */
    months: number;
}
/**
 * Event for paid message refunds.
 * Contains information about refunded messages and stars.
 */
export interface PaidMessagesRefundEvent extends BaseEvent {
    /** Always 'paid_messages_refund' */
    action: typeof EVENT_ACTIONS.PAID_MESSAGES_REFUND;
    /** Number of messages that were refunded */
    messagesCount: number;
    /** Number of Telegram Stars refunded */
    starsCount: number;
}
/**
 * Event for game score achievements.
 * Links to the original game message and records the score.
 *
 * @example
 * ```typescript
 * console.log(`New high score: ${event.score} in game ${event.gameMessageId}`)
 * ```
 */
export interface GameScoreEvent extends BaseEvent {
    /** Always 'score_in_game' */
    action: typeof EVENT_ACTIONS.SCORE_IN_GAME;
    /** The score that was achieved */
    score: number;
    /** ID of the message containing the game */
    gameMessageId: number;
}
/**
 * Event for chat history clearing.
 * Indicates when chat history was deleted.
 */
export interface ClearHistoryEvent extends BaseEvent {
    /** Always 'clear_history' */
    action: typeof EVENT_ACTIONS.CLEAR_HISTORY;
}
/**
 * Event for screenshot notifications in secret chats.
 * Indicates when a participant took a screenshot.
 */
export interface ScreenshotEvent extends BaseEvent {
    /** Always 'take_screenshot' */
    action: typeof EVENT_ACTIONS.TAKE_SCREENSHOT;
}
/**
 * Union type representing all possible Telegram service events.
 *
 * Service events are system-generated messages that indicate actions
 * like calls, membership changes, group modifications, etc.
 *
 * Use the provided type guards to narrow down to specific event types:
 *
 * @example
 * ```typescript
 * const processEvent = (event: TelegramEvent) => {
 *   if (isCallEvent(event)) {
 *     // TypeScript knows this is CallEvent
 *     console.log(`Call duration: ${event.duration}s`)
 *   } else if (isMembershipEvent(event)) {
 *     // TypeScript knows this is MembershipEvent
 *     console.log(`${event.members.length} members affected`)
 *   }
 * }
 * ```
 */
export type TelegramEvent = CallEvent | CallScheduleEvent | MembershipEvent | CreationEvent | GroupChangeEvent | MessagePinEvent | SendPremiumGiftEvent | PaidMessagesRefundEvent | GameScoreEvent | ClearHistoryEvent | ScreenshotEvent;
/**
 * Type guard to check if a message or event is a TelegramEvent (service message).
 *
 * Service events represent system actions rather than user messages.
 * This is the primary way to distinguish between regular messages and events.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a TelegramEvent, false otherwise
 *
 * @example
 * ```typescript
 * if (isEvent(item)) {
 *   // Handle service event
 *   console.log(`Service event: ${item.action}`)
 * } else {
 *   // Handle regular message
 *   console.log(`User message: ${item.text}`)
 * }
 * ```
 */
export declare function isEvent(msg: TelegramMessage | TelegramEvent): msg is TelegramEvent;
/**
 * Type guard to check if an event is a CallEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a CallEvent, false otherwise
 */
export declare function isCallEvent(msg: TelegramMessage | TelegramEvent): msg is CallEvent;
/**
 * Type guard to check if an event is a CallScheduleEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a CallScheduleEvent, false otherwise
 */
export declare function isCallScheduleEvent(msg: TelegramMessage | TelegramEvent): msg is CallScheduleEvent;
/**
 * Type guard to check if an event is a MembershipEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a MembershipEvent, false otherwise
 */
export declare function isMembershipEvent(msg: TelegramMessage | TelegramEvent): msg is MembershipEvent;
/**
 * Type guard to check if an event is a CreationEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a CreationEvent, false otherwise
 */
export declare function isCreationEvent(msg: TelegramMessage | TelegramEvent): msg is CreationEvent;
/**
 * Type guard to check if an event is a GroupChangeEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a GroupChangeEvent, false otherwise
 */
export declare function isEditGroupEvent(msg: TelegramMessage | TelegramEvent): msg is GroupChangeEvent;
/**
 * Type guard to check if an event is a MessagePinEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a MessagePinEvent, false otherwise
 */
export declare function isMessagePinEvent(msg: TelegramMessage | TelegramEvent): msg is MessagePinEvent;
/**
 * Type guard to check if an event is a SendPremiumGiftEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a SendPremiumGiftEvent, false otherwise
 */
export declare function isSendPremiumGiftEvent(msg: TelegramMessage | TelegramEvent): msg is SendPremiumGiftEvent;
/**
 * Type guard to check if an event is a PaidMessagesRefundEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a PaidMessagesRefundEvent, false otherwise
 */
export declare function isPaidMessagesRefundEvent(msg: TelegramMessage | TelegramEvent): msg is PaidMessagesRefundEvent;
/**
 * Type guard to check if an event is a GameScoreEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a GameScoreEvent, false otherwise
 */
export declare function isScoreInGameEvent(msg: TelegramMessage | TelegramEvent): msg is GameScoreEvent;
/**
 * Type guard to check if an event is a ClearHistoryEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a ClearHistoryEvent, false otherwise
 */
export declare function isClearHistoryEvent(msg: TelegramMessage | TelegramEvent): msg is ClearHistoryEvent;
/**
 * Type guard to check if an event is a ScreenshotEvent.
 *
 * @param msg - The message or event to check
 * @returns True if the input is a ScreenshotEvent, false otherwise
 */
export declare function isScreenshotEvent(msg: TelegramMessage | TelegramEvent): msg is ScreenshotEvent;
//# sourceMappingURL=events.d.ts.map