@synapta/skills 0.1.0 → 0.1.2

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

@@ -0,0 +1,184 @@
+# Architecture
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Convex Cloud (24/7)                       │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              Database (Document Store)               │   │
+│  │  ┌─────────────────────┐  ┌─────────────────────┐   │   │
+│  │  │ scheduled_messages  │  │   message_history   │   │   │
+│  │  │ - title             │  │ - title             │   │   │
+│  │  │ - message_text      │  │ - message_text      │   │   │
+│  │  │ - scheduled_time    │  │ - sent_at           │   │   │
+│  │  │ - status            │  │ - status            │   │   │
+│  │  │ - recurring         │  │ - error             │   │   │
+│  │  │ - storage_id        │  │                     │   │   │
+│  │  │ - file_name         │  │                     │   │   │
+│  │  └─────────────────────┘  └─────────────────────┘   │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │           Cron Job (every minute)                    │   │
+│  │  processScheduledMessages() → Telegram API           │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                   Functions                          │   │
+│  │  Queries:    listScheduled, viewHistory              │   │
+│  │  Mutations:  scheduleMessage, cancelMessage          │   │
+│  │  Actions:    sendMessage, processScheduledMessages   │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                    ↑                    ↓
+            ┌───────────────────────────────────────┐
+            │       Client Scripts (Claude)         │
+            │  send_message.ts, schedule_message.ts │
+            │  list_scheduled.ts, cancel_message.ts │
+            │  view_history.ts, setup.ts            │
+            └───────────────────────────────────────┘
+```
+
+## Convex Cloud Components
+
+### Database
+
+| Table                | Purpose                        | Key Fields                                                                    |
+| -------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
+| `scheduled_messages` | Pending and completed messages | title, message_text, scheduled_time, status, recurring, storage_id, file_name |
+| `message_history`    | Full send history              | title, message_text, sent_at, status, error                                   |
+
+Features:
+
+- Document-based storage with automatic indexing
+- ACID transactions with serializable isolation
+- Real-time subscriptions (available but not used)
+
+### Functions
+
+| Type          | Purpose                          | Examples                                             |
+| ------------- | -------------------------------- | ---------------------------------------------------- |
+| **Queries**   | Read-only database operations    | `listScheduled`, `viewHistory`, `getPendingMessages` |
+| **Mutations** | Read-write database transactions | `scheduleMessage`, `cancelMessage`, `markAsSent`     |
+| **Actions**   | External API calls (Telegram)    | `sendMessage`, `processScheduledMessages`            |
+| **Internal**  | Backend-only functions           | `getPendingMessages` (internalQuery)                 |
+
+### Cron Job
+
+Defined in `convex/crons.ts`:
+
+- Runs every minute
+- Queries for messages where `scheduled_time <= now` and `status == "pending"`
+- Sends each via Telegram API
+- Updates status to "sent" or "failed"
+- For recurring messages: calculates and schedules next occurrence
+
+## Local Components
+
+### Client Scripts (`scripts/`)
+
+| Script                | Purpose                              |
+| --------------------- | ------------------------------------ |
+| `setup.ts`            | Initial deployment and configuration |
+| `send_message.ts`     | Send immediate messages              |
+| `schedule_message.ts` | Schedule future messages             |
+| `list_scheduled.ts`   | List pending messages                |
+| `cancel_message.ts`   | Cancel scheduled messages            |
+| `view_history.ts`     | View message history                 |
+
+Scripts connect to Convex via HTTP using the deployment URL derived from the deploy key.
+
+### Configuration
+
+Stored at `/mnt/user-data/outputs/telegram_config.json`:
+
+```json
+{
+  "bot_token": "123456:ABC...",
+  "user_id": "123456789",
+  "deploy_key": "prod:deployment|key..."
+}
+```
+
+Persists across sessions for seamless operation.
+
+## Message Flow
+
+### Immediate Send
+
+```
+User Request → send_message.ts → Convex Action → Telegram API → User
+```
+
+### Scheduled Send
+
+```
+User Request → schedule_message.ts → Convex Mutation → Database
+                                                          ↓
+User ← Telegram API ← Convex Action ← Cron Job (every min) ←
+```
+
+### Recurring Messages
+
+```
+Cron Job → Send Message → Calculate Next Time → Create New Record
+              ↓                                        ↓
+         message_history                    scheduled_messages
+```
+
+## File Structure
+
+```
+telegram-reminders/
+├── convex/                    # Backend (Convex Cloud)
+│   ├── schema.ts             # Database schema definition
+│   ├── messages.ts           # Queries and mutations
+│   ├── telegram.ts           # Actions (Telegram API calls)
+│   ├── crons.ts              # Cron job definition
+│   └── tsconfig.json         # Convex TypeScript config
+├── scripts/                   # Client scripts (local)
+│   ├── setup.ts              # Initial setup + deploy
+│   ├── send_message.ts       # Send immediately
+│   ├── schedule_message.ts   # Schedule message
+│   ├── list_scheduled.ts     # List scheduled
+│   ├── cancel_message.ts     # Cancel message
+│   └── view_history.ts       # View history
+├── references/                # Documentation
+│   ├── architecture.md       # This file
+│   ├── convex.md             # Convex platform reference
+│   ├── telegram_api.md       # Telegram API reference
+│   ├── initial_setup.md      # Setup guide
+│   └── error_handling.md     # Troubleshooting guide
+├── package.json              # Dependencies and scripts
+└── tsconfig.json             # Root TypeScript config
+```
+
+## Security & Privacy
+
+| Aspect            | Implementation                                   |
+| ----------------- | ------------------------------------------------ |
+| Bot token         | Stored encrypted in Convex environment variables |
+| Deploy key        | Stored in local config file                      |
+| Communication     | All HTTPS                                        |
+| Platform security | Convex enterprise-grade infrastructure           |
+
+**Never share**: bot token, user ID, or deploy key publicly.
+
+## Dependencies
+
+### Root Package
+
+- `convex` - Convex client library
+- `chrono-node` - Natural language time parsing
+- `form-data` - File uploads to Telegram
+- `tsx` - TypeScript execution runtime
+- `undici` - HTTP client
+- `typescript` - TypeScript compiler
+- `@types/node` - Node.js type definitions
+
+### Convex Backend
+
+- TypeScript functions compiled automatically by Convex
+- No additional dependencies required

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

@@ -0,0 +1,173 @@
+# Convex Reference
+
+## Overview
+
+Convex is a backend-as-a-service platform providing:
+
+- **Reactive Database**: Real-time, document-relational database
+- **Serverless Functions**: TypeScript/JavaScript functions in the cloud
+- **Scheduled Jobs**: Cron jobs and scheduled functions
+- **Zero Infrastructure**: No server management or connection strings
+
+## Quick Reference
+
+| Feature    | Description                                                |
+| ---------- | ---------------------------------------------------------- |
+| Database   | Document-based, ACID transactions, automatic indexing      |
+| Functions  | Queries (read), Mutations (write), Actions (external APIs) |
+| Scheduling | Cron jobs + dynamic scheduling                             |
+| Deployment | `npx convex deploy` with deploy key                        |
+| Dashboard  | [dashboard.convex.dev](https://dashboard.convex.dev)       |
+
+## Function Types
+
+| Type         | Purpose        | Can Call External APIs | Database Access |
+| ------------ | -------------- | ---------------------- | --------------- |
+| **Query**    | Read data      | ❌                     | Read-only       |
+| **Mutation** | Write data     | ❌                     | Read-write      |
+| **Action**   | External calls | ✅                     | Via mutations   |
+| **Internal** | Backend-only   | Depends on type        | Depends on type |
+
+### Example Usage
+
+```typescript
+// Query - read-only
+export const listScheduled = query({
+  handler: async (ctx) => {
+    return await ctx.db.query('scheduled_messages').collect();
+  },
+});
+
+// Mutation - read-write
+export const scheduleMessage = mutation({
+  args: { title: v.string(), scheduled_time: v.number() },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert('scheduled_messages', args);
+  },
+});
+
+// Action - external API calls
+export const sendMessage = action({
+  args: { text: v.string() },
+  handler: async (ctx, args) => {
+    await fetch('https://api.telegram.org/...');
+  },
+});
+```
+
+## Scheduling
+
+### Cron Jobs (Static)
+
+Defined in `convex/crons.ts`:
+
+```typescript
+import { cronJobs } from 'convex/server';
+
+const crons = cronJobs();
+crons.interval(
+  'process-messages',
+  { minutes: 1 },
+  internal.telegram.processScheduledMessages
+);
+export default crons;
+```
+
+### Dynamic Scheduling
+
+Schedule functions from other functions:
+
+```typescript
+await ctx.scheduler.runAfter(delay, internal.myFunction, args);
+```
+
+## Deployment
+
+### Deploy Key Setup
+
+```bash
+# Set environment variable
+export CONVEX_DEPLOY_KEY="prod:deployment-name|key..."
+
+# Deploy
+npx convex deploy
+```
+
+Deploy keys grant permission to:
+
+- Push code and update schema
+- Set environment variables
+- View logs and dashboard
+
+### Environment Variables
+
+```bash
+# Set variables
+npx convex env set TELEGRAM_BOT_TOKEN "123456:ABC..."
+npx convex env set TELEGRAM_USER_ID "123456789"
+
+# List variables
+npx convex env list
+
+# Remove variable
+npx convex env unset VARIABLE_NAME
+```
+
+Access in functions: `process.env.VARIABLE_NAME`
+
+### Deployment URL
+
+Derived from deploy key:
+
+- Key: `prod:deployment-name|secret...`
+- URL: `https://deployment-name.convex.cloud`
+
+## Dashboard
+
+Access at [dashboard.convex.dev](https://dashboard.convex.dev):
+
+| Section       | Purpose                            |
+| ------------- | ---------------------------------- |
+| **Data**      | View/edit database tables          |
+| **Functions** | See function definitions and logs  |
+| **Logs**      | Real-time execution logs           |
+| **Crons**     | Monitor cron job runs              |
+| **Settings**  | Deploy keys, environment variables |
+
+## Free Tier
+
+| Resource            | Limit        |
+| ------------------- | ------------ |
+| Database storage    | Unlimited    |
+| Function executions | Unlimited    |
+| Bandwidth           | Unlimited    |
+| Credit card         | Not required |
+| Time limit          | None         |
+
+Perfect for personal projects and small-scale use.
+
+## CLI Commands
+
+```bash
+# Deploy to cloud
+npx convex deploy
+
+# View logs
+npx convex logs
+npx convex logs --watch  # Real-time
+
+# Environment variables
+npx convex env list
+npx convex env set KEY "value"
+npx convex env unset KEY
+
+# Development (local)
+npx convex dev
+```
+
+## Resources
+
+- **Documentation**: [docs.convex.dev](https://docs.convex.dev)
+- **Dashboard**: [dashboard.convex.dev](https://dashboard.convex.dev)
+- **Status**: [status.convex.dev](https://status.convex.dev)
+- **Examples**: [github.com/get-convex/convex-demos](https://github.com/get-convex/convex-demos)

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

@@ -0,0 +1,212 @@
+# Error Handling Guide
+
+## Quick Reference
+
+| Error                | Cause                    | Solution                                       |
+| -------------------- | ------------------------ | ---------------------------------------------- |
+| "Bot not configured" | Setup not run            | `tsx scripts/setup.ts <token> <id> <key>`      |
+| "Unauthorized"       | Invalid token or blocked | Verify token, start chat with bot              |
+| "chat not found"     | Wrong user ID            | Get ID from @userinfobot                       |
+| "EAI_AGAIN"          | DNS resolution failure   | Scripts use undici with proxy auto-detection   |
+| Deployment failed    | Invalid deploy key       | Get new key from dashboard                     |
+
+## Setup Errors
+
+### "Bot not configured"
+
+**Cause**: Configuration file missing or incomplete.
+
+**Solution**:
+
+```bash
+tsx scripts/setup.ts <bot_token> <user_id> <deploy_key>
+```
+
+### "Invalid deploy key format"
+
+**Cause**: Deploy key not copied correctly or expired.
+
+**Solution**:
+
+1. Go to [dashboard.convex.dev](https://dashboard.convex.dev)
+2. Navigate to your project → Settings → Deploy Keys
+3. Create a new "Production" deploy key
+4. Copy the full key (format: `prod:deployment-name|key...`)
+
+## Telegram API Errors
+
+### "Unauthorized" or "bot was blocked by the user"
+
+**Causes**:
+
+- User hasn't started chat with bot
+- Bot token is invalid
+- User blocked the bot
+
+**Solutions**:
+
+1. Search for your bot in Telegram by username
+2. Press "Start" to begin the chat
+3. Verify bot token: `curl "https://api.telegram.org/bot<TOKEN>/getMe"`
+
+### "chat not found"
+
+**Cause**: User ID is incorrect.
+
+**Solution**:
+
+1. Message [@userinfobot](https://t.me/userinfobot) on Telegram
+2. Copy the numeric ID it returns
+3. Update environment variable: `npx convex env set TELEGRAM_USER_ID "correct_id"`
+
+### Rate Limit (429 Too Many Requests)
+
+**Cause**: Exceeded Telegram's rate limits.
+
+**Limits**:
+
+- 30 messages/second globally
+- 20 messages/minute per user
+
+**Solution**: Wait and retry. For personal use, this is rarely hit.
+
+## Network Errors
+
+### "EAI_AGAIN" DNS Resolution Failure
+
+**Cause**: Node.js native fetch doesn't use the environment's egress proxy, causing DNS resolution failures in sandboxed environments.
+
+**Solution**: The tsx scripts now use `undici` with automatic proxy detection from `HTTP_PROXY`/`HTTPS_PROXY` environment variables. This is already configured in all scripts.
+
+**How it works**:
+
+- Scripts import `fetch` and `ProxyAgent` from `undici`
+- Proxy is auto-detected: `process.env.HTTP_PROXY || process.env.HTTPS_PROXY`
+- All fetch calls use `dispatcher: proxyAgent` option
+
+**If you still have issues**:
+
+1. Verify proxy environment variables are set
+2. Check that undici is installed: `npm list undici`
+3. Reinstall if needed: `npm install undici`
+
+### General Network Issues
+
+**Symptoms**: Timeouts, connection refused, DNS errors.
+
+**Solutions**:
+
+1. Check internet connection
+2. Verify proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`)
+3. Check Convex status at [status.convex.dev](https://status.convex.dev)
+4. Review logs: `npx convex logs`
+
+## Deployment Errors
+
+### "Could not resolve 'fs'" Error
+
+**Cause**: Missing `"use node";` directive.
+
+**Fix**: Ensure first line of `convex/telegram.ts` is:
+
+```typescript
+'use node';
+```
+
+### "Two output files share the same path" Error
+
+**Cause**: Duplicate .js files in convex directory.
+
+**Fix**:
+
+```bash
+rm -f convex/*.js convex/_generated/*.js
+npx convex deploy
+```
+
+### TypeScript "Property does not exist" Errors
+
+**Cause**: Missing type definitions or incorrect function visibility.
+
+**Fixes**:
+
+- Ensure internal functions use `internalQuery`/`internalMutation`
+- Add `as any` type assertions to fetch responses
+
+### "Cannot write file" TypeScript Error
+
+**Cause**: TypeScript trying to generate files that exist.
+
+**Fix**:
+
+```bash
+rm -f convex/_generated/*.js
+```
+
+## Message Delivery Issues
+
+### Messages Not Sending
+
+**Diagnostic steps**:
+
+1. **Check cron is running**:
+   - Convex Dashboard → Functions → Crons
+   - Should see `process-scheduled-messages` every minute
+
+2. **Verify environment variables**:
+
+   ```bash
+   npx convex env list
+   ```
+
+3. **Check pending messages**:
+   - Dashboard → Data → `scheduled_messages`
+   - Verify `status: "pending"` and `scheduled_time` is past
+
+4. **Review logs**:
+   ```bash
+   npx convex logs --watch
+   ```
+
+### Wrong Timestamp Format
+
+**Symptom**: Messages scheduled but never sent.
+
+**Cause**: Using seconds instead of milliseconds.
+
+**Correct format**: Unix timestamp in **milliseconds** (13 digits)
+
+- ✅ `1768355400000`
+- ❌ `1768355400`
+
+**Get current timestamp**:
+
+```javascript
+Date.now(); // JavaScript
+```
+
+```bash
+date +%s000  # Bash
+```
+
+## Debugging Commands
+
+```bash
+# Check configuration
+cat /mnt/user-data/outputs/telegram_config.json
+
+# Test database connection
+tsx scripts/list_scheduled.ts
+
+# Verify Telegram API
+tsx scripts/send_message.ts "test"
+
+# Check Convex deployment
+curl https://<deployment>.convex.cloud
+
+# Monitor real-time logs
+npx convex logs --watch
+
+# List environment variables
+npx convex env list
+```