teledzik 1.0.0

package/src/core/helpers/ai-stream.ts

@@ -0,0 +1,96 @@
+import { Context } from '../../context'
+import { InputRichMessage } from '../types/rich-message'
+
+export interface AIStreamOptions {
+  /** Minimum interval in ms between Telegram message edits (default: 800ms) */
+  minUpdateIntervalMs?: number
+  /** Use draft (sendRichMessageDraft) if true (default: false) */
+  useDraft?: boolean
+  /** Draft ID for sendRichMessageDraft */
+  draftId?: number
+}
+
+/**
+ * AI Live Stream Adapter for Telegram Bots.
+ * Throttles live token stream edits to prevent Telegram rate limit bans.
+ */
+export class AIStreamAdapter {
+  private buffer = ''
+  private lastUpdate = 0
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private readonly minInterval: number
+  private readonly ctx: Context<any>
+  private readonly options: AIStreamOptions
+  private sentMessageId?: number
+
+  constructor(ctx: Context<any>, options: AIStreamOptions = {}) {
+    this.ctx = ctx
+    this.options = options
+    this.minInterval = options.minUpdateIntervalMs ?? 800
+  }
+
+  /**
+   * Append new token chunk from LLM stream.
+   */
+  async push(chunk: string): Promise<void> {
+    this.buffer += chunk
+    await this.scheduleUpdate()
+  }
+
+  /**
+   * Finalize the stream and send the full final content.
+   */
+  async end(finalContent?: string): Promise<any> {
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+
+    if (finalContent !== undefined) {
+      this.buffer = finalContent
+    }
+
+    return this.flush(true)
+  }
+
+  private async scheduleUpdate(): Promise<void> {
+    const now = Date.now()
+    const elapsed = now - this.lastUpdate
+
+    if (elapsed >= this.minInterval) {
+      await this.flush()
+    } else if (!this.timer) {
+      this.timer = setTimeout(async () => {
+        this.timer = null
+        await this.flush()
+      }, this.minInterval - elapsed)
+    }
+  }
+
+  private async flush(isFinal = false): Promise<any> {
+    if (!this.buffer) return
+
+    this.lastUpdate = Date.now()
+
+    if (this.options.useDraft && this.options.draftId) {
+      const richMsg: InputRichMessage = { html: `<p>${this.buffer}${isFinal ? '' : ' ▍'}</p>` }
+      return this.ctx.sendRichMessageDraft(this.options.draftId, richMsg)
+    }
+
+    const text = `${this.buffer}${isFinal ? '' : ' ▍'}`
+
+    if (!this.sentMessageId) {
+      const sent = await this.ctx.reply(text, { parse_mode: 'HTML' })
+      this.sentMessageId = sent.message_id
+      return sent
+    } else {
+      return this.ctx.telegram.editMessageText(
+        this.ctx.chat?.id,
+        this.sentMessageId,
+        undefined,
+        text,
+        { parse_mode: 'HTML' }
+      )
+    }
+  }
+}

package/src/core/helpers/args.ts

@@ -0,0 +1,63 @@
+interface Entity {
+  /** Type of the entity. Currently, can be “mention” (@username), “hashtag” (#hashtag), “cashtag” ($USD), “bot_command” (/start@jobs_bot), “url” (https://telegram.org), “email” (do-not-reply@telegram.org), “phone_number” (+1-212-555-0123), “bold” (bold text), “italic” (italic text), “underline” (underlined text), “strikethrough” (strikethrough text), “spoiler” (spoiler message), “code” (monowidth string), “pre” (monowidth block), “text_link” (for clickable text URLs), “text_mention” (for users without usernames), “custom_emoji” (for inline custom emoji stickers) */
+  type: string
+  /** Offset in UTF-16 code units to the start of the entity */
+  offset: number
+  /** Length of the entity in UTF-16 code units */
+  length: number
+}
+
+const SINGLE_QUOTE = "'"
+const DOUBLE_QUOTE = '"'
+
+export function argsParser(
+  str: string,
+  entities: Entity[] = [],
+  entityOffset = 0
+) {
+  const mentions: { [offset: string]: number } = {}
+  for (const entity of entities) // extract all text_mentions into an { offset: length } map
+    if (entity.type === 'text_mention' || entity.type === 'text_link')
+      mentions[entity.offset - entityOffset] = entity.length
+
+  const args: string[] = []
+  let done = 0
+  let inside: `'` | `"` | undefined = undefined
+  let buf = ''
+
+  function flush(to: number) {
+    if (done !== to) args.push(buf + str.slice(done, to)), (inside = undefined)
+    buf = ''
+    done = to + 1
+  }
+
+  for (let i = 0; i < str.length; i++) {
+    const char = str[i]
+    // quick lookup length of mention starting at i
+    const mention = mentions[i]
+    if (mention) {
+      // if we're inside a quote, eagerly flush existing state
+      flush(i)
+      // this also consumes current index, so decrement
+      done--
+      // fast forward to end of mention
+      i += mention
+      flush(i)
+    } else if (char === SINGLE_QUOTE || char === DOUBLE_QUOTE)
+      if (inside)
+        if (inside === char) flush(i)
+        else continue
+      else flush(i), (inside = char)
+    else if (char === ' ')
+      if (inside) continue
+      else flush(i)
+    else if (char === '\n') flush(i)
+    else if (char === '\\')
+      (buf += str.slice(done, i)), (done = ++i) // skip parsing the next char
+    else continue
+  }
+
+  if (done < str.length) flush(str.length)
+
+  return args
+}

package/src/core/helpers/check.ts

@@ -0,0 +1,71 @@
+interface Mapping {
+  string: string
+  number: number
+  bigint: bigint
+  boolean: boolean
+  symbol: symbol
+  undefined: undefined
+  object: Record<string, unknown>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  function: (...props: any[]) => any
+}
+
+/**
+ * Checks if a given object has a property with a given name.
+ *
+ * Example invocation:
+ * ```js
+ * let obj = { 'foo': 'bar', 'baz': () => {} }
+ * hasProp(obj, 'foo') // true
+ * hasProp(obj, 'baz') // true
+ * hasProp(obj, 'abc') // false
+ * ```
+ *
+ * @param obj An object to test
+ * @param prop The name of the property
+ */
+export function hasProp<O extends object, K extends PropertyKey>(
+  obj: O | undefined,
+  prop: K
+): obj is O & Record<K, unknown> {
+  return obj !== undefined && prop in obj
+}
+/**
+ * Checks if a given object has a property with a given name.
+ * Furthermore performs a `typeof` check on the property if it exists.
+ *
+ * Example invocation:
+ * ```js
+ * let obj = { 'foo': 'bar', 'baz': () => {} }
+ * hasPropType(obj, 'foo', 'string') // true
+ * hasPropType(obj, 'baz', 'function') // true
+ * hasPropType(obj, 'abc', 'number') // false
+ * ```
+ *
+ * @param obj An object to test
+ * @param prop The name of the property
+ * @param type The type the property is expected to have
+ */
+export function hasPropType<
+  O extends object,
+  K extends PropertyKey,
+  T extends keyof Mapping,
+  V extends Mapping[T],
+>(obj: O | undefined, prop: K, type: T): obj is O & Record<K, V> {
+  return hasProp(obj, prop) && type === typeof obj[prop]
+}
+
+/**
+ * Checks if the supplied array has two dimensions or not.
+ *
+ * Example invocations:
+ * is2D([]) // false
+ * is2D([[]]) // true
+ * is2D([[], []]) // true
+ * is2D([42]) // false
+ *
+ * @param arr an array with one or two dimensions
+ */
+export function is2D<E>(arr: E[] | E[][]): arr is E[][] {
+  return Array.isArray(arr[0])
+}

package/src/core/helpers/compact.ts

@@ -0,0 +1,18 @@
+export function compactOptions<T extends { [key: string]: unknown }>(
+  options?: T
+): T | undefined {
+  if (!options) {
+    return options
+  }
+
+  const compacted: Partial<T> = {}
+  for (const key in options)
+    if (
+      // todo(mkr): replace with Object.hasOwn in v5 (Node 16+)
+      Object.prototype.hasOwnProperty.call(options, key) &&
+      options[key] !== undefined
+    )
+      compacted[key] = options[key]
+
+  return compacted as T | undefined
+}

package/src/core/helpers/deunionize.ts

@@ -0,0 +1,26 @@
+export type PropOr<
+  T extends object | undefined,
+  P extends string | symbol | number,
+  D = undefined,
+> = T extends Partial<Record<P, unknown>> ? T[P] : D
+
+export type UnionKeys<T> = T extends unknown ? keyof T : never
+
+type AddOptionalKeys<K extends PropertyKey> = { readonly [P in K]?: never }
+
+/**
+ * @see https://millsp.github.io/ts-toolbelt/modules/union_strict.html
+ */
+export type Deunionize<B extends object | undefined, T = B> = T extends object
+  ? T & AddOptionalKeys<Exclude<UnionKeys<B>, keyof T>>
+  : T
+
+/**
+ * Expose properties from all union variants.
+ * @deprectated
+ * @see https://github.com/telegraf/telegraf/issues/1388#issuecomment-791573609
+ * @see https://millsp.github.io/ts-toolbelt/modules/union_strict.html
+ */
+export function deunionize<T extends object | undefined>(t: T) {
+  return t as Deunionize<T>
+}

package/src/core/helpers/formatting.ts

@@ -0,0 +1,119 @@
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+import { MessageEntity, User } from '@telegraf/types'
+import { Any, zip } from './util'
+
+export type Nestable<Kind extends string> =
+  | string
+  | number
+  | boolean
+  | FmtString<Kind>
+export type MaybeNestableList<Kind extends string> =
+  | Nestable<Kind>
+  | readonly Nestable<Kind>[]
+
+export interface FmtString<Brand extends string> {
+  text: string
+  entities?: MessageEntity[]
+  parse_mode?: undefined
+  __to_nest: Brand
+}
+
+export class FmtString<Brand extends string = string>
+  implements FmtString<Brand>
+{
+  constructor(
+    public text: string,
+    entities?: MessageEntity[]
+  ) {
+    if (entities) {
+      this.entities = entities
+      // force parse_mode to undefined if entities are present
+      this.parse_mode = undefined
+    }
+  }
+  static normalise(content: Nestable<string>) {
+    if (content instanceof FmtString) return content
+    return new FmtString(String(content))
+  }
+}
+
+const isArray: <T>(xs: T | readonly T[]) => xs is readonly T[] = Array.isArray
+
+/** Given a base FmtString and something to append to it, mutates the base */
+const _add = (base: FmtString, next: FmtString | Any) => {
+  const len = base.text.length
+  if (next instanceof FmtString) {
+    base.text = `${base.text}${next.text}`
+    // next.entities could be undefined and condition will fail
+    for (let i = 0; i < (next.entities?.length || 0); i++) {
+      // because of the above condition, next.entities[i] cannot be undefined
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const entity = next.entities![i]!
+      // base.entities is ensured by caller
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      base.entities!.push({ ...entity, offset: entity.offset + len })
+    }
+  } else base.text = `${base.text}${next}`
+}
+
+/**
+ * Given an `Iterable<FmtString | string | Any>` and a separator, flattens the list into a single FmtString.
+ * Analogous to Array#join -> string, but for FmtString
+ */
+export const join = (
+  fragments: Iterable<FmtString | string | Any>,
+  separator?: string | FmtString
+) => {
+  const result = new FmtString('')
+  // ensure entities array so loop doesn't need to check
+  result.entities = []
+
+  const iter = fragments[Symbol.iterator]()
+
+  let curr = iter.next()
+  while (!curr.done) {
+    _add(result, curr.value)
+    curr = iter.next()
+    if (separator && !curr.done) _add(result, separator)
+  }
+
+  // set parse_mode: undefined if entities are present
+  if (result.entities.length) result.parse_mode = undefined
+  // remove entities array if not relevant
+  else delete result.entities
+
+  return result
+}
+
+/** Internal constructor for all fmt helpers */
+export function createFmt(kind?: MessageEntity['type'], opts?: object) {
+  return function fmt(
+    parts: MaybeNestableList<string>,
+    ...items: Nestable<string>[]
+  ) {
+    parts = isArray(parts) ? parts : [parts]
+    const result = join(zip(parts, items))
+    if (kind) {
+      result.entities ??= []
+      result.entities.unshift({
+        type: kind,
+        offset: 0,
+        length: result.text.length,
+        ...opts,
+      } as MessageEntity)
+      result.parse_mode = undefined
+    }
+    return result
+  }
+}
+
+export const linkOrMention = (
+  content: Nestable<string>,
+  data:
+    | { type: 'text_link'; url: string }
+    | { type: 'text_mention'; user: User }
+) => {
+  const { text, entities = [] } = FmtString.normalise(content)
+  entities.unshift(Object.assign(data, { offset: 0, length: text.length }))
+  return new FmtString(text, entities)
+}

package/src/core/helpers/input-box.ts

@@ -0,0 +1,86 @@
+import * as Markup from '../../markup'
+
+export interface InputBoxFieldOptions {
+  placeholder?: string
+  validate?: (value: string) => boolean | string
+  type?: 'text' | 'number'
+}
+
+export interface InputBoxField extends InputBoxFieldOptions {
+  key: string
+  label: string
+}
+
+/**
+ * Interactive In-Chat Form Box Card for Telegram Messages.
+ * Render boxed form cards with dynamic real-time field updates.
+ */
+export class InputBox {
+  readonly id: string
+  private title = '📋 FORM INPUT'
+  private fields: InputBoxField[] = []
+  private completionHandler?: (data: Record<string, string>) => any
+
+  constructor(id: string) {
+    this.id = id
+  }
+
+  setTitle(title: string): this {
+    this.title = title
+    return this
+  }
+
+  addField(key: string, label: string, options: InputBoxFieldOptions = {}): this {
+    this.fields.push({ key, label, ...options })
+    return this
+  }
+
+  onComplete(handler: (data: Record<string, string>) => any): this {
+    this.completionHandler = handler
+    return this
+  }
+
+  /**
+   * Render formatted HTML box card text.
+   */
+  renderText(data: Record<string, string> = {}): string {
+    const lines: string[] = []
+    lines.push(`<b>┌─ ${this.title.toUpperCase()} ─┐</b>`)
+
+    this.fields.forEach((field, idx) => {
+      const val = data[field.key] ? `<b>${data[field.key]}</b>` : `<i>[ ${field.placeholder ?? 'Belum diisi'} ]</i>`
+      lines.push(`│ ${idx + 1}. <b>${field.label}</b>: ${val}`)
+    })
+
+    const isComplete = this.fields.every((f) => Boolean(data[f.key]))
+    lines.push(`<b>└${'─'.repeat(30)}┘</b>`)
+    lines.push(isComplete ? '<b>Status:</b> ✅ <i>Lengkap (Siap Dikirim)</i>' : '<b>Status:</b> ⌛ <i>Menunggu Pengisian...</i>')
+
+    return lines.join('\n')
+  }
+
+  /**
+   * Render inline keyboard with field edit buttons and submit action.
+   */
+  renderKeyboard(data: Record<string, string> = {}) {
+    const buttons: any[] = []
+
+    // Field buttons
+    this.fields.forEach((field) => {
+      const filled = Boolean(data[field.key])
+      const icon = filled ? '✅' : '✏️'
+      buttons.push([Markup.button.callback(`${icon} ${field.label}`, `inputbox:${this.id}:edit:${field.key}`)])
+    })
+
+    // Action row
+    const isComplete = this.fields.every((f) => Boolean(data[f.key]))
+    if (isComplete) {
+      buttons.push([
+        Markup.button.callback('🚀 Submit Form', `inputbox:${this.id}:submit`),
+        Markup.button.callback('🔄 Reset', `inputbox:${this.id}:reset`),
+      ])
+    }
+
+    return Markup.inlineKeyboard(buttons)
+  }
+}

package/src/core/helpers/rich-sanitizer.ts

@@ -0,0 +1,36 @@
+/**
+ * Converts Rich HTML strings containing tags like <h1>, <h2>, <p>, <hr>
+ * into standard Telegram HTML compatible with parse_mode: 'HTML' (editMessageText/sendMessage).
+ */
+export function sanitizeRichHtml(html: string): string {
+  if (!html) return html
+
+  let result = html
+
+  // Convert H1: <h1>Text</h1> -> <b>TEXT</b>
+  result = result.replace(/<h1[^>]*>(.*?)<\/h1>/gis, (_, content) => `<b>${content.trim().toUpperCase()}</b>\n\n`)
+
+  // Convert H2..H6: <h2>Text</h2> -> <b>Text</b>
+  result = result.replace(/<h[2-6][^>]*>(.*?)<\/h[2-6]>/gis, (_, content) => `<b>${content.trim()}</b>\n\n`)
+
+  // Convert Paragraphs: <p>Text</p> -> Text\n\n
+  result = result.replace(/<p[^>]*>(.*?)<\/p>/gis, (_, content) => `${content.trim()}\n\n`)
+
+  // Convert Footer: <footer>Text</footer> -> <i>Text</i>
+  result = result.replace(/<footer[^>]*>(.*?)<\/footer>/gis, (_, content) => `<i>${content.trim()}</i>\n`)
+
+  // Convert Horizontal Rules: <hr/> or <hr> -> ──────────
+  result = result.replace(/<hr\s*\/?>/gi, '──────────\n')
+
+  // Convert Marks: <mark>Text</mark> -> <b>[Text]</b>
+  result = result.replace(/<mark[^>]*>(.*?)<\/mark>/gis, (_, content) => `<b>[${content.trim()}]</b>`)
+
+  // Strip unsupported sub/sup tags but keep text
+  result = result.replace(/<sub[^>]*>(.*?)<\/sub>/gis, '$1')
+  result = result.replace(/<sup[^>]*>(.*?)<\/sup>/gis, '$1')
+
+  // Trim extra trailing newlines (> 2 consecutive newlines)
+  result = result.replace(/\n{3,}/g, '\n\n')
+
+  return result.trim()
+}

package/src/core/helpers/smart-queue.ts

@@ -0,0 +1,89 @@
+export interface QueueOptions {
+  minDelayMs?: number
+  maxRetries?: number
+}
+
+interface QueuedItem<T> {
+  task: () => Promise<T>
+  resolve: (val: T | PromiseLike<T>) => void
+  reject: (err: any) => void
+  retries: number
+}
+
+/**
+ * Smart Queue & Rate-Limit Manager for Telegram Bot API calls.
+ * Prevents 429 Too Many Requests by enforcing min delay between calls per target key (e.g. chatId).
+ */
+export class SmartQueue {
+  private static instance: SmartQueue
+  private readonly queues = new Map<string | number, QueuedItem<any>[]>()
+  private readonly processing = new Set<string | number>()
+  private minDelayMs: number
+
+  constructor(options: QueueOptions = {}) {
+    this.minDelayMs = options.minDelayMs ?? 50
+  }
+
+  static getInstance(): SmartQueue {
+    if (!SmartQueue.instance) {
+      SmartQueue.instance = new SmartQueue()
+    }
+    return SmartQueue.instance
+  }
+
+  enqueue<T>(key: string | number, task: () => Promise<T>, options?: QueueOptions): Promise<T> {
+    return new Promise((resolve, reject) => {
+      if (!this.queues.has(key)) {
+        this.queues.set(key, [])
+      }
+
+      this.queues.get(key)!.push({
+        task,
+        resolve,
+        reject,
+        retries: 0,
+      })
+
+      this.processQueue(key, options)
+    })
+  }
+
+  private async processQueue(key: string | number, options?: QueueOptions) {
+    if (this.processing.has(key)) return
+    this.processing.add(key)
+
+    const queue = this.queues.get(key)
+    const maxRetries = options?.maxRetries ?? 3
+    const minDelay = options?.minDelayMs ?? this.minDelayMs
+
+    while (queue && queue.length > 0) {
+      const item = queue[0]
+      try {
+        const result = await item.task()
+        queue.shift()
+        item.resolve(result)
+      } catch (err: any) {
+        // Handle Telegram 429 Too Many Requests (retry_after)
+        const retryAfter = err?.parameters?.retry_after ?? err?.response?.parameters?.retry_after
+        if (retryAfter && item.retries < maxRetries) {
+          item.retries++
+          const waitTime = (retryAfter + 0.5) * 1000
+          await new Promise((res) => setTimeout(res, waitTime))
+          continue
+        }
+
+        queue.shift()
+        item.reject(err)
+      }
+
+      if (queue.length > 0) {
+        await new Promise((res) => setTimeout(res, minDelay))
+      }
+    }
+
+    this.processing.delete(key)
+    if (queue && queue.length === 0) {
+      this.queues.delete(key)
+    }
+  }
+}