@synapta/skills 0.1.0 → 0.1.2

package/skills/telegram-control/references/initial_setup.md

@@ -0,0 +1,165 @@
+# Telegram Reminders Setup Guide
+
+This guide will help you set up the Telegram Reminders skill, especially in sandboxed environments like Claude's computer.
+
+## Quick Setup (3 Steps)
+
+### Step 1: Get Your Credentials
+
+1. **Bot Token**:
+
+   - Open Telegram and message [@BotFather](https://t.me/BotFather)
+   - Send `/newbot` and follow the prompts
+   - Copy the bot token (format: `1234567890:ABCdefGHIjklMNOpqrsTUVwxyz`)
+
+2. **User ID**:
+
+   - Message [@userinfobot](https://t.me/userinfobot) on Telegram
+   - Copy your numeric ID (format: `123456789`)
+
+3. **Convex Deploy Key**:
+   - Go to [dashboard.convex.dev](https://dashboard.convex.dev)
+   - Create a new project (or use existing)
+   - Go to Settings → Deploy Keys
+   - Create a "Production" deploy key
+   - Copy the key (format: `prod:name-123|abc123def...`)
+
+### Step 2: Run Setup
+
+```bash
+cd /mnt/skills/user/telegram-reminders
+npm install
+tsx scripts/setup.ts <bot_token> <user_id> <deploy_key>
+```
+
+The setup will:
+
+- Save your credentials
+- Deploy to Convex Cloud
+- Configure environment variables
+- Attempt to send a test message
+
+**Note**: Scripts use `undici` with automatic proxy detection for network requests, ensuring compatibility with sandboxed environments.
+
+### Step 3: Start Chat with Your Bot
+
+**CRITICAL**: You must do this before the bot can send you messages!
+
+1. Open Telegram
+2. Search for your bot (by the name you gave it in BotFather)
+3. Click on it and press "Start"
+
+## Using the Skill
+
+Use the tsx scripts for all operations:
+
+```bash
+# Send a message
+tsx scripts/send_message.ts "Hello!"
+
+# Send with file attachment
+tsx scripts/send_message.ts "Check this file" /path/to/file.pdf
+
+# Schedule a reminder
+tsx scripts/schedule_message.ts "Meeting" "Team standup" "tomorrow 10am"
+
+# List pending messages
+tsx scripts/list_scheduled.ts
+
+# Cancel a message
+tsx scripts/cancel_message.ts <message_id>
+
+# View history
+tsx scripts/view_history.ts 50
+```
+
+## Common Issues
+
+### "EAI_AGAIN" DNS Error
+
+**Cause**: DNS resolution failure in sandboxed environments.
+
+**Solution**: Scripts now use `undici` with automatic proxy detection from `HTTP_PROXY`/`HTTPS_PROXY` environment variables. This should work automatically.
+
+### "Unauthorized" or "bot was blocked"
+
+**Cause**: You haven't started a chat with your bot.
+
+**Solution**:
+
+1. Open Telegram
+2. Search for your bot
+3. Press "Start"
+
+### Messages Not Sending
+
+**Cause**: Environment variables not set in Convex.
+
+**Solution**:
+
+```bash
+npx convex env set TELEGRAM_BOT_TOKEN "your_token"
+npx convex env set TELEGRAM_USER_ID "your_id"
+```
+
+### Setup Script Fails at Verification
+
+**Cause**: Network issues during setup.
+
+**Solution**: Verify manually by sending a test message:
+
+```bash
+tsx scripts/send_message.ts "Test message"
+```
+
+## Manual Setup (If Script Fails)
+
+If the setup script doesn't work, you can set up manually:
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Create config file
+cat > /mnt/user-data/outputs/telegram_config.json << EOF
+{
+  "botToken": "YOUR_BOT_TOKEN",
+  "userId": "YOUR_USER_ID",
+  "deployKey": "YOUR_DEPLOY_KEY",
+  "setupDate": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+}
+EOF
+
+# 3. Create .env.local
+echo "CONVEX_DEPLOY_KEY=YOUR_DEPLOY_KEY" > .env.local
+
+# 4. Deploy to Convex
+npx convex deploy
+
+# 5. Set environment variables
+npx convex env set TELEGRAM_BOT_TOKEN "YOUR_BOT_TOKEN"
+npx convex env set TELEGRAM_USER_ID "YOUR_USER_ID"
+
+# 6. Test
+tsx scripts/send_message.ts "Setup test!"
+```
+
+## Verification
+
+To verify everything is working:
+
+```bash
+# Check Convex deployment
+npx convex env list
+
+# Send test message
+tsx scripts/send_message.ts "Test!"
+
+# Check for message in Telegram
+```
+
+## Need Help?
+
+- Check the main [SKILL.md](SKILL.md) for detailed documentation
+- Monitor your deployment at [dashboard.convex.dev](https://dashboard.convex.dev)
+- Review Convex logs: `npx convex logs --watch`

package/skills/telegram-control/references/telegram_api.md

@@ -0,0 +1,156 @@
+# Telegram Bot API Reference
+
+## Quick Reference
+
+| Action       | Endpoint                        |
+| ------------ | ------------------------------- |
+| Send text    | `POST /bot<TOKEN>/sendMessage`  |
+| Send file    | `POST /bot<TOKEN>/sendDocument` |
+| Get bot info | `GET /bot<TOKEN>/getMe`         |
+
+Base URL: `https://api.telegram.org`
+
+## Bot Setup
+
+### 1. Create a Bot
+
+1. Message [@BotFather](https://t.me/BotFather) on Telegram
+2. Send `/newbot`
+3. Follow prompts to name your bot
+4. Copy the token (format: `123456789:ABCdefGHI...`)
+
+### 2. Get Your User ID
+
+1. Message [@userinfobot](https://t.me/userinfobot)
+2. Copy the numeric ID it returns
+
+### 3. Start Chat with Bot (Critical!)
+
+Before the bot can message you:
+
+1. Search for your bot by username in Telegram
+2. Press "Start" to begin the chat
+
+## API Endpoints
+
+### Send Text Message
+
+```bash
+curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "chat_id": "123456789",
+    "text": "Your message",
+    "parse_mode": "Markdown"
+  }'
+```
+
+**Parameters**:
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `chat_id` | Yes | User ID (numeric) |
+| `text` | Yes | Message content (max 4096 chars) |
+| `parse_mode` | No | `Markdown` or `HTML` |
+
+### Send Document
+
+```bash
+curl -X POST "https://api.telegram.org/bot<TOKEN>/sendDocument" \
+  -F "chat_id=123456789" \
+  -F "document=@/path/to/file.md" \
+  -F "caption=Optional caption"
+```
+
+**Parameters**:
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `chat_id` | Yes | User ID |
+| `document` | Yes | File to send |
+| `caption` | No | Text caption (max 1024 chars) |
+
+### Verify Bot Token
+
+```bash
+curl "https://api.telegram.org/bot<TOKEN>/getMe"
+```
+
+Returns `{"ok": true, "result": {...}}` if valid.
+
+## Text Formatting
+
+### Markdown Mode
+
+````
+*bold*
+_italic_
+`code`
+```code block```
+[link](https://example.com)
+````
+
+### HTML Mode
+
+```html
+<b>bold</b>
+<i>italic</i>
+<code>code</code>
+<pre>code block</pre>
+<a href="https://example.com">link</a>
+```
+
+**Note**: Escape special characters in user input to avoid parsing errors.
+
+## Error Codes
+
+| Code | Error             | Cause                                   | Solution                         |
+| ---- | ----------------- | --------------------------------------- | -------------------------------- |
+| 401  | Unauthorized      | Invalid bot token                       | Verify token with `/getMe`       |
+| 400  | chat not found    | Invalid user ID                         | Get correct ID from @userinfobot |
+| 403  | bot was blocked   | User blocked bot or hasn't started chat | User must press "Start"          |
+| 429  | Too Many Requests | Rate limit exceeded                     | Wait and retry                   |
+
+## Limits
+
+| Limit                      | Value           |
+| -------------------------- | --------------- |
+| Message length             | 4096 characters |
+| Caption length             | 1024 characters |
+| File size                  | 50 MB           |
+| Messages/second (global)   | 30              |
+| Messages/minute (per user) | 20              |
+
+## Best Practices
+
+1. **Always check `response.ok`** before processing results
+2. **Implement retry logic** with exponential backoff for 429 errors
+3. **Escape special characters** in Markdown/HTML to prevent parsing errors
+4. **Keep messages concise** - split long content into multiple messages
+5. **Use documents for files** - preserves quality better than inline
+
+## Example: Send with Error Handling
+
+```typescript
+async function sendTelegram(token: string, chatId: string, text: string) {
+  const response = await fetch(
+    `https://api.telegram.org/bot${token}/sendMessage`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ chat_id: chatId, text }),
+    }
+  );
+
+  const data = await response.json();
+  if (!data.ok) {
+    throw new Error(`Telegram error: ${data.description}`);
+  }
+  return data.result;
+}
+```
+
+## Resources
+
+- **Official Docs**: [core.telegram.org/bots/api](https://core.telegram.org/bots/api)
+- **Bot Tutorial**: [core.telegram.org/bots/tutorial](https://core.telegram.org/bots/tutorial)
+- **BotFather**: [@BotFather](https://t.me/BotFather)
+- **User Info Bot**: [@userinfobot](https://t.me/userinfobot)

package/skills/telegram-control/scripts/cancel_message.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env tsx
+
+import { ConvexHttpClient } from "convex/browser";
+import { readFileSync, existsSync } from "fs";
+import { api } from "../convex/_generated/api.js";
+import { Id } from "../convex/_generated/dataModel.js";
+import { Config, CONFIG_PATH, getConvexUrl } from "./types.js";
+import { logError, logSuccess, logInfo, logUsage, logNotConfigured } from "./logger.js";
+import { setupProxy } from "./proxy-util.js";
+
+setupProxy();
+
+async function cancelMessage(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  if (args.length < 1) {
+    logUsage("Usage: tsx cancel_message.ts <message_id>", [
+      "Get message IDs with: npm run list",
+    ]);
+    process.exit(1);
+  }
+
+  const messageId = args[0] as Id<"scheduled_messages">;
+
+  // Load config
+  if (!existsSync(CONFIG_PATH)) {
+    logNotConfigured();
+  }
+
+  const config: Config = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+
+  // Get Convex URL
+  const deploymentUrl = getConvexUrl(config.deployKey);
+  const client = new ConvexHttpClient(deploymentUrl);
+
+  logInfo("🗑️", `Cancelling message ${messageId}...`);
+
+  try {
+    await client.mutation(api.messages.cancelMessage, {
+      messageId,
+    });
+
+    logSuccess("Message cancelled successfully!");
+  } catch (error: any) {
+    logError(`Failed to cancel: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+cancelMessage().catch((error: Error) => {
+  logError(error.message);
+  process.exit(1);
+});

package/skills/telegram-control/scripts/list_scheduled.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env tsx
+
+import { ConvexHttpClient } from "convex/browser";
+import { readFileSync, existsSync } from "fs";
+import { api } from "../convex/_generated/api.js";
+import { Config, CONFIG_PATH, ScheduledMessage, getConvexUrl } from "./types.js";
+import { setupProxy } from "./proxy-util.js";
+import {
+  logError,
+  logInfo,
+  log,
+  logSeparator,
+  logNotConfigured,
+  logMessageEntry,
+} from "./logger.js";
+
+setupProxy();
+
+async function listScheduled(): Promise<void> {
+  // Load config
+  if (!existsSync(CONFIG_PATH)) {
+    logNotConfigured();
+  }
+
+  const config: Config = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+
+  // Get Convex URL
+  const deploymentUrl = getConvexUrl(config.deployKey);
+  const client = new ConvexHttpClient(deploymentUrl);
+
+  logInfo("📋", "Fetching scheduled messages...\n");
+
+  try {
+    const messages = await client.query(api.messages.listScheduled, {}) as ScheduledMessage[];
+
+    if (messages.length === 0) {
+      log("No scheduled messages found.");
+      return;
+    }
+
+    // Group by status
+    const pending = messages.filter((m) => m.status === "pending");
+    const sent = messages.filter((m) => m.status === "sent");
+    const failed = messages.filter((m) => m.status === "failed");
+
+    if (pending.length > 0) {
+      log("⏰ PENDING MESSAGES:");
+      logSeparator();
+      pending.forEach((msg) => {
+        const time = new Date(msg.scheduled_time).toLocaleString();
+        const preview = msg.message_text
+          ? msg.message_text.substring(0, 50) + "..."
+          : undefined;
+
+        logMessageEntry({
+          id: msg._id,
+          title: msg.title,
+          time,
+          recurring: msg.recurring,
+          message: preview,
+          fileName: msg.file_name,
+        });
+      });
+      log("\n" + "─".repeat(60));
+    }
+
+    if (sent.length > 0) {
+      log(`\n✅ SENT MESSAGES (${sent.length}):`);
+      logSeparator();
+      sent.slice(0, 5).forEach((msg) => {
+        const time = new Date(msg.last_sent_at || msg.scheduled_time).toLocaleString();
+        log(`\n${msg.title} - ${time}`);
+      });
+      if (sent.length > 5) {
+        log(`\n... and ${sent.length - 5} more`);
+      }
+      log("\n" + "─".repeat(60));
+    }
+
+    if (failed.length > 0) {
+      log(`\n❌ FAILED MESSAGES (${failed.length}):`);
+      logSeparator();
+      failed.forEach((msg) => {
+        logMessageEntry({
+          id: msg._id,
+          title: msg.title,
+          error: msg.error_message,
+        });
+      });
+      log("\n" + "─".repeat(60));
+    }
+
+    log(`\nTotal: ${messages.length} messages`);
+  } catch (error: any) {
+    logError(`Failed to list messages: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+listScheduled().catch((error: Error) => {
+  logError(error.message);
+  process.exit(1);
+});

package/skills/telegram-control/scripts/logger.ts

@@ -0,0 +1,121 @@
+/**
+ * Centralized logging utilities for CLI scripts
+ */
+
+import pino from "pino";
+
+const transport = pino.transport({
+  target: "pino-pretty",
+  options: {
+    colorize: true,
+    ignore: "pid,hostname,level,time",
+    messageFormat: "{msg}",
+  },
+});
+
+export const logger = pino(
+  {
+    level: process.env.LOG_LEVEL || "info",
+    base: null,
+    timestamp: false,
+  },
+  transport
+);
+
+/**
+ * Log an error message with [!] prefix
+ */
+export function logError(message: string): void {
+  logger.error(`[!] ${message}`);
+}
+
+/**
+ * Log a success message with [+] prefix
+ */
+export function logSuccess(message: string): void {
+  logger.info(`[+] ${message}`);
+}
+
+/**
+ * Log an info message with custom emoji prefix
+ */
+export function logInfo(emoji: string, message: string): void {
+  logger.info(`${emoji} ${message}`);
+}
+
+/**
+ * Log a message without prefix
+ */
+export function log(message: string): void {
+  logger.info(message);
+}
+
+/**
+ * Log a separator line
+ */
+export function logSeparator(length: number = 60): void {
+  logger.info("-".repeat(length));
+}
+
+/**
+ * Log an indented detail line
+ */
+export function logDetail(message: string, indent: string = "   "): void {
+  logger.info(`${indent}${message}`);
+}
+
+/**
+ * Log usage help for a script
+ */
+export function logUsage(usage: string, examples?: string[]): void {
+  logger.error(usage);
+  if (examples && examples.length > 0) {
+    logger.error("");
+    logger.error("Examples:");
+    examples.forEach((example) => logger.error(`  ${example}`));
+  }
+}
+
+/**
+ * Log a section header with optional emoji
+ */
+export function logSection(emoji: string, title: string): void {
+  logger.info(`\n${emoji} ${title}`);
+  logSeparator();
+}
+
+/**
+ * Log not configured error and exit
+ */
+export function logNotConfigured(): never {
+  logError("Not configured. Run: npm run setup");
+  process.exit(1);
+}
+
+/**
+ * Log a structured message entry with details
+ */
+export function logMessageEntry(details: {
+  id?: string;
+  title: string;
+  time?: string;
+  recurring?: string;
+  message?: string;
+  fileName?: string;
+  error?: string;
+  status?: string;
+  index?: number;
+}): void {
+  const prefix = details.index ? `${details.index}. ` : "";
+  const statusEmoji =
+    details.status === "sent" ? "[+]" : details.status === "failed" ? "[!]" : "";
+
+  log(`\n${prefix}${statusEmoji ? statusEmoji + " " : ""}${details.title}`);
+
+  if (details.id) logDetail(`ID: ${details.id}`);
+  if (details.time) logDetail(`Time: ${details.time}`);
+  if (details.recurring) logDetail(`Recurring: ${details.recurring}`);
+  if (details.message) logDetail(`Message: ${details.message}`);
+  if (details.fileName) logDetail(`File: ${details.fileName}`);
+  if (details.error) logDetail(`Error: ${details.error}`);
+}

package/skills/telegram-control/scripts/proxy-util.ts

@@ -0,0 +1,11 @@
+import { ProxyAgent, setGlobalDispatcher } from "undici";
+
+export function setupProxy(): void {
+  const proxyUrl = process.env.HTTP_PROXY || process.env.HTTPS_PROXY;
+  if (!proxyUrl) {
+    return;
+  }
+
+  const proxyAgent = new ProxyAgent(proxyUrl);
+  setGlobalDispatcher(proxyAgent);
+}