@astralibx/telegram-ui

Lit Web Components for Telegram account management, campaigns, inbox, and bot analytics -- built on native Custom Elements that work in any framework.

Rule-engine components (templates, rules, throttle, run history) are provided by @astralibx/rule-engine-ui and re-exported from this package. Telegram-specific components (accounts, inbox, bot) are built here.

Part of the @astralibx telegram ecosystem:

• @astralibx/telegram-account-manager -- account CRUD, sessions, health, capacity
• @astralibx/telegram-rule-engine -- templates, rules, throttling, runner (wraps @astralibx/rule-engine)
• @astralibx/telegram-inbox -- conversations, messages, sessions
• @astralibx/telegram-bot -- bot status, user analytics
• @astralibx/rule-engine-ui -- shared rule-engine UI components (templates, rules, throttle, run history)

Install

npm install @astralibx/telegram-ui

Peer dependency: lit ^3.0.0 (included automatically).

Quick Start

import { AlxTelegramConfig } from '@astralibx/telegram-ui';

// One-time setup at app bootstrap
AlxTelegramConfig.setup({
  accountManagerApi: '/api/telegram-accounts',
  ruleEngineApi: '/api/telegram-rules',
  inboxApi: '/api/telegram-inbox',
  botApi: '/api/telegram-bot',
  authToken: 'Bearer your-token',
  theme: 'dark',
});

<!-- Drop the all-in-one dashboard anywhere -->
<alx-telegram-dashboard theme="dark"></alx-telegram-dashboard>

Components

Shared (2)

| Tag | Description | |-----|-------------| | <alx-telegram-dashboard> | All-in-one dashboard with tabs, drawer editing, density/theme toggle | | <alx-tg-drawer> | Slide-in drawer panel for editing forms |

Account Management (2)

| Tag | Description | |-----|-------------| | <alx-tg-account-list> | Paginated table with status, health score, capacity usage | | <alx-tg-account-form> | Create/edit form with phone, session string, send limits |

Rule Engine (6)

| Tag | Description | |-----|-------------| | <alx-tg-template-list> | Template table with message count, variables, category, and clone support | | <alx-tg-template-editor> | Multi-variant message editor with preview and custom fields | | <alx-tg-rule-list> | Rules with active toggle, mode badge, last run date, and clone support | | <alx-tg-rule-editor> | Condition builder, identifier list, template selection | | <alx-tg-run-history> | Execution logs with sent/failed/skipped stats and duration | | <alx-tg-throttle-settings> | Per-recipient throttle config: daily/weekly limits, gap days, window mode |

Inbox (1)

| Tag | Description | |-----|-------------| | <alx-tg-inbox> | Split-pane conversation list + message thread with send support |

Bot (1)

| Tag | Description | |-----|-------------| | <alx-tg-bot-stats> | Bot status, user stats cards, paginated user table |

Analytics (1)

| Tag | Description | |-----|-------------| | <alx-tg-analytics> | Send/fail/skip stats, send logs, error logs with date filters |

API-Only Usage

Use the typed API clients without any UI components:

import { TelegramAccountAPI, TelegramRuleAPI, TelegramInboxAPI, TelegramBotAPI } from '@astralibx/telegram-ui/api';

const accounts = new TelegramAccountAPI('/api/telegram-accounts');
const list = await accounts.listAccounts({ page: 1, limit: 20 });

Theming

Override CSS custom properties on any component or a parent element:

alx-telegram-dashboard {
  --alx-primary: #d4af37;
  --alx-bg: #111;
  --alx-surface: #1a1a1a;
  --alx-border: #333;
  --alx-text: #ccc;
  --alx-text-muted: #888;
  --alx-radius: 4px;
  --alx-font-family: 'Inter', sans-serif;
}

Built-in themes: alxDarkTheme and alxLightTheme are available as Lit CSS exports.

Documentation

• Quick Start -- Pipeline overview, dashboard setup
• Configuration -- AlxTelegramConfig setup, auth tokens, all options
• Components -- All 13 components with properties and events
• Types -- Exported types, APIs, styles, utilities

License

MIT