@ebowwa/channel-types 0.1.1 → 0.2.0

package/src/plugins/registry.ts

@@ -0,0 +1,232 @@
+// src/plugins/registry.ts
+
+import type { ChannelId } from "../index.js";
+import type { ChannelPlugin } from "./types.plugin.js";
+
+// ============================================================
+// REGISTRATION TYPES
+// ============================================================
+
+export interface PluginChannelRegistration {
+  /** Plugin ID (usually matches channel ID) */
+  pluginId: string;
+
+  /** The channel plugin */
+  plugin: ChannelPlugin;
+
+  /** Optional dock metadata (lightweight channel info) */
+  dock?: ChannelDock;
+
+  /** Source (e.g., "core", "extension", "custom") */
+  source: string;
+}
+
+export interface ChannelDock {
+  /** Channel ID */
+  id: ChannelId;
+
+  /** Human-readable label */
+  label: string;
+
+  /** Capabilities summary */
+  capabilities: {
+    chatTypes: string[];
+    hasMedia: boolean;
+    hasThreads: boolean;
+    hasReactions: boolean;
+  };
+
+  /** Outbound limits */
+  outboundLimits: {
+    textChunkLimit: number;
+    maxFileSize?: number;
+  };
+}
+
+// ============================================================
+// PLUGIN REGISTRY
+// ============================================================
+
+class PluginRegistryImpl {
+  private channels: Map<string, PluginChannelRegistration> = new Map();
+  private channelOrder: string[] = [];
+
+  /**
+   * Register a channel plugin
+   */
+  registerChannel(registration: PluginChannelRegistration): void {
+    const id = registration.plugin.id;
+
+    if (typeof id !== "string") {
+      throw new Error("Channel plugin id must be a string");
+    }
+
+    const normalizedId = id.trim().toLowerCase();
+
+    if (this.channels.has(normalizedId)) {
+      console.warn(`[PluginRegistry] Channel "${normalizedId}" already registered, replacing`);
+    }
+
+    this.channels.set(normalizedId, registration);
+
+    // Add to order if not present
+    if (!this.channelOrder.includes(normalizedId)) {
+      this.channelOrder.push(normalizedId);
+    }
+
+    console.log(`[PluginRegistry] Registered channel: ${normalizedId} (source: ${registration.source})`);
+  }
+
+  /**
+   * Unregister a channel plugin
+   */
+  unregisterChannel(channelId: string): boolean {
+    const normalizedId = channelId.trim().toLowerCase();
+    const existed = this.channels.delete(normalizedId);
+
+    if (existed) {
+      this.channelOrder = this.channelOrder.filter(id => id !== normalizedId);
+    }
+
+    return existed;
+  }
+
+  /**
+   * Get a channel plugin by ID
+   */
+  getChannel(channelId: string): ChannelPlugin | undefined {
+    const normalizedId = this.normalizeChannelId(channelId);
+    const registration = this.channels.get(normalizedId);
+    return registration?.plugin;
+  }
+
+  /**
+   * Get channel registration (includes dock and source)
+   */
+  getChannelRegistration(channelId: string): PluginChannelRegistration | undefined {
+    const normalizedId = this.normalizeChannelId(channelId);
+    return this.channels.get(normalizedId);
+  }
+
+  /**
+   * Get all registered channels
+   */
+  getChannels(): ChannelPlugin[] {
+    return this.channelOrder
+      .map(id => this.channels.get(id)?.plugin)
+      .filter((p): p is ChannelPlugin => p !== undefined);
+  }
+
+  /**
+   * Get all channel registrations
+   */
+  getChannelRegistrations(): PluginChannelRegistration[] {
+    return this.channelOrder
+      .map(id => this.channels.get(id))
+      .filter((r): r is PluginChannelRegistration => r !== undefined);
+  }
+
+  /**
+   * Get channels ordered by registration
+   */
+  getChannelOrder(): string[] {
+    return [...this.channelOrder];
+  }
+
+  /**
+   * Set channel order
+   */
+  setChannelOrder(order: string[]): void {
+    this.channelOrder = order.map(id => id.toLowerCase().trim());
+  }
+
+  /**
+   * Get channels that support a specific capability
+   */
+  getChannelsByCapability(capability: keyof ChannelPlugin["capabilities"]["supports"]): ChannelPlugin[] {
+    return this.getChannels().filter(plugin =>
+      plugin.capabilities.supports[capability] === true
+    );
+  }
+
+  /**
+   * Get channels by chat type
+   */
+  getChannelsByChatType(chatType: string): ChannelPlugin[] {
+    return this.getChannels().filter(plugin =>
+      plugin.capabilities.chatTypes?.includes(chatType as any)
+    );
+  }
+
+  /**
+   * Check if a channel is registered
+   */
+  hasChannel(channelId: string): boolean {
+    return this.channels.has(this.normalizeChannelId(channelId));
+  }
+
+  /**
+   * Normalize channel ID (handle aliases)
+   */
+  normalizeChannelId(channelId: string): string {
+    const id = channelId.trim().toLowerCase();
+
+    // Common aliases
+    const aliases: Record<string, string> = {
+      "tg": "telegram",
+      "imsg": "imessage",
+      "wa": "whatsapp",
+      "dc": "discord",
+      "sl": "slack",
+    };
+
+    return aliases[id] || id;
+  }
+
+  /**
+   * Clear all registrations (for testing)
+   */
+  clear(): void {
+    this.channels.clear();
+    this.channelOrder = [];
+  }
+
+  /**
+   * Get registry stats
+   */
+  getStats(): {
+    channelCount: number;
+    channels: string[];
+  } {
+    return {
+      channelCount: this.channels.size,
+      channels: this.getChannelOrder(),
+    };
+  }
+}
+
+// ============================================================
+// SINGLETON INSTANCE
+// ============================================================
+
+export const pluginRegistry = new PluginRegistryImpl();
+
+// ============================================================
+// CONVENIENCE FUNCTIONS
+// ============================================================
+
+export function registerChannel(registration: PluginChannelRegistration): void {
+  pluginRegistry.registerChannel(registration);
+}
+
+export function getChannel(channelId: string): ChannelPlugin | undefined {
+  return pluginRegistry.getChannel(channelId);
+}
+
+export function getChannels(): ChannelPlugin[] {
+  return pluginRegistry.getChannels();
+}
+
+export function hasChannel(channelId: string): boolean {
+  return pluginRegistry.hasChannel(channelId);
+}

package/src/plugins/types.adapters.ts

@@ -0,0 +1,183 @@
+// src/plugins/types.adapters.ts
+
+import type { ChannelId, ChannelMessage } from "../index.js";
+
+// ============================================================
+// CONFIG ADAPTER
+// ============================================================
+
+export interface ChannelConfigAdapter<ResolvedAccount = unknown> {
+  /** List available account IDs for this channel */
+  listAccountIds: (config: Record<string, unknown>) => Promise<string[]>;
+
+  /** Resolve account config to a normalized account object */
+  resolveAccount: (config: Record<string, unknown>, accountId: string) => Promise<ResolvedAccount>;
+
+  /** Validate account credentials */
+  validateAccount?: (account: ResolvedAccount) => Promise<boolean>;
+}
+
+// ============================================================
+// OUTBOUND ADAPTER (Message Delivery)
+// ============================================================
+
+export type DeliveryMode = "direct" | "queue" | "webhook";
+
+export interface ChunkResult {
+  chunks: string[];
+  totalChunks: number;
+}
+
+export interface ChannelOutboundAdapter<ResolvedAccount = unknown> {
+  /** How messages are delivered */
+  deliveryMode: DeliveryMode;
+
+  /** Max characters per text message */
+  textChunkLimit?: number;
+
+  /** Chunk text for this channel (markdown-aware) */
+  chunker?: (text: string, limit: number) => ChunkResult;
+
+  /** Send text message */
+  sendText: (params: {
+    to: string;
+    text: string;
+    accountId: string;
+    account: ResolvedAccount;
+    replyToId?: string;
+    threadId?: string;
+  }) => Promise<OutboundResult>;
+
+  /** Send media message */
+  sendMedia?: (params: {
+    to: string;
+    text?: string;
+    mediaUrl: string;
+    mediaType: "image" | "video" | "audio" | "file";
+    accountId: string;
+    account: ResolvedAccount;
+  }) => Promise<OutboundResult>;
+
+  /** Send poll (if supported) */
+  sendPoll?: (params: {
+    to: string;
+    question: string;
+    options: string[];
+    accountId: string;
+    account: ResolvedAccount;
+  }) => Promise<OutboundResult>;
+}
+
+export interface OutboundResult {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+  timestamp: Date;
+}
+
+// ============================================================
+// GATEWAY ADAPTER (Account Lifecycle)
+// ============================================================
+
+export interface ChannelGatewayAdapter<ResolvedAccount = unknown> {
+  /** Start monitoring an account for incoming messages */
+  startAccount: (params: {
+    accountId: string;
+    account: ResolvedAccount;
+    onMessage: (message: ChannelMessage) => void;
+  }) => Promise<void>;
+
+  /** Stop monitoring an account */
+  stopAccount: (params: {
+    accountId: string;
+    account: ResolvedAccount;
+  }) => Promise<void>;
+
+  /** Check if account is active */
+  isAccountActive?: (accountId: string) => boolean;
+}
+
+// ============================================================
+// STATUS ADAPTER (Health & Audits)
+// ============================================================
+
+export interface ChannelStatusAdapter<ResolvedAccount = unknown> {
+  /** Health probe for account */
+  healthProbe: (params: {
+    accountId: string;
+    account: ResolvedAccount;
+  }) => Promise<HealthStatus>;
+
+  /** Audit account for issues */
+  audit?: (params: {
+    accountId: string;
+    account: ResolvedAccount;
+  }) => Promise<ChannelAudit[]>;
+}
+
+export interface HealthStatus {
+  healthy: boolean;
+  latency?: number;
+  error?: string;
+  lastCheck: Date;
+}
+
+export interface ChannelAudit {
+  level: "info" | "warning" | "error";
+  message: string;
+  timestamp: Date;
+}
+
+// ============================================================
+// THREADING ADAPTER
+// ============================================================
+
+export interface ChannelThreadingAdapter {
+  /** Supported reply modes */
+  replyModes: ("quote" | "thread" | "reference")[];
+
+  /** Default reply mode */
+  defaultReplyMode: "quote" | "thread" | "reference";
+
+  /** Get thread context for a message */
+  getThreadContext?: (messageId: string) => Promise<ChannelMessage[]>;
+}
+
+// ============================================================
+// MESSAGING ADAPTER (Target Normalization)
+// ============================================================
+
+export interface ChannelMessagingAdapter {
+  /** Normalize a target string (e.g., "@user", "tg:user", URL) to canonical format */
+  normalizeTarget: (target: string) => Promise<NormalizedTarget>;
+
+  /** Parse target from URL */
+  parseUrl?: (url: string) => Promise<NormalizedTarget | null>;
+}
+
+export interface NormalizedTarget {
+  channelId: ChannelId;
+  targetId: string;
+  targetType: "user" | "group" | "channel";
+  original: string;
+}
+
+// ============================================================
+// ONBOARDING ADAPTER (Setup Wizard)
+// ============================================================
+
+export interface ChannelOnboardingAdapter {
+  /** CLI setup wizard steps */
+  wizardSteps: OnboardingStep[];
+
+  /** Validate setup input */
+  validateInput?: (step: string, input: string) => Promise<boolean>;
+}
+
+export interface OnboardingStep {
+  id: string;
+  prompt: string;
+  type: "text" | "password" | "select" | "confirm";
+  options?: string[];
+  required: boolean;
+}

package/src/plugins/types.core.ts

@@ -0,0 +1,161 @@
+// src/plugins/types.core.ts
+
+/**
+ * Core types that support the plugin system.
+ * These are the foundational types used across the channel plugin architecture.
+ */
+
+import type { ChannelId } from "../index.js";
+
+// ============================================================
+// ACCOUNT RESOLUTION
+// ============================================================
+
+/** Resolved account interface - minimal guaranteed shape */
+export interface ResolvedAccount {
+  /** Unique account identifier */
+  id: string;
+
+  /** Human-readable label */
+  label?: string;
+
+  /** Platform-specific data */
+  [key: string]: unknown;
+}
+
+// ============================================================
+// CHANNEL IDENTITY
+// ============================================================
+
+/** String-based channel ID (for serialization) */
+export type ChannelIdString = string;
+
+/** Convert ChannelId to string representation */
+export function channelIdToString(id: ChannelId): ChannelIdString {
+  const base = `${id.platform}:${id.accountId}`;
+  return id.instanceId ? `${base}:${id.instanceId}` : base;
+}
+
+/** Parse string back to ChannelId */
+export function parseChannelIdString(str: ChannelIdString): ChannelId {
+  const parts = str.split(":");
+  if (parts.length < 2) {
+    throw new Error(`Invalid channel ID string: ${str}`);
+  }
+  return {
+    platform: parts[0] as ChannelId["platform"],
+    accountId: parts[1],
+    instanceId: parts[2],
+  };
+}
+
+// ============================================================
+// PLUGIN LIFECYCLE
+// ============================================================
+
+export interface PluginLifecycle {
+  /** Called when plugin is registered */
+  onRegister?: () => Promise<void> | void;
+
+  /** Called when plugin is unregistered */
+  onUnregister?: () => Promise<void> | void;
+
+  /** Called before channel starts */
+  beforeStart?: () => Promise<void> | void;
+
+  /** Called after channel stops */
+  afterStop?: () => Promise<void> | void;
+}
+
+// ============================================================
+// PLUGIN CONTEXT
+// ============================================================
+
+export interface PluginContext {
+  /** Plugin ID */
+  pluginId: string;
+
+  /** Working directory for plugin */
+  workDir: string;
+
+  /** Data directory for persistent storage */
+  dataDir: string;
+
+  /** Temporary directory */
+  tempDir: string;
+
+  /** Logger instance */
+  logger: PluginLogger;
+
+  /** Get a value from plugin config */
+  getConfig: (key: string, defaultValue?: unknown) => unknown;
+
+  /** Set a value in plugin config */
+  setConfig: (key: string, value: unknown) => Promise<void>;
+}
+
+export interface PluginLogger {
+  debug: (message: string, ...args: unknown[]) => void;
+  info: (message: string, ...args: unknown[]) => void;
+  warn: (message: string, ...args: unknown[]) => void;
+  error: (message: string, ...args: unknown[]) => void;
+}
+
+// ============================================================
+// PLUGIN ERROR
+// ============================================================
+
+export class PluginError extends Error {
+  constructor(
+    public readonly pluginId: string,
+    public readonly code: string,
+    message: string,
+    public readonly cause?: Error
+  ) {
+    super(`[${pluginId}] ${code}: ${message}`);
+    this.name = "PluginError";
+  }
+}
+
+export enum PluginErrorCode {
+  /** Invalid configuration */
+  INVALID_CONFIG = "INVALID_CONFIG",
+
+  /** Authentication failed */
+  AUTH_FAILED = "AUTH_FAILED",
+
+  /** Rate limit exceeded */
+  RATE_LIMITED = "RATE_LIMITED",
+
+  /** Network error */
+  NETWORK_ERROR = "NETWORK_ERROR",
+
+  /** Account not found */
+  ACCOUNT_NOT_FOUND = "ACCOUNT_NOT_FOUND",
+
+  /** Feature not supported */
+  NOT_SUPPORTED = "NOT_SUPPORTED",
+
+  /** Internal plugin error */
+  INTERNAL_ERROR = "INTERNAL_ERROR",
+}
+
+// ============================================================
+// CHANNEL EVENTS
+// ============================================================
+
+export type ChannelEventType =
+  | "message"
+  | "message_edit"
+  | "message_delete"
+  | "reaction"
+  | "typing"
+  | "presence"
+  | "error";
+
+export interface ChannelEvent {
+  type: ChannelEventType;
+  channelId: ChannelId;
+  timestamp: Date;
+  data: unknown;
+}