@yesvara/svara 0.1.0

package/src/channels/telegram.ts

@@ -0,0 +1,122 @@
+/**
+ * @module channels/telegram
+ *
+ * Telegram Bot channel.
+ * Used when you call: `agent.connectChannel('telegram', { token: '...' })`
+ */
+
+import type { SvaraAgent, SvaraChannel } from '../core/agent.js';
+import type { IncomingMessage, ChannelName } from '../core/types.js';
+
+export interface TelegramChannelConfig {
+  token: string;
+  mode?: 'polling' | 'webhook';
+  webhookUrl?: string;
+  pollingInterval?: number;
+}
+
+interface TGUpdate {
+  update_id: number;
+  message?: { message_id: number; from: { id: number; username?: string }; chat: { id: number }; date: number; text?: string };
+}
+
+export class TelegramChannel implements SvaraChannel {
+  readonly name: ChannelName = 'telegram';
+
+  private agent!: SvaraAgent;
+  private baseUrl: string;
+  private lastUpdateId = 0;
+  private pollingTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(private config: TelegramChannelConfig) {
+    if (!config.token) throw new Error('[@yesvara/svara] Telegram requires a bot token.');
+    this.baseUrl = `https://api.telegram.org/bot${config.token}`;
+  }
+
+  async mount(agent: SvaraAgent): Promise<void> {
+    this.agent = agent;
+    const me = await this.api<{ username: string }>('getMe');
+    console.log(`[@yesvara/svara] Telegram connected as @${me.username}`);
+
+    if (this.config.mode === 'webhook' && this.config.webhookUrl) {
+      await this.api('setWebhook', { url: `${this.config.webhookUrl}/telegram/webhook` });
+      console.log(`[@yesvara/svara] Telegram webhook registered.`);
+    } else {
+      this.startPolling();
+    }
+  }
+
+  async send(sessionId: string, text: string): Promise<void> {
+    const chatId = parseInt(sessionId, 10);
+    if (!isNaN(chatId)) await this.sendMessage(chatId, text);
+  }
+
+  async stop(): Promise<void> {
+    if (this.pollingTimer) clearInterval(this.pollingTimer);
+  }
+
+  private startPolling(): void {
+    const interval = this.config.pollingInterval ?? 1000;
+    console.log('[@yesvara/svara] Telegram polling started...');
+    this.pollingTimer = setInterval(async () => {
+      try {
+        const updates = await this.api<TGUpdate[]>('getUpdates', {
+          offset: this.lastUpdateId + 1,
+          allowed_updates: ['message'],
+        });
+        for (const update of updates) {
+          this.lastUpdateId = update.update_id;
+          if (update.message?.text) await this.handleUpdate(update);
+        }
+      } catch { /* polling errors are transient */ }
+    }, interval);
+  }
+
+  private async handleUpdate(update: TGUpdate): Promise<void> {
+    const msg = update.message!;
+    const message: IncomingMessage = {
+      id: String(msg.message_id),
+      sessionId: String(msg.chat.id),
+      userId: String(msg.from.id),
+      channel: 'telegram',
+      text: msg.text ?? '',
+      timestamp: new Date(msg.date * 1000),
+      raw: msg,
+    };
+
+    await this.api('sendChatAction', { chat_id: msg.chat.id, action: 'typing' }).catch(() => {});
+
+    try {
+      const result = await this.agent.receive(message);
+      for (const chunk of this.split(result.response, 4096)) {
+        await this.sendMessage(msg.chat.id, chunk);
+      }
+    } catch (err) {
+      await this.sendMessage(msg.chat.id, 'Sorry, something went wrong. Please try again.');
+      console.error('[@yesvara/svara] Telegram error:', (err as Error).message);
+    }
+  }
+
+  private async sendMessage(chatId: number, text: string): Promise<void> {
+    await this.api('sendMessage', { chat_id: chatId, text, parse_mode: 'Markdown' });
+  }
+
+  private async api<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T> {
+    const res = await fetch(`${this.baseUrl}/${method}`, {
+      method: params ? 'POST' : 'GET',
+      headers: { 'Content-Type': 'application/json' },
+      body: params ? JSON.stringify(params) : undefined,
+    });
+    const data = await res.json() as { ok: boolean; result: T; description?: string };
+    if (!data.ok) throw new Error(`Telegram API: ${data.description}`);
+    return data.result;
+  }
+
+  private split(text: string, max: number): string[] {
+    if (text.length <= max) return [text];
+    const chunks: string[] = [];
+    let rest = text;
+    while (rest.length > 0) { chunks.push(rest.slice(0, max)); rest = rest.slice(max); }
+    return chunks;
+  }
+}

package/src/channels/web.ts

@@ -0,0 +1,118 @@
+/**
+ * @module channels/web
+ *
+ * HTTP channel — exposes the agent as a REST API with SSE streaming.
+ *
+ * Used automatically when you call:
+ * ```ts
+ * agent.connectChannel('web', { port: 3000 });
+ * ```
+ *
+ * Or mount it on SvaraApp/Express:
+ * ```ts
+ * app.route('/chat', agent.handler());
+ * ```
+ *
+ * API:
+ *   POST /chat       — { message, sessionId? } → { response, sessionId, usage }
+ *   GET  /health     — { status: 'ok' }
+ */
+
+import express, { type Express } from 'express';
+import type { SvaraAgent, SvaraChannel } from '../core/agent.js';
+import type { IncomingMessage, ChannelName } from '../core/types.js';
+
+export interface WebChannelConfig {
+  port?: number;           // default 3000
+  cors?: boolean | string;
+  apiKey?: string;
+  path?: string;           // base path prefix, default ''
+}
+
+export class WebChannel implements SvaraChannel {
+  readonly name: ChannelName = 'web';
+
+  private app: Express;
+  private server: ReturnType<Express['listen']> | null = null;
+  private agent!: SvaraAgent;
+
+  constructor(private config: WebChannelConfig = {}) {
+    this.app = this.buildApp();
+  }
+
+  async mount(agent: SvaraAgent): Promise<void> {
+    this.agent = agent;
+    this.attachRoutes();
+
+    const port = this.config.port ?? 3000;
+    return new Promise((resolve, reject) => {
+      this.server = this.app.listen(port, () => {
+        console.log(`[@yesvara/svara] Web channel running at http://localhost:${port}`);
+        resolve();
+      });
+      this.server.on('error', reject);
+    });
+  }
+
+  async send(_sessionId: string, _text: string): Promise<void> {
+    // Push-based sending is handled via SSE in the /chat/stream route
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      this.server?.close(() => resolve()) ?? resolve();
+    });
+  }
+
+  // ─── Private ───────────────────────────────────────────────────────────────
+
+  private buildApp(): Express {
+    const app = express();
+    app.use(express.json({ limit: '10mb' }));
+
+    if (this.config.cors) {
+      const origin = this.config.cors === true ? '*' : this.config.cors;
+      app.use((_req, res, next) => {
+        res.setHeader('Access-Control-Allow-Origin', origin as string);
+        res.setHeader('Access-Control-Allow-Methods', 'GET,POST,OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        next();
+      });
+      app.options('*', (_req, res) => res.sendStatus(204));
+    }
+
+    if (this.config.apiKey) {
+      app.use((req, res, next) => {
+        const token = req.headers.authorization?.replace('Bearer ', '');
+        if (token !== this.config.apiKey) {
+          res.status(401).json({ error: 'Unauthorized' });
+          return;
+        }
+        next();
+      });
+    }
+
+    return app;
+  }
+
+  private attachRoutes(): void {
+    const base = this.config.path ?? '';
+
+    this.app.get(`${base}/health`, (_req, res) => {
+      res.json({ status: 'ok', agent: this.agent.name, timestamp: new Date().toISOString() });
+    });
+
+    this.app.post(`${base}/chat`, this.agent.handler());
+  }
+
+  private buildMessage(body: { message: string; sessionId?: string; userId?: string }): IncomingMessage {
+    return {
+      id: crypto.randomUUID(),
+      sessionId: body.sessionId ?? crypto.randomUUID(),
+      userId: body.userId ?? 'web-user',
+      channel: 'web',
+      text: body.message,
+      timestamp: new Date(),
+    };
+  }
+}

package/src/channels/whatsapp.ts

@@ -0,0 +1,161 @@
+/**
+ * @module channels/whatsapp
+ *
+ * WhatsApp Business API channel (Meta Cloud API).
+ * Used when you call: `agent.connectChannel('whatsapp', { ... })`
+ *
+ * Requires the 'web' channel to be mounted first (it shares the Express server).
+ * Webhook endpoint: POST /whatsapp/webhook
+ */
+
+import type { SvaraAgent, SvaraChannel } from '../core/agent.js';
+import type { IncomingMessage, ChannelName } from '../core/types.js';
+import type express from 'express';
+
+export interface WhatsAppChannelConfig {
+  /** WhatsApp Cloud API access token */
+  token: string;
+  /** Your WhatsApp Phone Number ID */
+  phoneId: string;
+  /** Token to verify the webhook with Meta */
+  verifyToken: string;
+  /** API version, default 'v19.0' */
+  apiVersion?: string;
+}
+
+interface WABody {
+  object: string;
+  entry: Array<{
+    changes: Array<{
+      value: {
+        messages?: Array<{
+          id: string; from: string; timestamp: string;
+          type: string; text?: { body: string };
+        }>;
+      };
+    }>;
+  }>;
+}
+
+export class WhatsAppChannel implements SvaraChannel {
+  readonly name: ChannelName = 'whatsapp';
+
+  private agent!: SvaraAgent;
+  private readonly apiUrl: string;
+
+  constructor(private config: WhatsAppChannelConfig) {
+    if (!config.token || !config.phoneId || !config.verifyToken) {
+      throw new Error(
+        '[@yesvara/svara] WhatsApp requires: token, phoneId, and verifyToken.'
+      );
+    }
+    const version = config.apiVersion ?? 'v19.0';
+    this.apiUrl = `https://graph.facebook.com/${version}/${config.phoneId}`;
+  }
+
+  async mount(agent: SvaraAgent): Promise<void> {
+    this.agent = agent;
+
+    // Get the web channel's Express app to attach webhook routes
+    const webChannel = (agent as unknown as {
+      channels: Map<string, { app?: express.Application }>;
+    }).channels?.get('web');
+
+    const app = (webChannel as { app?: { post: (...a: unknown[]) => void; get: (...a: unknown[]) => void } })?.app;
+
+    if (!app) {
+      console.warn(
+        '[@yesvara/svara] WhatsApp: no "web" channel found. ' +
+        'Add connectChannel("web", ...) before connectChannel("whatsapp", ...) ' +
+        'so the webhook can be mounted.'
+      );
+      return;
+    }
+
+    // Webhook verification
+    app.get('/whatsapp/webhook', (req: { query: Record<string, string> }, res: { status: (n: number) => { send: (s: unknown) => void } }) => {
+      const { 'hub.mode': mode, 'hub.verify_token': token, 'hub.challenge': challenge } = req.query;
+      if (mode === 'subscribe' && token === this.config.verifyToken) {
+        console.log('[@yesvara/svara] WhatsApp webhook verified.');
+        res.status(200).send(challenge);
+      } else {
+        res.status(403).send('Forbidden');
+      }
+    });
+
+    // Incoming messages
+    app.post('/whatsapp/webhook', async (req: { body: WABody }, res: { sendStatus: (n: number) => void }) => {
+      res.sendStatus(200); // ack immediately
+      if (req.body.object !== 'whatsapp_business_account') return;
+
+      for (const entry of req.body.entry) {
+        for (const change of entry.changes) {
+          for (const waMsg of change.value.messages ?? []) {
+            if (waMsg.type !== 'text' || !waMsg.text?.body) continue;
+            await this.handle(waMsg).catch((err: Error) =>
+              console.error('[@yesvara/svara] WhatsApp error:', err.message)
+            );
+          }
+        }
+      }
+    });
+
+    console.log('[@yesvara/svara] WhatsApp webhook mounted at /whatsapp/webhook');
+  }
+
+  async send(to: string, text: string): Promise<void> {
+    await this.sendMessage(to, text);
+  }
+
+  async stop(): Promise<void> { /* HTTP-based, no persistent connection */ }
+
+  private async handle(waMsg: { id: string; from: string; timestamp: string; text?: { body: string } }): Promise<void> {
+    const message: IncomingMessage = {
+      id: waMsg.id,
+      sessionId: waMsg.from,
+      userId: waMsg.from,
+      channel: 'whatsapp',
+      text: waMsg.text?.body ?? '',
+      timestamp: new Date(parseInt(waMsg.timestamp) * 1000),
+      raw: waMsg,
+    };
+
+    try {
+      const result = await this.agent.receive(message);
+      for (const chunk of this.split(result.response, 4000)) {
+        await this.sendMessage(waMsg.from, chunk);
+      }
+    } catch (err) {
+      await this.sendMessage(waMsg.from, 'Sorry, something went wrong. Please try again.');
+      throw err;
+    }
+  }
+
+  private async sendMessage(to: string, text: string): Promise<void> {
+    const res = await fetch(`${this.apiUrl}/messages`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.config.token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        messaging_product: 'whatsapp',
+        to,
+        type: 'text',
+        text: { body: text },
+      }),
+    });
+    if (!res.ok) {
+      const err = await res.json() as { error?: { message: string } };
+      throw new Error(`WhatsApp API: ${err.error?.message}`);
+    }
+  }
+
+  private split(text: string, max: number): string[] {
+    if (text.length <= max) return [text];
+    const chunks: string[] = [];
+    let rest = text;
+    while (rest.length > 0) { chunks.push(rest.slice(0, max)); rest = rest.slice(max); }
+    return chunks;
+  }
+}

package/src/cli/commands/dev.ts

@@ -0,0 +1,87 @@
+/**
+ * @module cli/commands/dev
+ * SvaraJS — `svara dev` command
+ *
+ * Starts a development server with hot-reload and a pretty REPL.
+ * Wraps tsx watch for TypeScript + restarts on file changes.
+ */
+
+import { spawn } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+
+interface DevOptions {
+  entry?: string;
+  port?: number;
+}
+
+export async function devServer(options: DevOptions = {}): Promise<void> {
+  const entry = options.entry ?? findEntry();
+
+  if (!entry) {
+    console.error(`
+❌ Could not find entry file.
+
+Create src/index.ts or specify one:
+  svara dev --entry src/app.ts
+`);
+    process.exit(1);
+  }
+
+  console.log(`
+🚀 SvaraJS Dev Server
+─────────────────────
+  Entry: ${entry}
+  Watch: enabled
+
+`);
+
+  const runner = spawn(
+    'npx',
+    ['tsx', 'watch', '--clear-screen=false', entry],
+    {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        NODE_ENV: 'development',
+        ...(options.port ? { PORT: String(options.port) } : {}),
+      },
+    }
+  );
+
+  runner.on('error', (err) => {
+    console.error('\n❌ Dev server error:', err.message);
+    console.error('Make sure "tsx" is installed: npm install -D tsx');
+  });
+
+  runner.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      process.exit(code);
+    }
+  });
+
+  // Forward signals
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.on(signal, () => {
+      runner.kill(signal);
+      process.exit(0);
+    });
+  }
+}
+
+function findEntry(): string | null {
+  const candidates = [
+    'src/index.ts',
+    'src/app.ts',
+    'src/main.ts',
+    'index.ts',
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.resolve(process.cwd(), candidate))) {
+      return candidate;
+    }
+  }
+
+  return null;
+}

package/src/cli/commands/new.ts

@@ -0,0 +1,213 @@
+/**
+ * @module cli/commands/new
+ * SvaraJS — `svara new <project-name>` command
+ *
+ * Scaffolds a new SvaraJS project with opinionated defaults.
+ * Creates a ready-to-run project in seconds.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { execSync } from 'child_process';
+
+interface ScaffoldOptions {
+  name: string;
+  provider?: 'openai' | 'anthropic' | 'ollama';
+  channels?: string[];
+  installDeps?: boolean;
+}
+
+export async function newProject(options: ScaffoldOptions): Promise<void> {
+  const { name, provider = 'openai', channels = ['web'] } = options;
+  const targetDir = path.resolve(process.cwd(), name);
+
+  console.log(`\n✨ Creating SvaraJS project: ${name}\n`);
+
+  // Check if directory already exists
+  try {
+    await fs.access(targetDir);
+    console.error(`❌ Directory "${name}" already exists.`);
+    process.exit(1);
+  } catch {
+    // Good — it doesn't exist
+  }
+
+  await fs.mkdir(targetDir, { recursive: true });
+  await fs.mkdir(path.join(targetDir, 'src'), { recursive: true });
+  await fs.mkdir(path.join(targetDir, 'docs'), { recursive: true });
+  await fs.mkdir(path.join(targetDir, 'data'), { recursive: true });
+
+  const files: Record<string, string> = {
+    'package.json': generatePackageJson(name),
+    'tsconfig.json': generateTsConfig(),
+    '.env.example': generateEnvExample(provider, channels),
+    '.gitignore': generateGitignore(),
+    'src/index.ts': generateIndexFile(name, provider, channels),
+    'docs/README.md': `# ${name} Knowledge Base\n\nAdd your documents here for RAG.\n`,
+  };
+
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = path.join(targetDir, filePath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    await fs.writeFile(fullPath, content, 'utf-8');
+    console.log(`  ✓ ${filePath}`);
+  }
+
+  if (options.installDeps !== false) {
+    console.log('\n📦 Installing dependencies...\n');
+    try {
+      execSync('npm install', { cwd: targetDir, stdio: 'inherit' });
+    } catch {
+      console.warn('\n⚠️  Dependency install failed. Run "npm install" manually.\n');
+    }
+  }
+
+  console.log(`
+✅ Project ready!
+
+  cd ${name}
+  cp .env.example .env     # Add your API keys
+  npm run dev              # Start the agent
+
+📚 Docs: https://svarajs.dev
+`);
+}
+
+// ─── File Templates ────────────────────────────────────────────────────────────
+
+function generatePackageJson(name: string): string {
+  return JSON.stringify({
+    name,
+    version: '0.1.0',
+    private: true,
+    scripts: {
+      dev: 'tsx watch src/index.ts',
+      build: 'tsc',
+      start: 'node dist/index.js',
+    },
+    dependencies: {
+      svarajs: 'latest',
+      dotenv: '^16.4.5',
+    },
+    devDependencies: {
+      '@types/node': '^20.14.2',
+      tsx: '^4.15.7',
+      typescript: '^5.4.5',
+    },
+  }, null, 2);
+}
+
+function generateTsConfig(): string {
+  return JSON.stringify({
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'CommonJS',
+      moduleResolution: 'bundler',
+      outDir: 'dist',
+      rootDir: 'src',
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+    },
+    include: ['src/**/*'],
+    exclude: ['node_modules', 'dist'],
+  }, null, 2);
+}
+
+function generateEnvExample(
+  provider: string,
+  channels: string[]
+): string {
+  const lines = ['# SvaraJS Environment Variables', ''];
+
+  if (provider === 'openai') {
+    lines.push('# OpenAI', 'OPENAI_API_KEY=sk-...', '');
+  } else if (provider === 'anthropic') {
+    lines.push('# Anthropic', 'ANTHROPIC_API_KEY=sk-ant-...', '');
+  }
+
+  if (channels.includes('telegram')) {
+    lines.push('# Telegram', 'TELEGRAM_BOT_TOKEN=...', '');
+  }
+  if (channels.includes('whatsapp')) {
+    lines.push('# WhatsApp', 'WA_ACCESS_TOKEN=...', 'WA_PHONE_ID=...', 'WA_VERIFY_TOKEN=...', '');
+  }
+
+  return lines.join('\n');
+}
+
+function generateIndexFile(
+  name: string,
+  provider: string,
+  channels: string[]
+): string {
+  const modelMap: Record<string, string> = {
+    openai: 'gpt-4o',
+    anthropic: 'claude-opus-4-6',
+    ollama: 'llama3',
+  };
+
+  const channelSetup = channels
+    .map((ch) => {
+      if (ch === 'web') return `agent.use('web', { port: 3000, cors: true });`;
+      if (ch === 'telegram') return `agent.use('telegram', { token: process.env.TELEGRAM_BOT_TOKEN! });`;
+      if (ch === 'whatsapp') return [
+        `agent.use('whatsapp', {`,
+        `  token: process.env.WA_ACCESS_TOKEN!,`,
+        `  phoneId: process.env.WA_PHONE_ID!,`,
+        `  verifyToken: process.env.WA_VERIFY_TOKEN!,`,
+        `});`,
+      ].join('\n');
+      return '';
+    })
+    .filter(Boolean)
+    .join('\n');
+
+  return `import 'dotenv/config';
+import { svara } from 'svarajs';
+
+/**
+ * ${name} — powered by SvaraJS
+ */
+const agent = svara({
+  llm: {
+    provider: '${provider}',
+    model: '${modelMap[provider] ?? 'gpt-4o'}',
+  },
+  systemPrompt: \`You are a helpful AI assistant called ${name}.
+Be concise, friendly, and always try your best to help.\`,
+  memory: {
+    type: 'conversation',
+    maxMessages: 20,
+  },
+  verbose: true,
+});
+
+// ── Tools ──────────────────────────────────────────────────────────────────
+agent.tool('get_time', {
+  description: 'Get the current date and time',
+  parameters: {},
+  execute: async () => ({
+    datetime: new Date().toISOString(),
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+  }),
+});
+
+// ── Channels ────────────────────────────────────────────────────────────────
+${channelSetup}
+
+// ── Start ────────────────────────────────────────────────────────────────────
+agent.start().then(() => {
+  console.log('🚀 ${name} is running!');
+});
+`;
+}
+
+function generateGitignore(): string {
+  return `node_modules/
+dist/
+.env
+data/*.db
+*.log
+`;
+}