@vvlad1973/telegram-bot-client 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,282 @@
+# Changelog
+
+## [1.1.0](https://github.com/vvlad1973/telegram-framework/compare/v1.0.0...v1.1.0)
+
+### Features
+
+- **feat**: implement TelegramBotClient framework (2025-12-18) [`656934a9b70b47190fd9b83c9525c26581d85b73`](https://github.com/vvlad1973/telegram-framework/commit/656934a9b70b47190fd9b83c9525c26581d85b73)
+  Add high-level bot framework with complete update processing:
+  
+  Core features:
+  \- Abstract TelegramBotClient class extending BaseTelegramApi
+  \- Event-based update routing with EventEmitter
+  \- Advanced filter system with RegExp support
+  \- Middleware chain with async support
+  \- Wrapper classes integration
+  
+  Event system:
+  \- Type-based subscriptions (on, onFilter)
+  \- Wildcard support for all update types
+  \- Chat type filtering (@private, @group)
+  \- Command extraction and routing
+  
+  Filter system:
+  \- JSON-based filter definitions
+  \- RegExp matching for all text fields
+  \- Multi-field filtering (type, contents, chat, user)
+  \- Flexible filter composition
+  
+  Middleware:
+  \- Chain of responsibility pattern
+  \- Pre-processing before handlers
+  \- Async middleware support
+  \- Error boundary handling
+  
+  Integration:
+  \- Works with any callApi implementation
+  \- Compatible with polling and webhooks
+  \- Type-safe with full TypeScript support
+
+- **feat**: add update helper functions (2025-12-18) [`c9f25ec034759834c910e64f12c4e793311dc0b6`](https://github.com/vvlad1973/telegram-framework/commit/c9f25ec034759834c910e64f12c4e793311dc0b6)
+  Implement utilities for update and message processing:
+  
+  \- UpdateType enum: All Telegram update types
+  \- MessageType enum: All message types (text, photo, document, etc.)
+  \- SERVICE_MESSAGE_TYPES: Array of service message types
+  
+  Helper functions:
+  \- parseCommand(): Extract command and parameters from text
+  \- getMessageType(): Determine message type from Message object
+  \- getFileId(): Extract file_id from any message type
+  \- isServiceMessage(): Check if message is a service message
+  
+  These helpers are used internally by TelegramBotClient for update
+  classification and filtering, and are also exported for public use.
+
+- **feat**: add wrapper classes for messages and callbacks (2025-12-18) [`31c5dcd93ccb80d9d72c515233e6a2dccbeb0b56`](https://github.com/vvlad1973/telegram-framework/commit/31c5dcd93ccb80d9d72c515233e6a2dccbeb0b56)
+  Implement enhanced wrapper classes with helper methods:
+  
+  \- MessageWrapper: Enhance Message objects
+    \- replyMessage/answerMessage for sending responses
+    \- replyPhoto/replyDocument for media replies
+    \- editText/editCaption for editing
+    \- delete/pin/unpin for message management
+    \- forward for forwarding messages
+    \- Access to original message properties
+  
+  \- CallbackQueryWrapper: Enhance CallbackQuery objects
+    \- Automatic callback answering
+    \- answer() for callback responses
+    \- answerMessage() for sending messages
+    \- editText/editCaption for inline message editing
+    \- delete() for deleting callback messages
+    \- Access to message through wrapper.message
+  
+  Both wrappers integrate seamlessly with TelegramBotClient and provide
+  type-safe API access through the callApi method.
+
+- **feat**: add keyboard and command builders (2025-12-18) [`93844e08815e1c8db19af9b2db64a93569ab26de`](https://github.com/vvlad1973/telegram-framework/commit/93844e08815e1c8db19af9b2db64a93569ab26de)
+  Implement fluent API builders for Telegram keyboards and commands:
+  
+  \- InlineKeyboardBuilder: Build inline keyboards
+    \- Text buttons with callback data
+    \- URL buttons
+    \- Switch inline query buttons
+    \- Login URL buttons
+    \- Web app buttons
+    \- Pay and game buttons
+    \- Row and column management
+  
+  \- ReplyKeyboardBuilder: Build reply keyboards
+    \- Text buttons
+    \- Request contact/location buttons
+    \- Poll type buttons
+    \- Web app buttons
+    \- Keyboard configuration (resize, one-time, selective)
+  
+  \- BotCommandsBuilder: Manage bot commands
+    \- Add/remove commands
+    \- Scope and language support
+    \- Validation
+  
+  All builders include full TypeScript types and comprehensive validation.
+
+- **feat**: add working examples for bot framework (2025-12-18) [`4e57fdd83f1374151140ac4bbf1af94a9bd9f4c6`](https://github.com/vvlad1973/telegram-framework/commit/4e57fdd83f1374151140ac4bbf1af94a9bd9f4c6)
+  Add comprehensive examples demonstrating framework usage:
+  
+  \- simple-bot.ts: Basic bot implementation
+    \- Command handling with event system
+    \- Text message processing
+    \- Simple filter usage
+    \- Keyboard builders
+  
+  \- advanced-bot.ts: Advanced features
+    \- Complex filters with RegExp
+    \- Middleware chain
+    \- Rate limiting
+    \- Admin commands
+    \- Multi-language support
+  
+  \- webhook-bot.ts: Webhook integration
+    \- Express server setup
+    \- Webhook endpoint
+    \- Update processing
+    \- Error handling
+  
+  All examples are production-ready and include TypeScript types.
+
+### Fixes
+
+- **fix**: replace any types with proper TypeScript types (2025-12-18) [`5448e813762448f046f8d6dff8ccd829000e4c6f`](https://github.com/vvlad1973/telegram-framework/commit/5448e813762448f046f8d6dff8ccd829000e4c6f)
+  Replace all any types in production code with proper types:
+  \- polling-manager.types.ts: Update -> Update, info -> unknown
+  \- PollingLoop.ts: Use instanceof Error pattern for error handling
+  \- WorkerCommandHandler.ts: Use typed object assertion
+  \- LongPollingManager.ts: Update -> Update, httpOptions -> Record<string, unknown>
+  \- TelegramBotClient.ts: unknown, Record<string, unknown> for flexible parameters
+  \- CallbackQueryWrapper.ts: InputMedia for media parameter, unknown for type guard
+  \- MessageWrapper.ts: InputMedia, InputMedia[], Record<string, unknown>
+  \- TokensManager.ts: Export TokensManagerOptions
+  
+  This improves type safety and eliminates all ESLint any warnings in production code.
+
+### Documentation
+
+- **docs**: fix TypeDoc configuration and JSDoc format (2025-12-18) [`cfbd837a2651f41ab954c061ff3695020032c691`](https://github.com/vvlad1973/telegram-framework/commit/cfbd837a2651f41ab954c061ff3695020032c691)
+  \- Fix JSDoc @description format in type files (http-client, logger, queue)
+  \- Add missing entry points to typedoc.json
+  \- Remove exclusion of helpers from TypeDoc
+  \- Fix markdown lint errors in README.md and examples/README.md
+  \- Add comprehensive documentation sections to README.md:
+    \- Bot Commands Builder
+    \- Worker Management
+    \- Event Handling
+    \- Core API Classes
+  \- Fix broken links to guides documentation
+  \- Eliminates all TypeDoc warnings (15 warnings -> 0)
+
+- **docs**: reorganize documentation structure (2025-12-18) [`df19996e43f261e57851f35d4d52358596fa5918`](https://github.com/vvlad1973/telegram-framework/commit/df19996e43f261e57851f35d4d52358596fa5918)
+  \- Move CLIENT-GUIDE.md and MIGRATION-GUIDE.md to docs/guides/
+  \- Add ARCHITECTURE.md to docs/
+  \- Remove obsolete analysis and reports (14 files):
+    \- docs/reports/ (9 status and analysis reports)
+    \- docs/LONG-POLLING-*-ANALYSIS.md files
+    \- docs/HTTP-CLIENT-COMPARISON.md
+  \- Add long-polling-multi-token.ts example
+  \- Fix markdown lint errors in all documentation files
+  \- Update README.md with comprehensive documentation links
+  \- Follows DOCUMENTATION-GUIDELINES.md principles
+  \- Improves documentation organization and maintainability
+
+- **docs**: add comprehensive guides for high-level framework (2025-12-18) [`ad1249e9824c2843f3ab896debec04f534ea09f4`](https://github.com/vvlad1973/telegram-framework/commit/ad1249e9824c2843f3ab896debec04f534ea09f4)
+  Add detailed documentation for new bot framework features:
+  
+  \- CLIENT-GUIDE.md: Complete guide for TelegramBotClient usage
+    \- Event system with type-based subscriptions
+    \- Advanced filtering with RegExp support
+    \- Middleware chain implementation
+    \- Wrapper classes with helper methods
+    \- Integration examples
+  
+  \- FILTERS.md: Filter system documentation
+    \- Filter syntax and semantics
+    \- RegExp usage in filters
+    \- Practical examples for common scenarios
+    \- Best practices
+  
+  \- MIDDLEWARE.md: Middleware guide
+    \- Chain of responsibility pattern
+    \- Async middleware support
+    \- Error handling in middleware
+    \- Real-world use cases
+  
+  \- FILTER-INTERNALS.md: Internal implementation details
+    \- Filter matching algorithm
+    \- Performance considerations
+    \- Testing strategies
+
+- **docs**: update README with high-level bot framework documentation (2025-12-18) [`b3fb0c8553f65606c590eb2be438cfc1bb5504c0`](https://github.com/vvlad1973/telegram-framework/commit/b3fb0c8553f65606c590eb2be438cfc1bb5504c0)
+  Update documentation to reflect new high-level features added in v1.0.0:
+  \- TelegramBotClient framework with event system
+  \- Advanced filter system with RegExp support
+  \- Middleware chain of responsibility pattern
+  \- Wrapper classes for Message and CallbackQuery
+  \- Keyboard builders with fluent API
+  \- Complete usage examples and guides
+  
+  Restructure documentation sections:
+  \- Add "High-Level Bot Framework" as primary option
+  \- Move transport layer to "Low-Level Usage" section
+  \- Add comprehensive examples for all new features
+  \- Update feature list with framework capabilities
+  \- Add links to new documentation files
+
+- **docs**: add final status analysis for v1.0.0 (2025-12-18) [`c56d85181ebc5dc1a469c9179412a8174eac6fe1`](https://github.com/vvlad1973/telegram-framework/commit/c56d85181ebc5dc1a469c9179412a8174eac6fe1)
+  Added comprehensive status report documenting all improvements:
+  \- Test coverage increased to 93.03% (from 88.15%)
+  \- 330 tests passing (was 256, +74 tests)
+  \- 100% coverage for open-api.js, utils.js, logger-helpers.ts, ErrorMapper.ts
+  \- Integration test suite with 13 end-to-end tests
+  \- All 6 commits for v1.0.0 documented
+  \- Package ready for production use
+
+- **docs**: add comprehensive documentation and examples for v1.0.0 (2025-12-17) [`88018094aefbd50542dcb763612456a346c91df6`](https://github.com/vvlad1973/telegram-framework/commit/88018094aefbd50542dcb763612456a346c91df6)
+  \- Add Migration Guide for upgrading from 0.1.0-alpha.0
+  \- Create documentation index with organized navigation
+  \- Add basic usage examples (sending messages, multiple bots, error handling)
+  \- Add advanced usage examples (polling, priorities, chat admin, media)
+  \- Add examples README with setup instructions and snippets
+  \- Update main README with new features section and docs structure
+  \- Reorganize reports into docs/reports/ subdirectory
+  \- Update version info: 1.0.0, Telegram Bot API 9.2.0, Node.js 18+
+  \- Fix vitest.config.ts for Vitest 4.x compatibility
+  \- Add @vvlad1973/gen-changelog dependency
+  \- Update package.json version to 1.0.0
+
+## [1.0.0](https://github.com/vvlad1973/telegram-framework/compare/0.1.0-alpha.0...v1.0.0)
+
+### Features
+
+- **feat**: integrate logger-tree with dual binding support (2025-12-17) [`247f305bdf5d386b579603ddbf2a89e3b1ced744`](https://github.com/vvlad1973/telegram-framework/commit/247f305bdf5d386b579603ddbf2a89e3b1ced744)
+  Add comprehensive logger support to all transport components with two
+  integration methods: LoggerBinder automatic binding and direct logger
+  passing through constructor parameters.
+  
+  Core Changes:
+  \- Add logger types and interfaces (ILogger, LoggerOptions, ILoggerAware)
+  \- Add logger helper functions (initializeLogger, logError, safeLogContext)
+  \- Integrate logger into TelegramHttpTransport with API call logging
+  \- Integrate logger into TelegramHttpClient with HTTP request logging
+  \- Integrate logger into TokensManager with token operation logging
+  \- Integrate logger into InMemoryQueueProvider with queue logging
+  \- Export all logger types and helpers from main index
+  \- Add dependencies: @vvlad1973/logger-tree, @vvlad1973/simple-logger
+  
+  Documentation:
+  \- Add comprehensive Logger Integration Guide (550+ lines)
+  \- Update Quick Start Guide with logger examples
+  \- Add Logger Integration Status report
+  \- Update README with logger-aware feature
+  
+  Features:
+  \- Support LoggerBinder.bind() for automatic logger binding
+  \- Support direct logger passing via constructor parameters
+  \- Logger hierarchy: parent components pass logger to children
+  \- Optional logger: all components work without logger
+  \- Full backward compatibility maintained
+  \- Log levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
+  \- Structured logging with context objects
+  
+  Quality Assurance:
+  \- Build: SUCCESS (0 errors)
+  \- ESLint: SUCCESS (0 errors, 50 pre-existing warnings)
+  \- Markdownlint: SUCCESS (0 errors)
+
+- **feat**: update Telegram Bot API types and add new endpoints (2025-12-16) [`40c2523a0f3d24b6d6561d4063c8ff57eac0cc76`](https://github.com/vvlad1973/telegram-framework/commit/40c2523a0f3d24b6d6561d4063c8ff57eac0cc76)
+  Updated OpenAPI specification, regenerated API types, added new methods (EditUserStarSubscription, GetAvailableGifts, etc.), and enhanced test infrastructure.
+
+## [0.1.0-alpha.0](https://github.com/vvlad1973/telegram-framework/tree/0.1.0-alpha.0)
+
+### Initial
+
+- Initial commit (2024-08-27) [`ff34832dadf08d53df59ef1684edb9990814bd96`](https://github.com/vvlad1973/telegram-framework/commit/ff34832dadf08d53df59ef1684edb9990814bd96)

package/LICENSE

@@ -0,0 +1,19 @@
+# MIT License with Commercial Use
+
+Copyright (c) 2022 Vladislav Vnukovskiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.
+
+Commercial Use:
+
+The user is allowed to use the Software for commercial purposes, subject to the following conditions:
+
+The user must agree to share a portion of their revenue with the author of the Software.
+
+The author of the Software reserves the right to verify the accuracy and size of the revenue earned by the user through the use of the Software. This provision is a mandatory condition for the commercial use of the Software.
+
+If the user does not agree to these conditions, they may not use the Software for commercial purposes.
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.