paperclip-plugin-telegram 0.2.1 → 0.2.3

package/README.md

@@ -104,13 +104,24 @@ curl -X POST http://127.0.0.1:3100/api/plugins/install \
   -d '{"packageName":"paperclip-plugin-telegram"}'
 ```
 
-### 4. Configure
+### 4. Store your bot token as a Paperclip secret
+
+The bot token field requires a Paperclip secret reference (a UUID), not the raw token.
+
+1. In Paperclip, go to **Settings → Secrets → Create new secret**
+2. Paste your Telegram bot token as the secret value and save
+3. Copy the UUID of the created secret
+4. Use that UUID in the `telegramBotTokenRef` field below
+
+Do the same for `transcriptionApiKeyRef` if you want Whisper transcription.
+
+### 5. Configure
 
 In your Paperclip instance settings, configure:
 
 | Setting | Required | Description |
 |---------|----------|-------------|
-| `telegramBotTokenRef` | Yes | Secret reference to your bot token |
+| `telegramBotTokenRef` | Yes | Secret UUID for your bot token (see step 4) |
 | `defaultChatId` | Yes | Chat ID for notifications |
 | `approvalsChatId` | No | Separate chat for approvals |
 | `errorsChatId` | No | Separate chat for errors |
@@ -128,7 +139,7 @@ In your Paperclip instance settings, configure:
 | `maxSuggestionsPerHourPerCompany` | No | Rate limit for proactive suggestions (default: 10) |
 | `watchDeduplicationWindowMs` | No | Window before same watch+entity can re-fire (default: 86400000 / 24h) |
 
-### 5. Add bot to group (optional)
+### 6. Add bot to group (optional)
 
 If using a group chat:
 1. Add the bot to your Telegram group
@@ -175,6 +186,20 @@ When a user replies to a bot notification, the plugin looks up which Paperclip e
 | Proactive suggestions | No | Watch conditions with built-in sales templates |
 | Architecture | Monorepo example | Standalone npm package |
 
+## Migration
+
+### v0.2.1
+
+The `telegramBotTokenRef` and `transcriptionApiKeyRef` fields now require a Paperclip secret reference (a UUID), not the raw token value. If you previously entered your raw bot token in the field, follow these steps to migrate:
+
+1. Go to **Settings → Secrets → Create new secret**
+2. Paste your Telegram bot token as the secret value and save
+3. Copy the resulting UUID
+4. Open **Plugin Settings for Telegram Bot** and paste the UUID into "Telegram Bot Token"
+5. Save and restart the plugin
+
+The plugin will fail to activate if a raw token (non-UUID) is entered in the field.
+
 ## Development
 
 ```bash

package/dist/acp-bridge.d.ts

@@ -0,0 +1,34 @@
+import type { PluginContext } from "@paperclipai/plugin-sdk";
+export type ChatSession = {
+    sessionId: string;
+    agentId: string;
+    agentName: string;
+    agentDisplayName: string;
+    transport: "native" | "acp";
+    spawnedAt: string;
+    status: "active" | "closed";
+    lastActivityAt: string;
+};
+type AcpOutputEvent = {
+    sessionId: string;
+    chatId: string;
+    threadId: number;
+    text: string;
+    done?: boolean;
+};
+export declare function setupAcpOutputListener(ctx: PluginContext, token: string): void;
+export declare function handleAcpCommand(ctx: PluginContext, token: string, chatId: string, args: string, messageThreadId?: number, companyId?: string): Promise<void>;
+export declare function routeMessageToAgent(ctx: PluginContext, token: string, chatId: string, threadId: number, text: string, replyToMessageId?: number, companyId?: string): Promise<boolean>;
+export declare function handleAcpOutput(ctx: PluginContext, token: string, event: AcpOutputEvent): Promise<void>;
+export declare function handleHandoffToolCall(ctx: PluginContext, token: string, params: Record<string, unknown>, companyId: string, sourceAgentId: string): Promise<{
+    content?: string;
+    error?: string;
+}>;
+export declare function handleHandoffApproval(ctx: PluginContext, token: string, handoffId: string, actor: string, callbackQueryId: string, chatId: string | null, messageId: number | undefined): Promise<void>;
+export declare function handleHandoffRejection(ctx: PluginContext, token: string, handoffId: string, actor: string, callbackQueryId: string, chatId: string | null, messageId: number | undefined): Promise<void>;
+export declare function handleDiscussToolCall(ctx: PluginContext, token: string, params: Record<string, unknown>, companyId: string, sourceAgentId: string): Promise<{
+    content?: string;
+    error?: string;
+}>;
+export declare function getSessions(ctx: PluginContext, chatId: string, threadId: number): Promise<ChatSession[]>;
+export {};