@ebowwa/channel-types 0.1.0

package/src/index.ts

@@ -0,0 +1,367 @@
+/**
+ * @ebowwa/channel-types
+ *
+ * Composable types for channel-LLM communication.
+ *
+ * Architecture:
+ *   Channel (Discord/Telegram/WhatsApp)
+ *       ↓ ChannelMessage (normalized)
+ *   LLMHandler.process()
+ *       ↓ ChannelResponse (normalized)
+ *   Channel delivers response
+ */
+
+// ============================================================
+// CHANNEL IDENTITY
+// ============================================================
+
+/** Supported channel platforms */
+export type ChannelPlatform =
+  | "discord"
+  | "telegram"
+  | "whatsapp"
+  | "imessage"
+  | "slack"
+  | "signal"
+  | "web"
+  | "cli"
+  | "custom";
+
+/** Unique channel identifier */
+export interface ChannelId {
+  platform: ChannelPlatform;
+  accountId: string; // Bot/user account identifier
+  instanceId?: string; // Optional for multiple instances
+}
+
+// ============================================================
+// NORMALIZED MESSAGE FORMAT
+// ============================================================
+
+/** Reference to a message (for replies) */
+export interface MessageRef {
+  messageId: string;
+  channelId: ChannelId;
+}
+
+/** Sender information */
+export interface MessageSender {
+  id: string;
+  username?: string;
+  displayName?: string;
+  isBot?: boolean;
+}
+
+/** Media attachment */
+export interface MediaAttachment {
+  type: "image" | "video" | "audio" | "file";
+  url?: string;
+  data?: Buffer;
+  mimeType?: string;
+  filename?: string;
+}
+
+/** Message context (where it came from) */
+export interface MessageContext {
+  /** Direct message vs group/channel */
+  isDM: boolean;
+  /** Group or channel name */
+  groupName?: string;
+  /** Thread ID if in a thread */
+  threadId?: string;
+  /** Additional platform-specific metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Normalized incoming message from any channel.
+ * This is the universal format that LLM handlers receive.
+ */
+export interface ChannelMessage {
+  // Identity
+  readonly messageId: string;
+  readonly channelId: ChannelId;
+  readonly timestamp: Date;
+
+  // Sender
+  readonly sender: MessageSender;
+
+  // Content
+  readonly text: string;
+  readonly media?: MediaAttachment[];
+
+  // Context
+  readonly context: MessageContext;
+
+  // Reply chain
+  readonly replyTo?: MessageRef;
+  readonly quotedText?: string;
+}
+
+// ============================================================
+// NORMALIZED RESPONSE FORMAT
+// ============================================================
+
+/** Response content options */
+export interface ResponseContent {
+  /** Text response */
+  text: string;
+
+  /** Optional media attachments */
+  media?: MediaAttachment[];
+
+  /** Whether to reply to the original message */
+  replyToOriginal?: boolean;
+
+  /** Platform-specific options */
+  options?: {
+    /** Discord: ephemeral (only visible to sender) */
+    ephemeral?: boolean;
+    /** Telegram: parse mode */
+    parseMode?: "markdown" | "html";
+    /** Any platform-specific flags */
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Normalized response from LLM handler.
+ * Channels deliver this back to the platform.
+ */
+export interface ChannelResponse {
+  /** Response content */
+  readonly content: ResponseContent;
+
+  /** Reference to the original message (for reply) */
+  readonly replyTo: MessageRef;
+
+  /** Whether this response completes the interaction */
+  readonly isComplete?: boolean;
+
+  /** Optional metadata for logging/debugging */
+  readonly metadata?: {
+    model?: string;
+    tokensUsed?: number;
+    latency?: number;
+    [key: string]: unknown;
+  };
+}
+
+/** Streaming response chunk */
+export interface StreamChunk {
+  /** Chunk of text */
+  text: string;
+  /** Whether this is the final chunk */
+  done: boolean;
+  /** Sequence number */
+  seq?: number;
+}
+
+// ============================================================
+// CHANNEL CONNECTOR INTERFACE
+// ============================================================
+
+/**
+ * Interface for channel implementations.
+ * Channels normalize platform messages and deliver responses.
+ */
+export interface ChannelConnector {
+  /** Channel identity */
+  readonly id: ChannelId;
+
+  /** Human-readable label */
+  readonly label: string;
+
+  /** Platform capabilities */
+  readonly capabilities: ChannelCapabilities;
+
+  /** Start listening for messages */
+  start(): Promise<void>;
+
+  /** Stop listening */
+  stop(): Promise<void>;
+
+  /** Register handler for incoming messages */
+  onMessage(handler: MessageHandler): void;
+
+  /** Send response to channel */
+  send(response: ChannelResponse): Promise<void>;
+
+  /** Send streaming response (if supported) */
+  stream?(response: ChannelResponse, chunks: AsyncIterable<StreamChunk>): Promise<void>;
+
+  /** Check if connected */
+  isConnected(): boolean;
+}
+
+/** Message handler function type */
+export type MessageHandler = (message: ChannelMessage) => Promise<ChannelResponse | void>;
+
+/** Channel capabilities */
+export interface ChannelCapabilities {
+  /** Supported message types */
+  readonly supports: {
+    text: boolean;
+    media: boolean;
+    replies: boolean;
+    threads: boolean;
+    reactions: boolean;
+    editing: boolean;
+    streaming: boolean;
+  };
+
+  /** Media constraints */
+  readonly media?: {
+    maxFileSize?: number;
+    supportedMimeTypes?: string[];
+  };
+
+  /** Rate limits */
+  readonly rateLimits?: {
+    messagesPerMinute?: number;
+    charactersPerMessage?: number;
+  };
+}
+
+// ============================================================
+// LLM HANDLER INTERFACE
+// ============================================================
+
+/**
+ * Interface for LLM implementations.
+ * LLM handlers receive normalized messages and return responses.
+ */
+export interface LLMHandler {
+  /** Handler identity */
+  readonly id: string;
+
+  /** Model identifier */
+  readonly model: string;
+
+  /** Process incoming message */
+  process(message: ChannelMessage): Promise<ChannelResponse>;
+
+  /** Process with streaming (optional) */
+  stream?(message: ChannelMessage): AsyncIterable<StreamChunk>;
+
+  /** Check if ready */
+  isReady(): boolean;
+}
+
+// ============================================================
+// CHANNEL-LLM BRIDGE
+// ============================================================
+
+/**
+ * Bridge that connects channels to LLM handlers.
+ * Routes messages from channels to appropriate handlers.
+ */
+export interface ChannelBridge {
+  /** Register a channel */
+  registerChannel(channel: ChannelConnector): void;
+
+  /** Register an LLM handler */
+  registerHandler(handler: LLMHandler): void;
+
+  /** Set default handler for a channel */
+  setDefaultHandler(channelId: ChannelId, handlerId: string): void;
+
+  /** Start all channels */
+  start(): Promise<void>;
+
+  /** Stop all channels */
+  stop(): Promise<void>;
+
+  /** Get connected channels */
+  getChannels(): ChannelConnector[];
+
+  /** Get registered handlers */
+  getHandlers(): LLMHandler[];
+}
+
+// ============================================================
+// UTILITY TYPES
+// ============================================================
+
+/** Create a simple channel ID */
+export function createChannelId(
+  platform: ChannelPlatform,
+  accountId: string,
+  instanceId?: string
+): ChannelId {
+  return { platform, accountId, instanceId };
+}
+
+/** Create a simple message ref */
+export function createMessageRef(messageId: string, channelId: ChannelId): MessageRef {
+  return { messageId, channelId };
+}
+
+/** Check if two channel IDs match */
+export function channelIdsMatch(a: ChannelId, b: ChannelId): boolean {
+  return (
+    a.platform === b.platform &&
+    a.accountId === b.accountId &&
+    a.instanceId === b.instanceId
+  );
+}
+
+/** Format channel ID for logging */
+export function formatChannelId(id: ChannelId): string {
+  const base = `${id.platform}:${id.accountId}`;
+  return id.instanceId ? `${base}:${id.instanceId}` : base;
+}
+
+/** Default capabilities for text-only channels */
+export const DEFAULT_CAPABILITIES: ChannelCapabilities = {
+  supports: {
+    text: true,
+    media: false,
+    replies: false,
+    threads: false,
+    reactions: false,
+    editing: false,
+    streaming: false,
+  },
+};
+
+/** Full capabilities for rich channels (Discord, Slack) */
+export const RICH_CAPABILITIES: ChannelCapabilities = {
+  supports: {
+    text: true,
+    media: true,
+    replies: true,
+    threads: true,
+    reactions: true,
+    editing: true,
+    streaming: true,
+  },
+};
+
+// Re-export config types and utilities
+export type {
+  BaseChannelConfig,
+  TelegramChannelConfig,
+  DiscordChannelConfig,
+  WhatsAppChannelConfig,
+  IMessageChannelConfig,
+  SlackChannelConfig,
+  SignalChannelConfig,
+  CLIChannelConfig,
+  WebChannelConfig,
+  ChannelConfig,
+  ChannelConfigMap,
+} from "./config.js";
+
+export {
+  loadChannelConfigsFromEnv,
+  getChannelId,
+  validateChannelConfig,
+  getEnabledChannels,
+  getChannelsByPlatform,
+  createChannelConfig,
+  parseChannelConfig,
+  parseChannelConfigs,
+  serializeChannelConfig,
+  serializeChannelConfigs,
+} from "./config.js";

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}