@dual-os/telegram 0.0.0-stage → 8.0.5

package/LICENSE

@@ -0,0 +1,4 @@
+All rights reserved.
+
+This package is proprietary and is not licensed for public use or redistribution.
+Use and distribution require permission from the rights holder under a separate agreement.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @dual-os/telegram
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Private ESM Telegram plugin for the Dual SDK. Provides chat, callback, file, and message actions plus an update webhook trigger.
+
+## Composition
+
+```ts
+// Definition-only composition: no client or handler-layer imports.
+import { telegramPluginBase } from "@dual-os/telegram/definition";
+// Executable composition with the existing HTTP client and handlers.
+import { telegramPlugin } from "@dual-os/telegram/executable";
+```
+
+Run the executable value in process with `DualRuntime.fromPlugin(plugin, packageJson.version)`; a host receives the published package from npm as a standard plugin. Importing a module starts no services, makes no requests and creates no Provider Connection.
+
+`@dual-os/telegram/plugin.json` exposes declarative discovery metadata: schema version, package/plugin identity, definition/executable subpaths and named exports. The package version is the release. It can be read without executing plugin code.
+
+The historical `Telegram` and `TelegramClient` root namespaces and explicit `/Telegram` and `/TelegramClient` subpaths remain supported. The historical root includes executable modules; use `/definition` for definition-only composition. Internal schema modules are not public entrypoints.
+
+## Installation and compatibility
+
+Source builds use the exact SDK and Effect dependencies in `package.json`; released bundles include them and the runner, without sandbox installation. Pin exact package versions and commit the application's lockfile.
+
+The executable uses Fetch and Node-compatible APIs. Packaging adds no new runtime restriction and does not certify a new Node runtime matrix. Supply provider credentials through the host's Provider Connection setup. Never commit credentials.
+
+## API and Agent Channel
+
+This plugin includes the existing API Actions and Workflow Triggers plus the telegram/messages Agent Channel.
+Existing action/trigger IDs, schemas and API authentication methods are unchanged. The additional
+Channel authentication is listed at plugin level; per-action authentication subsets are intentionally
+deferred. Use existing API Connections for Actions/Triggers and the Channel credentials below for
+agent conversations. No migration of unused standalone Channel installations is provided.
+
+### Telegram Bot Channel
+
+Telegram Bot Channel `telegram/messages`. Uses its own
+Connection (customer bot token and webhook secret); the existing `@dual-os/telegram`
+workflow integration and generated plugins are unchanged.
+
+Deployment settings choose where (`chatIds`: groups or `<chat>/<topic>`, empty for all;
+`directMessages`), who (`access`, `allowedSenderKeys`) and when (`respondTo`). Private text
+messages always respond. With `mentions`, groups respond only to an explicit bot
+mention, a command addressed to the bot username, or a reply whose Telegram sender
+is this bot; `all_messages` responds to every group message in scope and needs privacy mode off. Numeric sender access applies to messages and `/stop`. Actual
+`message_thread_id` values isolate forum topics; ordinary replies share their chat.
+Edits, forwards, channel posts, business messages, anonymous senders, other bots and non-text
+messages are ignored. Attachments and arbitrary history reads are unsupported.
+
+Output uses sendMessage, editMessageText, deleteMessage, setMessageReaction and
+sendChatAction. Sends have no idempotency token, so all deliveries are at-most-once.
+Uncertain sends are terminal `unknown_completion`, never automatically retried.
+Telegram flood control is `rate_limited`; the client retains `retry_after`, while
+the Channel's closed error contract carries only the code. There are no automatic
+HTTP retries. Reaction/edit/delete restrictions and provider errors remain failures.
+Reactions replace the bot's single reaction; removing a reaction clears it. Typing
+lasts at most five seconds; idle has no explicit clearing API and waits for expiry.
+
+Activation checkpoints bot identity before setting an owned registration URL.
+Telegram allows one webhook per bot: activation replaces the previous integration.
+Cleanup deletes only the exact URL owned by that activation and keeps queued updates.
+Telegram offers no conditional delete, so this follows its getWebhookInfo/deleteWebhook
+ownership check. Use a dedicated bot per Channel installation.
+
+Public imports: definition-only `telegramPluginBase` from `/definition`, executable
+`telegramPlugin` from `/executable` or `/Telegram`, and `Telegram.telegramPlugin`
+from the package root. Existing API client exports remain unchanged.