@ebowwa/channel-types 0.1.0

package/src/config.ts

@@ -0,0 +1,429 @@
+/**
+ * @ebowwa/channel-types/config
+ *
+ * Composable channel configuration loading.
+ * Supports Doppler (env vars), JSON files, and programmatic config.
+ *
+ * Usage:
+ *   const config = loadChannelConfig(); // From env
+ *   const config = parseChannelConfig(jsonString); // From JSON
+ *   const config = createChannelConfig({ ... }); // Programmatic
+ */
+
+import type { ChannelPlatform, ChannelId } from "./index.js";
+import { createChannelId } from "./index.js";
+
+// ============================================================
+// CHANNEL CONFIG SCHEMA
+// ============================================================
+
+/** Base configuration for all channels */
+export interface BaseChannelConfig {
+  /** Channel platform */
+  platform: ChannelPlatform;
+
+  /** Unique account/bot identifier */
+  accountId: string;
+
+  /** Enable/disable channel */
+  enabled: boolean;
+
+  /** Human-readable label */
+  label?: string;
+
+  /** Optional instance ID for multiple instances */
+  instanceId?: string;
+}
+
+/** Telegram channel configuration */
+export interface TelegramChannelConfig extends BaseChannelConfig {
+  platform: "telegram";
+  /** Bot token from @BotFather */
+  botToken: string;
+  /** Polling interval in ms (default: 1000) */
+  pollingInterval?: number;
+  /** Allowed user IDs (empty = all) */
+  allowedUsers?: number[];
+  /** Allowed chat IDs (empty = all) */
+  allowedChats?: number[];
+}
+
+/** Discord channel configuration */
+export interface DiscordChannelConfig extends BaseChannelConfig {
+  platform: "discord";
+  /** Bot token */
+  botToken: string;
+  /** Application ID */
+  applicationId?: string;
+  /** Guild ID to restrict to */
+  guildId?: string;
+  /** Channel IDs to listen to */
+  channelIds?: string[];
+  /** Enable slash commands */
+  enableSlashCommands?: boolean;
+}
+
+/** WhatsApp channel configuration */
+export interface WhatsAppChannelConfig extends BaseChannelConfig {
+  platform: "whatsapp";
+  /** Webhook URL for business API */
+  webhookUrl?: string;
+  /** Phone number ID */
+  phoneNumberId?: string;
+  /** Access token */
+  accessToken?: string;
+  /** Or use QR code pairing (non-business) */
+  sessionPath?: string;
+}
+
+/** iMessage channel configuration */
+export interface IMessageChannelConfig extends BaseChannelConfig {
+  platform: "imessage";
+  /** BlueBubbles server URL */
+  serverUrl?: string;
+  /** BlueBubbles password */
+  password?: string;
+  /** Or use local iMessage */
+  local?: boolean;
+}
+
+/** Slack channel configuration */
+export interface SlackChannelConfig extends BaseChannelConfig {
+  platform: "slack";
+  /** Bot token (xoxb-...) */
+  botToken: string;
+  /** App token (xapp-...) for Socket Mode */
+  appToken?: string;
+  /** Signing secret */
+  signingSecret?: string;
+  /** Channel IDs to listen to */
+  channelIds?: string[];
+}
+
+/** Signal channel configuration */
+export interface SignalChannelConfig extends BaseChannelConfig {
+  platform: "signal";
+  /** Phone number */
+  phoneNumber: string;
+  /** signal-cli path */
+  cliPath?: string;
+  /** Signal REST API URL */
+  apiUrl?: string;
+}
+
+/** CLI channel configuration (terminal-based) */
+export interface CLIChannelConfig extends BaseChannelConfig {
+  platform: "cli";
+  /** Enable interactive mode */
+  interactive?: boolean;
+  /** Prompt string */
+  prompt?: string;
+  /** History file path */
+  historyPath?: string;
+}
+
+/** Web channel configuration */
+export interface WebChannelConfig extends BaseChannelConfig {
+  platform: "web";
+  /** Port to listen on */
+  port?: number;
+  /** Host to bind to */
+  host?: string;
+  /** API key for authentication */
+  apiKey?: string;
+  /** Enable CORS */
+  cors?: boolean;
+}
+
+/** Union of all channel configs */
+export type ChannelConfig =
+  | TelegramChannelConfig
+  | DiscordChannelConfig
+  | WhatsAppChannelConfig
+  | IMessageChannelConfig
+  | SlackChannelConfig
+  | SignalChannelConfig
+  | CLIChannelConfig
+  | WebChannelConfig;
+
+/** Map of channel name -> config */
+export type ChannelConfigMap = Record<string, ChannelConfig>;
+
+// ============================================================
+// CONFIG LOADING FROM DOPPLER (ENV VARS)
+// ============================================================
+
+/**
+ * Environment variable naming convention:
+ *
+ * {PLATFORM}_ENABLED       - Enable channel (true/false)
+ * {PLATFORM}_BOT_TOKEN     - Bot token
+ * {PLATFORM}_ACCOUNT_ID    - Account identifier
+ * {PLATFORM}_{OPTION}      - Platform-specific options
+ *
+ * Examples:
+ *   TELEGRAM_ENABLED=true
+ *   TELEGRAM_BOT_TOKEN=123456:ABC
+ *   DISCORD_ENABLED=true
+ *   DISCORD_BOT_TOKEN=xyz.abc
+ *   DISCORD_GUILD_ID=123456789
+ */
+
+/** Load all channel configs from environment variables (Doppler) */
+export function loadChannelConfigsFromEnv(): ChannelConfigMap {
+  const configs: ChannelConfigMap = {};
+
+  // Telegram
+  if (isChannelEnabled("TELEGRAM")) {
+    configs.telegram = loadTelegramConfig();
+  }
+
+  // Discord
+  if (isChannelEnabled("DISCORD")) {
+    configs.discord = loadDiscordConfig();
+  }
+
+  // WhatsApp
+  if (isChannelEnabled("WHATSAPP")) {
+    configs.whatsapp = loadWhatsAppConfig();
+  }
+
+  // iMessage
+  if (isChannelEnabled("IMESSAGE")) {
+    configs.imessage = loadIMessageConfig();
+  }
+
+  // Slack
+  if (isChannelEnabled("SLACK")) {
+    configs.slack = loadSlackConfig();
+  }
+
+  // Signal
+  if (isChannelEnabled("SIGNAL")) {
+    configs.signal = loadSignalConfig();
+  }
+
+  // CLI (enabled by default)
+  if (isChannelEnabled("CLI", true)) {
+    configs.cli = loadCLIConfig();
+  }
+
+  // Web
+  if (isChannelEnabled("WEB")) {
+    configs.web = loadWebConfig();
+  }
+
+  return configs;
+}
+
+/** Check if a channel is enabled via env var */
+function isChannelEnabled(prefix: string, defaultEnabled = false): boolean {
+  const value = process.env[`${prefix}_ENABLED`];
+  if (value === undefined) return defaultEnabled;
+  return value === "true" || value === "1";
+}
+
+/** Get env var with fallback */
+function getEnv(key: string, fallback?: string): string | undefined {
+  return process.env[key] ?? fallback;
+}
+
+/** Get required env var (throws if missing) */
+function requireEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) {
+    throw new Error(`Required environment variable ${key} is not set`);
+  }
+  return value;
+}
+
+/** Parse comma-separated list from env */
+function parseList(value?: string): string[] | undefined {
+  if (!value) return undefined;
+  return value.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+/** Parse number list from env */
+function parseNumberList(value?: string): number[] | undefined {
+  const list = parseList(value);
+  return list?.map((s) => parseInt(s, 10)).filter((n) => !isNaN(n));
+}
+
+// Individual channel loaders
+
+function loadTelegramConfig(): TelegramChannelConfig {
+  return {
+    platform: "telegram",
+    accountId: getEnv("TELEGRAM_ACCOUNT_ID", "default")!,
+    enabled: true,
+    botToken: requireEnv("TELEGRAM_BOT_TOKEN"),
+    pollingInterval: parseInt(getEnv("TELEGRAM_POLLING_INTERVAL", "1000")!, 10),
+    allowedUsers: parseNumberList(getEnv("TELEGRAM_ALLOWED_USERS")),
+    allowedChats: parseNumberList(getEnv("TELEGRAM_ALLOWED_CHATS")),
+  };
+}
+
+function loadDiscordConfig(): DiscordChannelConfig {
+  return {
+    platform: "discord",
+    accountId: getEnv("DISCORD_ACCOUNT_ID", "default")!,
+    enabled: true,
+    botToken: requireEnv("DISCORD_BOT_TOKEN"),
+    applicationId: getEnv("DISCORD_APPLICATION_ID"),
+    guildId: getEnv("DISCORD_GUILD_ID"),
+    channelIds: parseList(getEnv("DISCORD_CHANNEL_IDS")),
+    enableSlashCommands: getEnv("DISCORD_ENABLE_SLASH_COMMANDS", "true") === "true",
+  };
+}
+
+function loadWhatsAppConfig(): WhatsAppChannelConfig {
+  return {
+    platform: "whatsapp",
+    accountId: getEnv("WHATSAPP_ACCOUNT_ID", "default")!,
+    enabled: true,
+    webhookUrl: getEnv("WHATSAPP_WEBHOOK_URL"),
+    phoneNumberId: getEnv("WHATSAPP_PHONE_NUMBER_ID"),
+    accessToken: getEnv("WHATSAPP_ACCESS_TOKEN"),
+    sessionPath: getEnv("WHATSAPP_SESSION_PATH"),
+  };
+}
+
+function loadIMessageConfig(): IMessageChannelConfig {
+  return {
+    platform: "imessage",
+    accountId: getEnv("IMESSAGE_ACCOUNT_ID", "default")!,
+    enabled: true,
+    serverUrl: getEnv("IMESSAGE_SERVER_URL"),
+    password: getEnv("IMESSAGE_PASSWORD"),
+    local: getEnv("IMESSAGE_LOCAL", "false") === "true",
+  };
+}
+
+function loadSlackConfig(): SlackChannelConfig {
+  return {
+    platform: "slack",
+    accountId: getEnv("SLACK_ACCOUNT_ID", "default")!,
+    enabled: true,
+    botToken: requireEnv("SLACK_BOT_TOKEN"),
+    appToken: getEnv("SLACK_APP_TOKEN"),
+    signingSecret: getEnv("SLACK_SIGNING_SECRET"),
+    channelIds: parseList(getEnv("SLACK_CHANNEL_IDS")),
+  };
+}
+
+function loadSignalConfig(): SignalChannelConfig {
+  return {
+    platform: "signal",
+    accountId: getEnv("SIGNAL_ACCOUNT_ID", "default")!,
+    enabled: true,
+    phoneNumber: requireEnv("SIGNAL_PHONE_NUMBER"),
+    cliPath: getEnv("SIGNAL_CLI_PATH"),
+    apiUrl: getEnv("SIGNAL_API_URL"),
+  };
+}
+
+function loadCLIConfig(): CLIChannelConfig {
+  return {
+    platform: "cli",
+    accountId: getEnv("CLI_ACCOUNT_ID", "default")!,
+    enabled: true,
+    interactive: getEnv("CLI_INTERACTIVE", "true") === "true",
+    prompt: getEnv("CLI_PROMPT", "> "),
+    historyPath: getEnv("CLI_HISTORY_PATH"),
+  };
+}
+
+function loadWebConfig(): WebChannelConfig {
+  return {
+    platform: "web",
+    accountId: getEnv("WEB_ACCOUNT_ID", "default")!,
+    enabled: true,
+    port: parseInt(getEnv("WEB_PORT", "3000")!, 10),
+    host: getEnv("WEB_HOST", "0.0.0.0"),
+    apiKey: getEnv("WEB_API_KEY"),
+    cors: getEnv("WEB_CORS", "true") === "true",
+  };
+}
+
+// ============================================================
+// CONFIG UTILITIES
+// ============================================================
+
+/** Get ChannelId from config */
+export function getChannelId(config: ChannelConfig): ChannelId {
+  return createChannelId(config.platform, config.accountId, config.instanceId);
+}
+
+/** Validate channel config */
+export function validateChannelConfig(config: ChannelConfig): string[] {
+  const errors: string[] = [];
+
+  switch (config.platform) {
+    case "telegram":
+      if (!config.botToken) errors.push("Telegram: botToken is required");
+      break;
+    case "discord":
+      if (!config.botToken) errors.push("Discord: botToken is required");
+      break;
+    case "whatsapp":
+      if (!config.webhookUrl && !config.sessionPath) {
+        errors.push("WhatsApp: webhookUrl or sessionPath is required");
+      }
+      break;
+    case "signal":
+      if (!config.phoneNumber) errors.push("Signal: phoneNumber is required");
+      break;
+    case "slack":
+      if (!config.botToken) errors.push("Slack: botToken is required");
+      break;
+  }
+
+  return errors;
+}
+
+/** Filter configs by enabled status */
+export function getEnabledChannels(configs: ChannelConfigMap): ChannelConfig[] {
+  return Object.values(configs).filter((c) => c.enabled);
+}
+
+/** Filter configs by platform */
+export function getChannelsByPlatform(
+  configs: ChannelConfigMap,
+  platform: ChannelPlatform
+): ChannelConfig[] {
+  return Object.values(configs).filter((c) => c.platform === platform);
+}
+
+/** Create config programmatically */
+export function createChannelConfig<T extends ChannelConfig>(config: T): T {
+  const errors = validateChannelConfig(config);
+  if (errors.length > 0) {
+    throw new Error(`Invalid channel config: ${errors.join(", ")}`);
+  }
+  return config;
+}
+
+/** Parse config from JSON string */
+export function parseChannelConfig(json: string): ChannelConfig {
+  const config = JSON.parse(json) as ChannelConfig;
+  const errors = validateChannelConfig(config);
+  if (errors.length > 0) {
+    throw new Error(`Invalid channel config: ${errors.join(", ")}`);
+  }
+  return config;
+}
+
+/** Parse multiple configs from JSON string */
+export function parseChannelConfigs(json: string): ChannelConfigMap {
+  return JSON.parse(json) as ChannelConfigMap;
+}
+
+/** Serialize config to JSON */
+export function serializeChannelConfig(config: ChannelConfig): string {
+  return JSON.stringify(config, null, 2);
+}
+
+/** Serialize multiple configs to JSON */
+export function serializeChannelConfigs(configs: ChannelConfigMap): string {
+  return JSON.stringify(configs, null, 2);
+}

package/src/example.ts

@@ -0,0 +1,287 @@
+/**
+ * Example: Composable Channel-LLM Architecture
+ *
+ * This demonstrates how to:
+ * 1. Create a channel connector (Discord)
+ * 2. Create an LLM handler (GLM)
+ * 3. Connect them via a bridge
+ */
+
+import type {
+  ChannelBridge,
+  ChannelCapabilities,
+  ChannelConnector,
+  ChannelId,
+  ChannelMessage,
+  ChannelResponse,
+  LLMHandler,
+  MessageHandler,
+  StreamChunk,
+} from "./index.js";
+import {
+  createChannelId,
+  createMessageRef,
+  DEFAULT_CAPABILITIES,
+  RICH_CAPABILITIES,
+} from "./index.js";
+
+// ============================================================
+// EXAMPLE: Discord Channel Connector
+// ============================================================
+
+class DiscordChannel implements ChannelConnector {
+  readonly id: ChannelId;
+  readonly label = "Discord";
+  readonly capabilities: ChannelCapabilities = RICH_CAPABILITIES;
+
+  private messageHandler?: MessageHandler;
+  private connected = false;
+
+  constructor(accountId: string) {
+    this.id = createChannelId("discord", accountId);
+  }
+
+  async start(): Promise<void> {
+    // In real impl: connect to Discord gateway
+    this.connected = true;
+    console.log(`[${this.label}] Started`);
+  }
+
+  async stop(): Promise<void> {
+    this.connected = false;
+    console.log(`[${this.label}] Stopped`);
+  }
+
+  onMessage(handler: MessageHandler): void {
+    this.messageHandler = handler;
+  }
+
+  async send(response: ChannelResponse): Promise<void> {
+    // In real impl: send to Discord API
+    console.log(`[${this.label}] Sending: ${response.content.text}`);
+  }
+
+  async stream(
+    response: ChannelResponse,
+    chunks: AsyncIterable<StreamChunk>
+  ): Promise<void> {
+    // In real impl: edit message with streaming content
+    let fullText = "";
+    for await (const chunk of chunks) {
+      fullText += chunk.text;
+      console.log(`[${this.label}] Stream: ${fullText}`);
+    }
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  // Simulate receiving a message (for testing)
+  async simulateMessage(text: string, senderId: string): Promise<void> {
+    if (!this.messageHandler) return;
+
+    const message: ChannelMessage = {
+      messageId: `msg-${Date.now()}`,
+      channelId: this.id,
+      timestamp: new Date(),
+      sender: { id: senderId, username: `user_${senderId}` },
+      text,
+      context: { isDM: true },
+    };
+
+    const response = await this.messageHandler(message);
+    if (response) {
+      await this.send(response);
+    }
+  }
+}
+
+// ============================================================
+// EXAMPLE: GLM LLM Handler
+// ============================================================
+
+class GLMHandler implements LLMHandler {
+  readonly id = "glm-4.7";
+  readonly model = "glm-4-flash";
+
+  private ready = true;
+
+  async process(message: ChannelMessage): Promise<ChannelResponse> {
+    // In real impl: call GLM API
+    const startTime = Date.now();
+
+    // Simulate LLM response
+    const responseText = this.generateResponse(message.text);
+
+    return {
+      content: {
+        text: responseText,
+        replyToOriginal: true,
+      },
+      replyTo: createMessageRef(message.messageId, message.channelId),
+      isComplete: true,
+      metadata: {
+        model: this.model,
+        latency: Date.now() - startTime,
+      },
+    };
+  }
+
+  async* stream(message: ChannelMessage): AsyncIterable<StreamChunk> {
+    // In real impl: stream from GLM API
+    const response = await this.process(message);
+    const words = response.content.text.split(" ");
+
+    for (let i = 0; i < words.length; i++) {
+      yield {
+        text: words[i] + " ",
+        done: i === words.length - 1,
+        seq: i,
+      };
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+
+  isReady(): boolean {
+    return this.ready;
+  }
+
+  private generateResponse(input: string): string {
+    // Simple echo + prefix for demo
+    if (input.toLowerCase().includes("hello")) {
+      return "Hello! How can I help you today?";
+    }
+    if (input.toLowerCase().includes("status")) {
+      return "All systems operational. GLM 4.7 is ready to assist.";
+    }
+    return `I received your message: "${input}"`;
+  }
+}
+
+// ============================================================
+// EXAMPLE: Simple Bridge Implementation
+// ============================================================
+
+class SimpleBridge implements ChannelBridge {
+  private channels: Map<string, ChannelConnector> = new Map();
+  private handlers: Map<string, LLMHandler> = new Map();
+  private defaultHandlers: Map<string, string> = new Map();
+
+  registerChannel(channel: ChannelConnector): void {
+    const key = this.channelKey(channel.id);
+    this.channels.set(key, channel);
+
+    // Set up message routing
+    channel.onMessage(async (message) => {
+      const handlerId = this.defaultHandlers.get(key);
+      if (!handlerId) {
+        console.warn(`No handler for channel ${key}`);
+        return;
+      }
+
+      const handler = this.handlers.get(handlerId);
+      if (!handler) {
+        console.warn(`Handler ${handlerId} not found`);
+        return;
+      }
+
+      return handler.process(message);
+    });
+
+    console.log(`[Bridge] Registered channel: ${channel.label}`);
+  }
+
+  registerHandler(handler: LLMHandler): void {
+    this.handlers.set(handler.id, handler);
+    console.log(`[Bridge] Registered handler: ${handler.id}`);
+  }
+
+  setDefaultHandler(channelId: ChannelId, handlerId: string): void {
+    this.defaultHandlers.set(this.channelKey(channelId), handlerId);
+    console.log(`[Bridge] Set default handler: ${this.channelKey(channelId)} → ${handlerId}`);
+  }
+
+  async start(): Promise<void> {
+    for (const channel of this.channels.values()) {
+      await channel.start();
+    }
+  }
+
+  async stop(): Promise<void> {
+    for (const channel of this.channels.values()) {
+      await channel.stop();
+    }
+  }
+
+  getChannels(): ChannelConnector[] {
+    return Array.from(this.channels.values());
+  }
+
+  getHandlers(): LLMHandler[] {
+    return Array.from(this.handlers.values());
+  }
+
+  private channelKey(id: ChannelId): string {
+    return `${id.platform}:${id.accountId}`;
+  }
+}
+
+// ============================================================
+// USAGE EXAMPLE
+// ============================================================
+
+async function main() {
+  console.log("=== Composable Channel-LLM Example ===\n");
+
+  // 1. Create bridge
+  const bridge = new SimpleBridge();
+
+  // 2. Create and register LLM handler
+  const glmHandler = new GLMHandler();
+  bridge.registerHandler(glmHandler);
+
+  // 3. Create and register channel
+  const discordChannel = new DiscordChannel("my-bot-123");
+  bridge.registerChannel(discordChannel);
+
+  // 4. Connect channel to handler
+  bridge.setDefaultHandler(discordChannel.id, glmHandler.id);
+
+  // 5. Start the bridge
+  await bridge.start();
+
+  // 6. Simulate messages
+  console.log("\n--- Simulating messages ---\n");
+  await discordChannel.simulateMessage("Hello!", "user-1");
+  await discordChannel.simulateMessage("What's the status?", "user-2");
+  await discordChannel.simulateMessage("Can you help me with a task?", "user-3");
+
+  // 7. Stop
+  console.log("\n--- Stopping ---\n");
+  await bridge.stop();
+}
+
+// Run example
+main().catch(console.error);
+
+/**
+ * Output:
+ *
+ * === Composable Channel-LLM Example ===
+ *
+ * [Bridge] Registered handler: glm-4.7
+ * [Bridge] Registered channel: Discord
+ * [Bridge] Set default handler: discord:my-bot-123 → glm-4.7
+ * [Discord] Started
+ *
+ * --- Simulating messages ---
+ *
+ * [Discord] Sending: Hello! How can I help you today?
+ * [Discord] Sending: All systems operational. GLM 4.7 is ready to assist.
+ * [Discord] Sending: I received your message: "Can you help me with a task?"
+ *
+ * --- Stopping ---
+ *
+ * [Discord] Stopped
+ */