@almadar/cli 1.0.6 → 1.0.7

package/shells/typescript-shell/packages/server/src/integrators/registry.ts

@@ -1,318 +0,0 @@
-/**
- * Integrator Registry
- *
- * Central registry for service integrators.
- * Provides type-safe lookup and management of integrators.
- *
- * @packageDocumentation
- */
-
-import type {
-  ServiceIntegrator,
-  IntegratorRegistry,
-  IntegratorRegistryEntry,
-  EventBus,
-} from './types.js';
-
-// ============================================================================
-// Registry Implementation
-// ============================================================================
-
-/**
- * Internal storage for registered integrators.
- */
-const integrators: Map<string, IntegratorRegistryEntry> = new Map();
-
-/**
- * Register an integrator in the registry.
- *
- * @param integrator - The integrator to register
- * @param builtIn - Whether this is a built-in integrator (default: false)
- * @throws Error if an integrator with the same name is already registered
- *
- * @example
- * ```typescript
- * registerIntegrator(youtubeIntegrator);
- * registerIntegrator(customIntegrator, false);
- * ```
- */
-export function registerIntegrator(
-  integrator: ServiceIntegrator,
-  builtIn: boolean = false
-): void {
-  if (integrators.has(integrator.name)) {
-    throw new Error(
-      `Integrator "${integrator.name}" is already registered. Use a unique name.`
-    );
-  }
-
-  integrators.set(integrator.name, {
-    integrator,
-    builtIn,
-    registeredAt: new Date(),
-  });
-}
-
-/**
- * Get an integrator by name.
- *
- * @param name - The integrator name
- * @returns The integrator or undefined if not found
- *
- * @example
- * ```typescript
- * const youtube = getIntegrator('youtube');
- * if (youtube) {
- *   await youtube.execute('search', { query: 'cats' }, eventBus, callbacks);
- * }
- * ```
- */
-export function getIntegrator(name: string): ServiceIntegrator | undefined {
-  return integrators.get(name)?.integrator;
-}
-
-/**
- * Check if an integrator is registered.
- *
- * @param name - The integrator name
- * @returns True if the integrator exists
- */
-export function hasIntegrator(name: string): boolean {
-  return integrators.has(name);
-}
-
-/**
- * List all registered integrator names.
- *
- * @returns Array of integrator names
- *
- * @example
- * ```typescript
- * const names = listIntegrators(); // ['youtube', 'stripe', 'twilio']
- * ```
- */
-export function listIntegrators(): string[] {
-  return Array.from(integrators.keys());
-}
-
-/**
- * List integrators filtered by category.
- *
- * @param category - The category to filter by (e.g., 'media', 'payment')
- * @returns Array of integrators in the category
- *
- * @example
- * ```typescript
- * const paymentIntegrators = listIntegratorsByCategory('payment');
- * ```
- */
-export function listIntegratorsByCategory(
-  category: string
-): ServiceIntegrator[] {
-  return Array.from(integrators.values())
-    .filter((entry) => entry.integrator.category === category)
-    .map((entry) => entry.integrator);
-}
-
-/**
- * Get all registered integrators.
- *
- * @returns Array of all integrators
- */
-export function getAllIntegrators(): ServiceIntegrator[] {
-  return Array.from(integrators.values()).map((entry) => entry.integrator);
-}
-
-/**
- * Get registry entry details for an integrator.
- *
- * @param name - The integrator name
- * @returns Registry entry or undefined
- */
-export function getIntegratorEntry(
-  name: string
-): IntegratorRegistryEntry | undefined {
-  return integrators.get(name);
-}
-
-/**
- * Unregister an integrator.
- *
- * @param name - The integrator name to remove
- * @returns True if the integrator was removed
- */
-export function unregisterIntegrator(name: string): boolean {
-  return integrators.delete(name);
-}
-
-/**
- * Clear all registered integrators.
- * Useful for testing.
- */
-export function clearRegistry(): void {
-  integrators.clear();
-}
-
-/**
- * Get count of registered integrators.
- */
-export function getIntegratorCount(): number {
-  return integrators.size;
-}
-
-// ============================================================================
-// Registry Object (for interface compatibility)
-// ============================================================================
-
-/**
- * Registry object implementing IntegratorRegistry interface.
- * Use this when you need an object-oriented interface.
- */
-export const integratorRegistry: IntegratorRegistry = {
-  register: registerIntegrator,
-  get: getIntegrator,
-  has: hasIntegrator,
-  list: listIntegrators,
-  listByCategory: listIntegratorsByCategory,
-  getAll: getAllIntegrators,
-};
-
-// ============================================================================
-// Execution Helpers
-// ============================================================================
-
-/**
- * Execute an action on a registered integrator (callback pattern).
- *
- * This is a convenience function that looks up the integrator and executes.
- *
- * @param serviceName - The integrator/service name
- * @param action - The action to execute
- * @param params - Parameters for the action
- * @param eventBus - Event bus for callbacks
- * @param callbacks - Success/error event names
- * @throws Error if integrator is not registered
- *
- * @example
- * ```typescript
- * await executeIntegrator(
- *   'youtube',
- *   'search',
- *   { query: 'typescript tutorial' },
- *   eventBus,
- *   { onSuccess: 'SEARCH_COMPLETE', onError: 'SEARCH_FAILED' }
- * );
- * ```
- */
-export async function executeIntegrator(
-  serviceName: string,
-  action: string,
-  params: Record<string, unknown>,
-  eventBus: EventBus,
-  callbacks: { onSuccess: string; onError: string }
-): Promise<void> {
-  const integrator = getIntegrator(serviceName);
-
-  if (!integrator) {
-    eventBus.emit(callbacks.onError, {
-      code: 'INTEGRATOR_NOT_FOUND',
-      message: `Integrator "${serviceName}" is not registered`,
-    });
-    return;
-  }
-
-  // Validate params if the integrator supports it
-  if (integrator.validateParams) {
-    const validation = integrator.validateParams(action, params);
-    if (!validation.valid) {
-      eventBus.emit(callbacks.onError, {
-        code: 'VALIDATION_ERROR',
-        message: `Invalid parameters: ${validation.errors?.join(', ')}`,
-      });
-      return;
-    }
-  }
-
-  // Check configuration if the integrator supports it
-  if (integrator.isConfigured && !integrator.isConfigured()) {
-    eventBus.emit(callbacks.onError, {
-      code: 'NOT_CONFIGURED',
-      message: `Integrator "${serviceName}" is not properly configured`,
-    });
-    return;
-  }
-
-  // Execute the action
-  await integrator.execute(action, params, eventBus, callbacks);
-}
-
-/**
- * Call an integrator action and return the result as a Promise.
- *
- * This is a Promise-based wrapper around the callback-based integrator interface.
- * Use this when you need direct request-response semantics instead of event-based.
- *
- * @param serviceName - The integrator/service name
- * @param action - The action to execute
- * @param params - Parameters for the action
- * @returns Promise resolving to the result or rejecting with error
- * @throws Error if integrator is not found or execution fails
- *
- * @example
- * ```typescript
- * const results = await callIntegrator('youtube', 'search', { query: 'cats' });
- * console.log(results); // Array of search results
- * ```
- */
-export async function callIntegrator(
-  serviceName: string,
-  action: string,
-  params: Record<string, unknown>
-): Promise<unknown> {
-  const integrator = getIntegrator(serviceName);
-
-  if (!integrator) {
-    throw new Error(`Integrator "${serviceName}" is not registered`);
-  }
-
-  // Validate params if the integrator supports it
-  if (integrator.validateParams) {
-    const validation = integrator.validateParams(action, params);
-    if (!validation.valid) {
-      throw new Error(`Invalid parameters: ${validation.errors?.join(', ')}`);
-    }
-  }
-
-  // Check configuration if the integrator supports it
-  if (integrator.isConfigured && !integrator.isConfigured()) {
-    throw new Error(`Integrator "${serviceName}" is not properly configured`);
-  }
-
-  // Create a one-shot event bus that resolves/rejects the promise
-  return new Promise((resolve, reject) => {
-    // Generate unique callback event names
-    const successEvent = `__internal_success_${Date.now()}_${Math.random()}`;
-    const errorEvent = `__internal_error_${Date.now()}_${Math.random()}`;
-
-    // Create a minimal event bus that captures the result
-    // Only emit is used by integrators, on/once are no-ops
-    const oneShot: { emit: (event: string, payload?: unknown) => void; on: () => () => void; once: () => void } = {
-      emit: (event: string, payload?: unknown) => {
-        if (event === successEvent) {
-          resolve(payload);
-        } else if (event === errorEvent) {
-          const error = payload as { code?: string; message?: string } | undefined;
-          reject(new Error(error?.message || 'Integrator execution failed'));
-        }
-      },
-      // No-op implementations - not used for one-shot calls
-      on: () => () => {},
-      once: () => {},
-    };
-
-    // Execute with internal callbacks
-    integrator
-      .execute(action, params, oneShot, { onSuccess: successEvent, onError: errorEvent })
-      .catch(reject);
-  });
-}

package/shells/typescript-shell/packages/server/src/integrators/types.ts

@@ -1,248 +0,0 @@
-/**
- * Shell Integrator Types
- *
- * Defines the interfaces and types for service integrators.
- * Integrators handle external API calls and emit results via EventBus.
- *
- * @packageDocumentation
- */
-
-// ============================================================================
-// Event Bus Interface
-// ============================================================================
-
-/**
- * Event bus for inter-trait communication.
- * Integrators use this to emit success/error events back to traits.
- */
-export interface EventBus {
-  /**
-   * Emit an event with optional payload.
-   * @param event - Event name (e.g., 'SEARCH_COMPLETE', 'PAYMENT_FAILED')
-   * @param payload - Optional data payload
-   */
-  emit(event: string, payload?: unknown): void;
-
-  /**
-   * Subscribe to an event.
-   * @param event - Event name to subscribe to
-   * @param handler - Callback function when event is emitted
-   * @returns Unsubscribe function
-   */
-  on(event: string, handler: (payload?: unknown) => void): () => void;
-
-  /**
-   * Subscribe to an event for one-time execution.
-   * @param event - Event name to subscribe to
-   * @param handler - Callback function when event is emitted
-   */
-  once(event: string, handler: (payload?: unknown) => void): void;
-}
-
-// ============================================================================
-// Integrator Action Types
-// ============================================================================
-
-/**
- * Parameter definition for an integrator action.
- */
-export interface ActionParam {
-  /** Parameter name */
-  name: string;
-  /** Parameter type (string, number, boolean, object, array) */
-  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
-  /** Whether the parameter is required */
-  required: boolean;
-  /** Optional description for documentation */
-  description?: string;
-  /** Optional default value */
-  defaultValue?: unknown;
-}
-
-/**
- * Metadata for an integrator action.
- * Describes what the action does, its parameters, and expected response.
- */
-export interface IntegratorAction {
-  /** Action name (e.g., 'search', 'createPaymentIntent') */
-  name: string;
-  /** Human-readable description */
-  description: string;
-  /** Parameters the action accepts */
-  params: ActionParam[];
-  /** Shape of the success response payload */
-  responseShape?: Record<string, string>;
-}
-
-// ============================================================================
-// Service Integrator Interface
-// ============================================================================
-
-/**
- * Callback configuration for integrator execution.
- */
-export interface IntegratorCallbacks {
-  /** Event to emit on successful execution */
-  onSuccess: string;
-  /** Event to emit on error */
-  onError: string;
-}
-
-/**
- * Error payload structure for integrator errors.
- */
-export interface IntegratorError {
-  /** Error code */
-  code: string;
-  /** Human-readable error message */
-  message: string;
-  /** Original error details (optional) */
-  details?: unknown;
-}
-
-/**
- * Execution context passed to integrators.
- */
-export interface ExecutionContext {
-  /** Request timeout in milliseconds */
-  timeout?: number;
-  /** Retry configuration */
-  retry?: {
-    maxAttempts: number;
-    backoffMs: number;
-  };
-  /** Additional context data */
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * Service integrator interface.
- *
- * Integrators handle external API calls and form "closed circuits"
- * by emitting results back through the event bus.
- *
- * @example
- * ```typescript
- * const youtubeIntegrator: ServiceIntegrator = {
- *   name: 'youtube',
- *   description: 'YouTube Data API integration',
- *   actions: [
- *     { name: 'search', description: 'Search videos', params: [...] }
- *   ],
- *   execute: async (action, params, eventBus, callbacks) => {
- *     try {
- *       const results = await youtubeApi.search(params.query);
- *       eventBus.emit(callbacks.onSuccess, results);
- *     } catch (error) {
- *       eventBus.emit(callbacks.onError, { code: 'API_ERROR', message: error.message });
- *     }
- *   }
- * };
- * ```
- */
-export interface ServiceIntegrator {
-  /** Unique integrator name (e.g., 'youtube', 'stripe') */
-  name: string;
-  /** Human-readable description */
-  description: string;
-  /** Category for grouping (e.g., 'media', 'payment', 'messaging') */
-  category: string;
-  /** Available actions this integrator supports */
-  actions: IntegratorAction[];
-
-  /**
-   * Execute an action on this integrator.
-   *
-   * This method MUST:
-   * 1. Perform the external API call
-   * 2. Emit `callbacks.onSuccess` with result payload on success
-   * 3. Emit `callbacks.onError` with IntegratorError on failure
-   *
-   * @param action - Action name to execute
-   * @param params - Parameters for the action
-   * @param eventBus - Event bus for emitting results
-   * @param callbacks - Success/error event names
-   * @param context - Optional execution context
-   */
-  execute(
-    action: string,
-    params: Record<string, unknown>,
-    eventBus: EventBus,
-    callbacks: IntegratorCallbacks,
-    context?: ExecutionContext
-  ): Promise<void>;
-
-  /**
-   * Validate action parameters before execution.
-   * @param action - Action name
-   * @param params - Parameters to validate
-   * @returns Validation result with any errors
-   */
-  validateParams?(
-    action: string,
-    params: Record<string, unknown>
-  ): { valid: boolean; errors?: string[] };
-
-  /**
-   * Check if the integrator is properly configured (e.g., API key present).
-   * @returns Whether the integrator is ready to use
-   */
-  isConfigured?(): boolean;
-}
-
-// ============================================================================
-// Integrator Registry Types
-// ============================================================================
-
-/**
- * Registry entry for an integrator.
- */
-export interface IntegratorRegistryEntry {
-  /** The integrator instance */
-  integrator: ServiceIntegrator;
-  /** Whether this is a built-in integrator */
-  builtIn: boolean;
-  /** Registration timestamp */
-  registeredAt: Date;
-}
-
-/**
- * Integrator registry interface.
- */
-export interface IntegratorRegistry {
-  /**
-   * Register an integrator.
-   * @param integrator - Integrator to register
-   * @param builtIn - Whether this is a built-in integrator
-   */
-  register(integrator: ServiceIntegrator, builtIn?: boolean): void;
-
-  /**
-   * Get an integrator by name.
-   * @param name - Integrator name
-   * @returns Integrator or undefined if not found
-   */
-  get(name: string): ServiceIntegrator | undefined;
-
-  /**
-   * Check if an integrator exists.
-   * @param name - Integrator name
-   */
-  has(name: string): boolean;
-
-  /**
-   * List all registered integrator names.
-   */
-  list(): string[];
-
-  /**
-   * List integrators by category.
-   * @param category - Category to filter by
-   */
-  listByCategory(category: string): ServiceIntegrator[];
-
-  /**
-   * Get all registered integrators.
-   */
-  getAll(): ServiceIntegrator[];
-}