@icanseeuanywhere/telekaf 4.16.3

package/src/core/types/rich-message.ts

@@ -0,0 +1,474 @@
+/**
+ * Telegram Bot API 10.1 — Rich Messages
+ * https://core.telegram.org/bots/api#june-11-2026
+ */
+
+// ---------------------------------------------------------------------------
+// RichText — inline text elements
+// ---------------------------------------------------------------------------
+
+export interface RichTextPlain {
+  type: 'plain'
+  text: string
+}
+
+export interface RichTextBold {
+  type: 'bold'
+  text: RichText
+}
+
+export interface RichTextItalic {
+  type: 'italic'
+  text: RichText
+}
+
+export interface RichTextUnderline {
+  type: 'underline'
+  text: RichText
+}
+
+export interface RichTextStrikethrough {
+  type: 'strikethrough'
+  text: RichText
+}
+
+export interface RichTextSpoiler {
+  type: 'spoiler'
+  text: RichText
+}
+
+export interface RichTextDateTime {
+  type: 'date_time'
+  unix_time: number
+}
+
+export interface RichTextMention {
+  type: 'mention'
+  text: RichText
+  user_id?: number
+  username?: string
+}
+
+export interface RichTextSubscript {
+  type: 'subscript'
+  text: RichText
+}
+
+export interface RichTextSuperscript {
+  type: 'superscript'
+  text: RichText
+}
+
+export interface RichTextMarked {
+  type: 'marked'
+  text: RichText
+}
+
+export interface RichTextCode {
+  type: 'code'
+  text: RichText
+  language?: string
+}
+
+export interface RichTextCustomEmoji {
+  type: 'custom_emoji'
+  custom_emoji_id: string
+}
+
+export interface RichTextMathematicalExpression {
+  type: 'mathematical_expression'
+  expression: string
+}
+
+export interface RichTextUrl {
+  type: 'url'
+  href: string
+  text: RichText
+}
+
+export interface RichTextEmailAddress {
+  type: 'email_address'
+  email: string
+  text?: RichText
+}
+
+export interface RichTextPhoneNumber {
+  type: 'phone_number'
+  phone_number: string
+  text?: RichText
+}
+
+export interface RichTextBankCardNumber {
+  type: 'bank_card_number'
+  bank_card_number: string
+  text?: RichText
+}
+
+export interface RichTextHashtag {
+  type: 'hashtag'
+  hashtag: string
+}
+
+export interface RichTextCashtag {
+  type: 'cashtag'
+  cashtag: string
+}
+
+export interface RichTextBotCommand {
+  type: 'bot_command'
+  command: string
+  bot?: string
+}
+
+export interface RichTextAnchor {
+  type: 'anchor'
+  name: string
+}
+
+export interface RichTextAnchorLink {
+  type: 'anchor_link'
+  name: string
+  text: RichText
+}
+
+export interface RichTextReference {
+  type: 'reference'
+  reference_id: number
+}
+
+export interface RichTextReferenceLink {
+  type: 'reference_link'
+  reference_id: number
+  text: RichText
+}
+
+/** Union of all inline rich text element types. */
+export type RichText =
+  | RichTextPlain
+  | RichTextBold
+  | RichTextItalic
+  | RichTextUnderline
+  | RichTextStrikethrough
+  | RichTextSpoiler
+  | RichTextDateTime
+  | RichTextMention
+  | RichTextSubscript
+  | RichTextSuperscript
+  | RichTextMarked
+  | RichTextCode
+  | RichTextCustomEmoji
+  | RichTextMathematicalExpression
+  | RichTextUrl
+  | RichTextEmailAddress
+  | RichTextPhoneNumber
+  | RichTextBankCardNumber
+  | RichTextHashtag
+  | RichTextCashtag
+  | RichTextBotCommand
+  | RichTextAnchor
+  | RichTextAnchorLink
+  | RichTextReference
+  | RichTextReferenceLink
+
+// ---------------------------------------------------------------------------
+// RichBlock — block-level elements
+// ---------------------------------------------------------------------------
+
+/** Caption attached to a media block. */
+export interface RichBlockCaption {
+  type: 'caption'
+  texts: RichText[]
+}
+
+/** A single cell inside a RichBlockTable. */
+export interface RichBlockTableCell {
+  type: 'table_cell'
+  content: RichBlock[]
+  colspan?: number
+  rowspan?: number
+  is_header?: boolean
+  align?: 'left' | 'center' | 'right'
+}
+
+/** A single item inside a RichBlockList. */
+export interface RichBlockListItem {
+  type: 'list_item'
+  content: RichBlock[]
+}
+
+export interface RichBlockParagraph {
+  type: 'paragraph'
+  texts: RichText[]
+}
+
+export interface RichBlockSectionHeading {
+  type: 'section_heading'
+  texts: RichText[]
+  level: 1 | 2 | 3 | 4 | 5 | 6
+}
+
+export interface RichBlockPreformatted {
+  type: 'preformatted'
+  text: string
+  language?: string
+}
+
+export interface RichBlockFooter {
+  type: 'footer'
+  texts: RichText[]
+}
+
+export interface RichBlockDivider {
+  type: 'divider'
+}
+
+export interface RichBlockMathematicalExpression {
+  type: 'mathematical_expression'
+  expression: string
+}
+
+export interface RichBlockAnchor {
+  type: 'anchor'
+  name: string
+}
+
+export interface RichBlockList {
+  type: 'list'
+  is_ordered: boolean
+  items: RichBlockListItem[]
+}
+
+export interface RichBlockBlockQuotation {
+  type: 'block_quotation'
+  blocks: RichBlock[]
+}
+
+export interface RichBlockPullQuotation {
+  type: 'pull_quotation'
+  blocks: RichBlock[]
+  caption?: RichBlockCaption
+}
+
+export interface RichBlockCollage {
+  type: 'collage'
+  media: (RichBlockPhoto | RichBlockVideo | RichBlockAnimation)[]
+  caption?: RichBlockCaption
+}
+
+export interface RichBlockSlideshow {
+  type: 'slideshow'
+  media: (RichBlockPhoto | RichBlockVideo | RichBlockAnimation)[]
+  caption?: RichBlockCaption
+}
+
+export interface RichBlockTable {
+  type: 'table'
+  cells: RichBlockTableCell[][]
+  is_bordered?: boolean
+  is_striped?: boolean
+}
+
+export interface RichBlockDetails {
+  type: 'details'
+  header: RichText[]
+  blocks: RichBlock[]
+}
+
+export interface RichBlockMap {
+  type: 'map'
+  latitude: number
+  longitude: number
+  zoom?: number
+  caption?: RichBlockCaption
+}
+
+export interface RichBlockAnimation {
+  type: 'animation'
+  file_id: string
+  caption?: RichBlockCaption
+}
+
+export interface RichBlockAudio {
+  type: 'audio'
+  file_id: string
+  caption?: RichBlockCaption
+}
+
+export interface RichBlockPhoto {
+  type: 'photo'
+  file_id: string
+  caption?: RichBlockCaption
+}
+
+export interface RichBlockVideo {
+  type: 'video'
+  file_id: string
+  caption?: RichBlockCaption
+}
+
+export interface RichBlockVoiceNote {
+  type: 'voice_note'
+  file_id: string
+  caption?: RichBlockCaption
+}
+
+export interface RichBlockThinking {
+  type: 'thinking'
+  blocks: RichBlock[]
+}
+
+/** Union of all block-level rich message element types. */
+export type RichBlock =
+  | RichBlockParagraph
+  | RichBlockSectionHeading
+  | RichBlockPreformatted
+  | RichBlockFooter
+  | RichBlockDivider
+  | RichBlockMathematicalExpression
+  | RichBlockAnchor
+  | RichBlockList
+  | RichBlockBlockQuotation
+  | RichBlockPullQuotation
+  | RichBlockCollage
+  | RichBlockSlideshow
+  | RichBlockTable
+  | RichBlockDetails
+  | RichBlockMap
+  | RichBlockAnimation
+  | RichBlockAudio
+  | RichBlockPhoto
+  | RichBlockVideo
+  | RichBlockVoiceNote
+  | RichBlockThinking
+  | RichBlockCaption
+  | RichBlockTableCell
+  | RichBlockListItem
+
+// ---------------------------------------------------------------------------
+// RichMessage — top-level message container
+// ---------------------------------------------------------------------------
+
+/** A rich formatted message received from Telegram. */
+export interface RichMessage {
+  blocks: RichBlock[]
+  references?: RichText[]
+}
+
+/** Describes a rich message to send via sendRichMessage / sendRichMessageDraft. */
+export interface InputRichMessage {
+  blocks: RichBlock[]
+  references?: RichText[]
+}
+
+/** Can be used as InputMessageContent in inline, guest, and Web App queries. */
+export interface InputRichMessageContent {
+  rich_message: InputRichMessage
+}
+
+// ---------------------------------------------------------------------------
+// Helper builder — fluent API for constructing InputRichMessage
+// ---------------------------------------------------------------------------
+
+export class RichMessageBuilder {
+  private readonly _blocks: RichBlock[] = []
+  private readonly _references: RichText[] = []
+
+  paragraph(...texts: RichText[]) {
+    this._blocks.push({ type: 'paragraph', texts })
+    return this
+  }
+
+  heading(level: 1 | 2 | 3 | 4 | 5 | 6, ...texts: RichText[]) {
+    this._blocks.push({ type: 'section_heading', texts, level })
+    return this
+  }
+
+  preformatted(text: string, language?: string) {
+    this._blocks.push({ type: 'preformatted', text, language })
+    return this
+  }
+
+  divider() {
+    this._blocks.push({ type: 'divider' })
+    return this
+  }
+
+  list(isOrdered: boolean, ...items: RichBlock[][]) {
+    this._blocks.push({
+      type: 'list',
+      is_ordered: isOrdered,
+      items: items.map((content) => ({ type: 'list_item', content })),
+    })
+    return this
+  }
+
+  blockQuote(...blocks: RichBlock[]) {
+    this._blocks.push({ type: 'block_quotation', blocks })
+    return this
+  }
+
+  thinking(...blocks: RichBlock[]) {
+    this._blocks.push({ type: 'thinking', blocks })
+    return this
+  }
+
+  photo(fileId: string, caption?: RichBlockCaption) {
+    this._blocks.push({ type: 'photo', file_id: fileId, caption })
+    return this
+  }
+
+  video(fileId: string, caption?: RichBlockCaption) {
+    this._blocks.push({ type: 'video', file_id: fileId, caption })
+    return this
+  }
+
+  audio(fileId: string, caption?: RichBlockCaption) {
+    this._blocks.push({ type: 'audio', file_id: fileId, caption })
+    return this
+  }
+
+  reference(text: RichText) {
+    const id = this._references.length + 1
+    this._references.push(text)
+    return id
+  }
+
+  build(): InputRichMessage {
+    return {
+      blocks: this._blocks,
+      ...(this._references.length ? { references: this._references } : {}),
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Static helpers for building RichText nodes
+// ---------------------------------------------------------------------------
+
+export const RT = {
+  plain: (text: string): RichTextPlain => ({ type: 'plain', text }),
+  bold: (text: RichText): RichTextBold => ({ type: 'bold', text }),
+  italic: (text: RichText): RichTextItalic => ({ type: 'italic', text }),
+  underline: (text: RichText): RichTextUnderline => ({ type: 'underline', text }),
+  strikethrough: (text: RichText): RichTextStrikethrough => ({ type: 'strikethrough', text }),
+  spoiler: (text: RichText): RichTextSpoiler => ({ type: 'spoiler', text }),
+  dateTime: (unixTime: number): RichTextDateTime => ({ type: 'date_time', unix_time: unixTime }),
+  mention: (text: RichText, userId?: number, username?: string): RichTextMention => ({ type: 'mention', text, user_id: userId, username }),
+  subscript: (text: RichText): RichTextSubscript => ({ type: 'subscript', text }),
+  superscript: (text: RichText): RichTextSuperscript => ({ type: 'superscript', text }),
+  marked: (text: RichText): RichTextMarked => ({ type: 'marked', text }),
+  code: (text: RichText, language?: string): RichTextCode => ({ type: 'code', text, language }),
+  customEmoji: (id: string): RichTextCustomEmoji => ({ type: 'custom_emoji', custom_emoji_id: id }),
+  math: (expression: string): RichTextMathematicalExpression => ({ type: 'mathematical_expression', expression }),
+  url: (href: string, text: RichText): RichTextUrl => ({ type: 'url', href, text }),
+  email: (email: string, text?: RichText): RichTextEmailAddress => ({ type: 'email_address', email, text }),
+  phone: (phoneNumber: string, text?: RichText): RichTextPhoneNumber => ({ type: 'phone_number', phone_number: phoneNumber, text }),
+  bankCard: (bankCardNumber: string, text?: RichText): RichTextBankCardNumber => ({ type: 'bank_card_number', bank_card_number: bankCardNumber, text }),
+  hashtag: (hashtag: string): RichTextHashtag => ({ type: 'hashtag', hashtag }),
+  cashtag: (cashtag: string): RichTextCashtag => ({ type: 'cashtag', cashtag }),
+  botCommand: (command: string, bot?: string): RichTextBotCommand => ({ type: 'bot_command', command, bot }),
+  anchor: (name: string): RichTextAnchor => ({ type: 'anchor', name }),
+  anchorLink: (name: string, text: RichText): RichTextAnchorLink => ({ type: 'anchor_link', name, text }),
+  reference: (referenceId: number): RichTextReference => ({ type: 'reference', reference_id: referenceId }),
+  referenceLink: (referenceId: number, text: RichText): RichTextReferenceLink => ({ type: 'reference_link', reference_id: referenceId, text }),
+} as const

package/src/core/types/typegram.ts

@@ -0,0 +1,55 @@
+import * as Typegram from '@telegraf/types'
+export * from './rich-message'
+
+// internal type provisions
+export * from '@telegraf/types/api'
+export * from '@telegraf/types/inline'
+export * from '@telegraf/types/manage'
+export * from '@telegraf/types/markup'
+export * from '@telegraf/types/message'
+export * from '@telegraf/types/methods'
+export * from '@telegraf/types/passport'
+export * from '@telegraf/types/payment'
+export * from '@telegraf/types/settings'
+export * from '@telegraf/types/update'
+
+// telegraf input file definition
+interface InputFileByPath {
+  source: string
+  filename?: string
+}
+interface InputFileByReadableStream {
+  source: NodeJS.ReadableStream
+  filename?: string
+}
+interface InputFileByBuffer {
+  source: Buffer
+  filename?: string
+}
+interface InputFileByURL {
+  url: string
+  filename?: string
+}
+export type InputFile =
+  | InputFileByPath
+  | InputFileByReadableStream
+  | InputFileByBuffer
+  | InputFileByURL
+
+export type Telegram = Typegram.ApiMethods<InputFile>
+
+export type Opts<M extends keyof Telegram> = Typegram.Opts<InputFile>[M]
+export type InputMedia = Typegram.InputMedia<InputFile>
+export type InputMediaPhoto = Typegram.InputMediaPhoto<InputFile>
+export type InputMediaVideo = Typegram.InputMediaVideo<InputFile>
+export type InputMediaAnimation = Typegram.InputMediaAnimation<InputFile>
+export type InputMediaAudio = Typegram.InputMediaAudio<InputFile>
+export type InputMediaDocument = Typegram.InputMediaDocument<InputFile>
+
+// tiny helper types
+export type ChatAction = Opts<'sendChatAction'>['action']
+
+/**
+ * Sending video notes by a URL is currently unsupported
+ */
+export type InputFileVideoNote = Exclude<InputFile, InputFileByURL>

package/src/filters.ts

@@ -0,0 +1,109 @@
+import type {
+  CallbackQuery,
+  CommonMessageBundle,
+  Message,
+  Update,
+} from '@telegraf/types'
+import { DistinctKeys, KeyedDistinct, Guarded } from './core/helpers/util'
+
+export type Filter<U extends Update> = (update: Update) => update is U
+
+export { Guarded }
+
+export type AllGuarded<Fs extends Filter<Update>[]> = Fs extends [
+  infer A,
+  ...infer B,
+]
+  ? B extends []
+    ? Guarded<A>
+    : // TS doesn't know otherwise that B is Filter[]
+    B extends Filter<Update>[]
+    ? Guarded<A> & AllGuarded<B>
+    : never
+  : never
+
+export const message =
+  <Ks extends DistinctKeys<Message>[]>(...keys: Ks) =>
+  (
+    update: Update
+  ): update is Update.MessageUpdate<KeyedDistinct<Message, Ks[number]>> => {
+    if (!('message' in update)) return false
+    for (const key of keys) {
+      if (!(key in update.message)) return false
+    }
+    return true
+  }
+
+export const editedMessage =
+  <Ks extends DistinctKeys<CommonMessageBundle>[]>(...keys: Ks) =>
+  (
+    update: Update
+  ): update is Update.EditedMessageUpdate<
+    KeyedDistinct<CommonMessageBundle, Ks[number]>
+  > => {
+    if (!('edited_message' in update)) return false
+    for (const key of keys) {
+      if (!(key in update.edited_message)) return false
+    }
+    return true
+  }
+
+export const channelPost =
+  <Ks extends DistinctKeys<Message>[]>(...keys: Ks) =>
+  (
+    update: Update
+  ): update is Update.ChannelPostUpdate<KeyedDistinct<Message, Ks[number]>> => {
+    if (!('channel_post' in update)) return false
+    for (const key of keys) {
+      if (!(key in update.channel_post)) return false
+    }
+    return true
+  }
+
+export const editedChannelPost =
+  <Ks extends DistinctKeys<CommonMessageBundle>[]>(...keys: Ks) =>
+  (
+    update: Update
+  ): update is Update.EditedChannelPostUpdate<
+    KeyedDistinct<CommonMessageBundle, Ks[number]>
+  > => {
+    if (!('edited_channel_post' in update)) return false
+    for (const key of keys) {
+      if (!(key in update.edited_channel_post)) return false
+    }
+    return true
+  }
+
+export const callbackQuery =
+  <Ks extends DistinctKeys<CallbackQuery>[]>(...keys: Ks) =>
+  (
+    update: Update
+  ): update is Update.CallbackQueryUpdate<
+    KeyedDistinct<CallbackQuery, Ks[number]>
+  > => {
+    if (!('callback_query' in update)) return false
+    for (const key of keys) {
+      if (!(key in update.callback_query)) return false
+    }
+    return true
+  }
+
+/** Any of the provided filters must match */
+export const anyOf =
+  <Us extends Update[]>(
+    ...filters: {
+      [UIdx in keyof Us]: Filter<Us[UIdx]>
+    }
+  ) =>
+  (update: Update): update is Us[number] => {
+    for (const filter of filters) if (filter(update)) return true
+    return false
+  }
+
+/** All of the provided filters must match */
+export const allOf =
+  <U extends Update, Fs extends Filter<U>[]>(...filters: Fs) =>
+  (update: Update): update is AllGuarded<Fs> => {
+    for (const filter of filters) if (!filter(update)) return false
+    return true
+  }