profclaw 0.0.1-beta.1

package/dist/chat/providers/telegram/index.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Telegram Provider - Full Implementation
+ *
+ * Secure Telegram Bot integration with:
+ * - Webhook signature verification (X-Telegram-Bot-Api-Secret-Token)
+ * - Message sending via Bot API
+ * - Bot commands (/command syntax)
+ * - Inline keyboards for interactive UI
+ * - Reply-to for threaded conversations
+ */
+import { z } from 'zod';
+import type { ChatProvider, TelegramAccountConfig } from '../types.js';
+interface TelegramUser {
+    id: number;
+    is_bot: boolean;
+    first_name: string;
+    last_name?: string;
+    username?: string;
+    language_code?: string;
+}
+interface TelegramChat {
+    id: number;
+    type: 'private' | 'group' | 'supergroup' | 'channel';
+    title?: string;
+    username?: string;
+    first_name?: string;
+    last_name?: string;
+}
+interface TelegramMessage {
+    message_id: number;
+    from?: TelegramUser;
+    chat: TelegramChat;
+    date: number;
+    text?: string;
+    entities?: Array<{
+        type: string;
+        offset: number;
+        length: number;
+    }>;
+    reply_to_message?: TelegramMessage;
+    photo?: Array<{
+        file_id: string;
+        width: number;
+        height: number;
+    }>;
+    document?: {
+        file_id: string;
+        file_name?: string;
+        mime_type?: string;
+    };
+}
+interface TelegramCallbackQuery {
+    id: string;
+    from: TelegramUser;
+    message?: TelegramMessage;
+    chat_instance: string;
+    data?: string;
+}
+interface TelegramUpdate {
+    update_id: number;
+    message?: TelegramMessage;
+    edited_message?: TelegramMessage;
+    callback_query?: TelegramCallbackQuery;
+}
+declare const TelegramAccountConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodLiteral<"telegram">;
+    botToken: z.ZodOptional<z.ZodString>;
+    webhookUrl: z.ZodOptional<z.ZodString>;
+    webhookSecret: z.ZodOptional<z.ZodString>;
+    allowedUserIds: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    allowedChatIds: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    provider: "telegram";
+    enabled: boolean;
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    webhookSecret?: string | undefined;
+    botToken?: string | undefined;
+    webhookUrl?: string | undefined;
+    allowedUserIds?: number[] | undefined;
+    allowedChatIds?: number[] | undefined;
+}, {
+    id: string;
+    provider: "telegram";
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    enabled?: boolean | undefined;
+    webhookSecret?: string | undefined;
+    botToken?: string | undefined;
+    webhookUrl?: string | undefined;
+    allowedUserIds?: number[] | undefined;
+    allowedChatIds?: number[] | undefined;
+}>;
+type TelegramConfig = z.infer<typeof TelegramAccountConfigSchema>;
+/**
+ * Verify Telegram webhook request
+ * Uses timing-safe comparison to prevent timing attacks
+ */
+export declare function verifyTelegramWebhook(secretToken: string | undefined, requestSecretToken: string | undefined): boolean;
+/**
+ * Check if sender is allowed based on allowlists
+ */
+export declare function isTelegramSenderAllowed(config: TelegramConfig, userId?: number, chatId?: number): {
+    allowed: boolean;
+    reason?: string;
+};
+declare function setConfig(config: TelegramConfig): void;
+declare function clearConfig(): void;
+/**
+ * Set webhook URL for the bot
+ */
+export declare function setTelegramWebhook(botToken: string, webhookUrl: string, secretToken?: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Remove webhook (switch to polling)
+ */
+export declare function deleteTelegramWebhook(botToken: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Get webhook info
+ */
+export declare function getTelegramWebhookInfo(botToken: string): Promise<{
+    url: string;
+    hasCustomCertificate: boolean;
+    pendingUpdateCount: number;
+    lastErrorDate?: number;
+    lastErrorMessage?: string;
+} | null>;
+/**
+ * Answer a callback query (inline keyboard button click)
+ */
+export declare function answerTelegramCallbackQuery(botToken: string, callbackQueryId: string, text?: string, showAlert?: boolean): Promise<{
+    success: boolean;
+}>;
+export declare const telegramProvider: ChatProvider<TelegramAccountConfig>;
+export { setConfig as setTelegramConfig, clearConfig as clearTelegramConfig };
+export { TelegramAccountConfigSchema };
+export type { TelegramConfig, TelegramUpdate, TelegramMessage, TelegramCallbackQuery };
+//# sourceMappingURL=index.d.ts.map

package/dist/chat/providers/telegram/index.js

@@ -0,0 +1,492 @@
+/**
+ * Telegram Provider - Full Implementation
+ *
+ * Secure Telegram Bot integration with:
+ * - Webhook signature verification (X-Telegram-Bot-Api-Secret-Token)
+ * - Message sending via Bot API
+ * - Bot commands (/command syntax)
+ * - Inline keyboards for interactive UI
+ * - Reply-to for threaded conversations
+ */
+import { z } from 'zod';
+import { timingSafeEqual } from 'crypto';
+import { logger } from '../../../utils/logger.js';
+import { chunkForPlatform } from '../../format/chunk.js';
+// CONFIGURATION
+const TelegramAccountConfigSchema = z.object({
+    id: z.string(),
+    name: z.string().optional(),
+    enabled: z.boolean().default(true),
+    isDefault: z.boolean().optional(),
+    provider: z.literal('telegram'),
+    botToken: z.string().optional(),
+    webhookUrl: z.string().optional(),
+    webhookSecret: z.string().optional(),
+    // Security: allowlists
+    allowedUserIds: z.array(z.number()).optional(),
+    allowedChatIds: z.array(z.number()).optional(),
+});
+// METADATA
+const meta = {
+    id: 'telegram',
+    name: 'Telegram',
+    description: 'Telegram Bot integration with commands and inline keyboards',
+    icon: '✈️',
+    docsUrl: 'https://core.telegram.org/bots/api',
+    order: 3,
+    color: '#0088CC',
+};
+// CAPABILITIES
+const capabilities = {
+    chatTypes: ['direct', 'group', 'channel'],
+    send: true,
+    receive: true,
+    slashCommands: true,
+    interactiveComponents: true,
+    reactions: true,
+    edit: true,
+    delete: true,
+    threads: false, // Telegram uses reply-to
+    media: true,
+    richBlocks: false, // Uses HTML/Markdown
+    oauth: false,
+    webhooks: true,
+    realtime: true, // Long polling available
+};
+// HELPER FUNCTIONS
+const TELEGRAM_API_BASE = 'https://api.telegram.org';
+async function callTelegramApi(botToken, method, params) {
+    const url = `${TELEGRAM_API_BASE}/bot${botToken}/${method}`;
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(params || {}),
+        });
+        const data = await response.json();
+        return data;
+    }
+    catch (error) {
+        logger.error('[Telegram] API call failed:', error instanceof Error ? error : undefined);
+        return {
+            ok: false,
+            description: error instanceof Error ? error.message : 'Unknown error',
+        };
+    }
+}
+function getChatType(type) {
+    switch (type) {
+        case 'private':
+            return 'direct';
+        case 'group':
+        case 'supergroup':
+            return 'group';
+        case 'channel':
+            return 'channel';
+        default:
+            return 'group';
+    }
+}
+function formatUserName(user) {
+    if (user.username)
+        return `@${user.username}`;
+    const parts = [user.first_name, user.last_name].filter(Boolean);
+    return parts.join(' ') || `User ${user.id}`;
+}
+// AUTH ADAPTER
+const authAdapter = {
+    getAuthUrl() {
+        // Telegram bots don't use OAuth - token from BotFather
+        throw new Error('Telegram uses bot tokens from @BotFather, not OAuth');
+    },
+    async exchangeCode() {
+        throw new Error('Telegram uses bot tokens from @BotFather, not OAuth');
+    },
+    /**
+     * Verify webhook signature
+     * Telegram uses X-Telegram-Bot-Api-Secret-Token header
+     */
+    verifyWebhook(signature, _timestamp, _body) {
+        // For Telegram, the signature IS the secret token
+        // The caller should have already extracted it from the header
+        // and should compare it against the configured secret
+        // This adapter method is used for the interface, actual verification
+        // is done in the route handler
+        return !!signature;
+    },
+};
+/**
+ * Verify Telegram webhook request
+ * Uses timing-safe comparison to prevent timing attacks
+ */
+export function verifyTelegramWebhook(secretToken, requestSecretToken) {
+    if (!secretToken || !requestSecretToken) {
+        return !secretToken; // If no secret configured, allow all (not recommended)
+    }
+    try {
+        const expected = Buffer.from(secretToken);
+        const received = Buffer.from(requestSecretToken);
+        if (expected.length !== received.length)
+            return false;
+        return timingSafeEqual(expected, received);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if sender is allowed based on allowlists
+ */
+export function isTelegramSenderAllowed(config, userId, chatId) {
+    const { allowedUserIds, allowedChatIds } = config;
+    // If no allowlists configured, allow all
+    if (!allowedUserIds?.length && !allowedChatIds?.length) {
+        return { allowed: true };
+    }
+    // Check user allowlist
+    if (allowedUserIds?.length && userId) {
+        if (!allowedUserIds.includes(userId)) {
+            return { allowed: false, reason: `User ${userId} not in allowlist` };
+        }
+    }
+    // Check chat allowlist
+    if (allowedChatIds?.length && chatId) {
+        if (!allowedChatIds.includes(chatId)) {
+            return { allowed: false, reason: `Chat ${chatId} not in allowlist` };
+        }
+    }
+    return { allowed: true };
+}
+// OUTBOUND ADAPTER
+let currentConfig = null;
+function setConfig(config) {
+    currentConfig = config;
+}
+function clearConfig() {
+    currentConfig = null;
+}
+const outboundAdapter = {
+    async send(message) {
+        if (!currentConfig?.botToken) {
+            return { success: false, error: 'Bot token not configured' };
+        }
+        const textChunks = message.text
+            ? chunkForPlatform(message.text, 'telegram', { mode: 'newline' }).chunks
+            : [];
+        const chunks = textChunks.length > 0 ? textChunks : [undefined];
+        let replyToId = message.replyToId ? parseInt(message.replyToId, 10) : undefined;
+        let firstMessage;
+        for (const [index, chunk] of chunks.entries()) {
+            const params = {
+                chat_id: message.to,
+                parse_mode: 'HTML',
+            };
+            if (chunk !== undefined) {
+                params.text = chunk;
+            }
+            if (replyToId) {
+                params.reply_to_message_id = replyToId;
+            }
+            if (message.blocks && Array.isArray(message.blocks) && index === 0) {
+                const firstBlock = message.blocks[0];
+                if (firstBlock && 'inline_keyboard' in firstBlock) {
+                    params.reply_markup = firstBlock;
+                }
+            }
+            const result = await callTelegramApi(currentConfig.botToken, 'sendMessage', params);
+            if (!result.ok || !result.result) {
+                return {
+                    success: false,
+                    error: result.description || 'Failed to send message',
+                };
+            }
+            if (!firstMessage) {
+                firstMessage = result.result;
+                replyToId = result.result.message_id;
+            }
+        }
+        return {
+            success: true,
+            messageId: firstMessage ? String(firstMessage.message_id) : undefined,
+            raw: { chunkCount: chunks.length },
+        };
+    },
+    async edit(messageId, channelId, content) {
+        if (!currentConfig?.botToken) {
+            return { success: false, error: 'Bot token not configured' };
+        }
+        const params = {
+            chat_id: channelId,
+            message_id: parseInt(messageId, 10),
+            parse_mode: 'HTML',
+        };
+        if (content.text) {
+            params.text = content.text;
+        }
+        if (content.blocks) {
+            params.reply_markup = content.blocks;
+        }
+        const result = await callTelegramApi(currentConfig.botToken, 'editMessageText', params);
+        return {
+            success: result.ok,
+            messageId: result.ok ? messageId : undefined,
+            error: result.description,
+        };
+    },
+    async delete(messageId, channelId) {
+        if (!currentConfig?.botToken) {
+            return { success: false, error: 'Bot token not configured' };
+        }
+        const result = await callTelegramApi(currentConfig.botToken, 'deleteMessage', {
+            chat_id: channelId,
+            message_id: parseInt(messageId, 10),
+        });
+        return {
+            success: result.ok,
+            error: result.description,
+        };
+    },
+    async react(messageId, channelId, emoji) {
+        if (!currentConfig?.botToken) {
+            return { success: false };
+        }
+        // Telegram's setMessageReaction API
+        const result = await callTelegramApi(currentConfig.botToken, 'setMessageReaction', {
+            chat_id: channelId,
+            message_id: parseInt(messageId, 10),
+            reaction: [{ type: 'emoji', emoji }],
+        });
+        return { success: result.ok };
+    },
+    async unreact(messageId, channelId) {
+        if (!currentConfig?.botToken) {
+            return { success: false };
+        }
+        // Remove all reactions
+        const result = await callTelegramApi(currentConfig.botToken, 'setMessageReaction', {
+            chat_id: channelId,
+            message_id: parseInt(messageId, 10),
+            reaction: [],
+        });
+        return { success: result.ok };
+    },
+};
+// INBOUND ADAPTER
+const inboundAdapter = {
+    parseMessage(payload) {
+        const update = payload;
+        const message = update.message || update.edited_message;
+        if (!message || !message.from)
+            return null;
+        return {
+            id: String(message.message_id),
+            provider: 'telegram',
+            accountId: currentConfig?.id || 'default',
+            senderId: String(message.from.id),
+            senderName: formatUserName(message.from),
+            senderUsername: message.from.username,
+            chatType: getChatType(message.chat.type),
+            chatId: String(message.chat.id),
+            chatName: message.chat.title || message.chat.first_name,
+            replyToId: message.reply_to_message
+                ? String(message.reply_to_message.message_id)
+                : undefined,
+            text: message.text || '',
+            rawContent: update,
+            timestamp: new Date(message.date * 1000),
+            editedAt: update.edited_message ? new Date() : undefined,
+            attachments: parseAttachments(message),
+        };
+    },
+    parseCommand(payload) {
+        const update = payload;
+        const message = update.message;
+        if (!message || !message.from || !message.text)
+            return null;
+        // Check for bot command entity
+        const commandEntity = message.entities?.find(e => e.type === 'bot_command' && e.offset === 0);
+        if (!commandEntity)
+            return null;
+        const fullCommand = message.text.slice(0, commandEntity.length);
+        const text = message.text.slice(commandEntity.length).trim();
+        // Handle commands like /help@BotName
+        const [command] = fullCommand.split('@');
+        return {
+            provider: 'telegram',
+            accountId: currentConfig?.id || 'default',
+            command,
+            text,
+            userId: String(message.from.id),
+            userName: formatUserName(message.from),
+            channelId: String(message.chat.id),
+            channelName: message.chat.title,
+            chatType: getChatType(message.chat.type),
+            raw: update,
+        };
+    },
+    parseAction(payload) {
+        const update = payload;
+        const callbackQuery = update.callback_query;
+        if (!callbackQuery)
+            return null;
+        return {
+            provider: 'telegram',
+            accountId: currentConfig?.id || 'default',
+            type: 'button',
+            actionId: callbackQuery.id,
+            value: callbackQuery.data,
+            userId: String(callbackQuery.from.id),
+            userName: formatUserName(callbackQuery.from),
+            channelId: callbackQuery.message ? String(callbackQuery.message.chat.id) : undefined,
+            messageId: callbackQuery.message ? String(callbackQuery.message.message_id) : undefined,
+            raw: update,
+        };
+    },
+    buildCommandResponse(response) {
+        const result = {
+            method: 'sendMessage',
+            parse_mode: 'HTML',
+        };
+        if (response.text) {
+            result.text = response.text;
+        }
+        // Convert blocks to Telegram inline keyboard
+        if (response.blocks && Array.isArray(response.blocks)) {
+            result.reply_markup = {
+                inline_keyboard: response.blocks,
+            };
+        }
+        return result;
+    },
+    buildActionResponse(response) {
+        // For callback queries, we can either answer the query
+        // or edit the original message
+        return {
+            method: response.text ? 'answerCallbackQuery' : 'editMessageText',
+            text: response.text,
+            show_alert: response.responseType === 'ephemeral',
+        };
+    },
+};
+function parseAttachments(message) {
+    const attachments = [];
+    if (message.photo && message.photo.length > 0) {
+        // Get highest resolution photo
+        const photo = message.photo[message.photo.length - 1];
+        attachments.push({
+            type: 'image',
+            name: `photo_${photo.file_id}`,
+        });
+    }
+    if (message.document) {
+        attachments.push({
+            type: 'file',
+            name: message.document.file_name,
+            mimeType: message.document.mime_type,
+        });
+    }
+    return attachments.length > 0 ? attachments : undefined;
+}
+// STATUS ADAPTER
+const statusAdapter = {
+    isConfigured(config) {
+        return !!config.botToken;
+    },
+    async checkHealth(config) {
+        if (!config.botToken) {
+            return { connected: false, error: 'Bot token not configured' };
+        }
+        const start = Date.now();
+        const result = await callTelegramApi(config.botToken, 'getMe');
+        const latencyMs = Date.now() - start;
+        if (result.ok && result.result) {
+            return {
+                connected: true,
+                latencyMs,
+                details: {
+                    botId: result.result.id,
+                    botUsername: result.result.username,
+                    botName: result.result.first_name,
+                },
+            };
+        }
+        return {
+            connected: false,
+            latencyMs,
+            error: result.description || 'Failed to connect',
+        };
+    },
+};
+// WEBHOOK MANAGEMENT
+/**
+ * Set webhook URL for the bot
+ */
+export async function setTelegramWebhook(botToken, webhookUrl, secretToken) {
+    const params = {
+        url: webhookUrl,
+        allowed_updates: ['message', 'edited_message', 'callback_query'],
+    };
+    if (secretToken) {
+        params.secret_token = secretToken;
+    }
+    const result = await callTelegramApi(botToken, 'setWebhook', params);
+    return {
+        success: result.ok,
+        error: result.description,
+    };
+}
+/**
+ * Remove webhook (switch to polling)
+ */
+export async function deleteTelegramWebhook(botToken) {
+    const result = await callTelegramApi(botToken, 'deleteWebhook');
+    return {
+        success: result.ok,
+        error: result.description,
+    };
+}
+/**
+ * Get webhook info
+ */
+export async function getTelegramWebhookInfo(botToken) {
+    const result = await callTelegramApi(botToken, 'getWebhookInfo');
+    if (result.ok && result.result) {
+        return {
+            url: result.result.url,
+            hasCustomCertificate: result.result.has_custom_certificate,
+            pendingUpdateCount: result.result.pending_update_count,
+            lastErrorDate: result.result.last_error_date,
+            lastErrorMessage: result.result.last_error_message,
+        };
+    }
+    return null;
+}
+/**
+ * Answer a callback query (inline keyboard button click)
+ */
+export async function answerTelegramCallbackQuery(botToken, callbackQueryId, text, showAlert = false) {
+    const result = await callTelegramApi(botToken, 'answerCallbackQuery', {
+        callback_query_id: callbackQueryId,
+        text,
+        show_alert: showAlert,
+    });
+    return { success: result.ok };
+}
+// PROVIDER EXPORT
+export const telegramProvider = {
+    meta,
+    capabilities,
+    defaultConfig: {
+        provider: 'telegram',
+        enabled: true,
+    },
+    configSchema: TelegramAccountConfigSchema,
+    auth: authAdapter,
+    outbound: outboundAdapter,
+    inbound: inboundAdapter,
+    status: statusAdapter,
+};
+// Export helpers to set/clear config for outbound calls
+export { setConfig as setTelegramConfig, clearConfig as clearTelegramConfig };
+export { TelegramAccountConfigSchema };
+//# sourceMappingURL=index.js.map

package/dist/chat/providers/tlon/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Tlon Provider - Urbit/Tlon messaging via ship HTTP API
+ * Connects to an Urbit ship for decentralized messaging.
+ * API: ship HTTP interface (Eyre)
+ */
+import { z } from 'zod';
+import type { ChatProvider, TlonAccountConfig } from '../types.js';
+export declare const TlonAccountConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodLiteral<"tlon">;
+    shipUrl: z.ZodOptional<z.ZodString>;
+    shipCode: z.ZodOptional<z.ZodString>;
+    shipName: z.ZodOptional<z.ZodString>;
+    channelPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    provider: "tlon";
+    enabled: boolean;
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    shipUrl?: string | undefined;
+    shipCode?: string | undefined;
+    shipName?: string | undefined;
+    channelPath?: string | undefined;
+}, {
+    id: string;
+    provider: "tlon";
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    enabled?: boolean | undefined;
+    shipUrl?: string | undefined;
+    shipCode?: string | undefined;
+    shipName?: string | undefined;
+    channelPath?: string | undefined;
+}>;
+type TlonConfig = z.infer<typeof TlonAccountConfigSchema>;
+export declare function setTlonConfig(config: TlonConfig): void;
+export declare function clearTlonConfig(): void;
+export declare const tlonProvider: ChatProvider<TlonAccountConfig>;
+export type { TlonConfig };
+//# sourceMappingURL=index.d.ts.map