@kadi.build/core 0.0.1-alpha.0 → 0.0.1-alpha.10

package/dist/client/KadiClient.d.ts

@@ -0,0 +1,270 @@
+/**
+ * KADI Client
+ *
+ * Thin orchestrator that composes specialized modules to provide the
+ * complete KADI client functionality.
+ *
+ * This is dramatically simpler than the old implementation because each
+ * concern has been properly separated.
+ *
+ * @module client/KadiClient
+ */
+import { EventEmitter } from 'events';
+import type { KadiConfig, ResolvedConfig, ToolHandler, KadiTool, EventCallback, UnsubscribeFunction, PublishOptions } from '../types/index.js';
+import { BrokerConnectionManager } from '../broker/BrokerConnectionManager.js';
+import { BrokerProtocol } from '../broker/BrokerProtocol.js';
+import { type LoadedAbility, type LoadOptions } from '../abilities/index.js';
+import type { IBrokerClient } from '../transports/BrokerTransport.js';
+/**
+ * KADI Client
+ *
+ * Main client class for KADI framework.
+ * Orchestrates tool registry, event hub, broker connections, and ability loading.
+ *
+ * @example
+ * ```typescript
+ * // Create client
+ * const client = new KadiClient({
+ *   name: 'my-service',
+ *   brokers: { local: 'ws://localhost:8080' },
+ *   networks: ['global']
+ * });
+ *
+ * // Register a tool
+ * client.registerTool('greet', async ({ name }) => {
+ *   return { message: `Hello, ${name}!` };
+ * });
+ *
+ * // Connect to brokers
+ * await client.connect();
+ *
+ * // Load an ability (explicit transport)
+ * const calc = await client.load('calculator', 'broker');
+ * const result = await calc.add({ a: 5, b: 3 });
+ *
+ * // Subscribe to events
+ * client.subscribeToEvent('user.*', (data) => {
+ *   console.log('User event:', data);
+ * });
+ *
+ * // Publish an event
+ * client.publishEvent('user.login', { userId: '123' });
+ * ```
+ */
+export declare class KadiClient extends EventEmitter implements IBrokerClient {
+    /**
+     * Resolved configuration
+     */
+    readonly config: ResolvedConfig;
+    /**
+     * Tool registry
+     */
+    private readonly tools;
+    /**
+     * Event hub
+     */
+    private readonly events;
+    /**
+     * Broker connection manager
+     */
+    private readonly brokers;
+    /**
+     * Broker protocol instances (per broker)
+     */
+    private readonly protocols;
+    /**
+     * Ability loader
+     */
+    private readonly abilityLoader;
+    /**
+     * Whether client is initialized
+     */
+    private initialized;
+    /**
+     * Create a new KADI Client
+     *
+     * @param config - Client configuration
+     */
+    constructor(config: KadiConfig);
+    /**
+     * Connect to configured brokers
+     *
+     * @throws {KadiError} If connection fails
+     *
+     * @example
+     * ```typescript
+     * await client.connect();
+     * console.log('Connected to brokers');
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Connect to all configured brokers
+     */
+    private connectToBrokers;
+    /**
+     * Register capabilities with a broker
+     *
+     * @param protocol - Broker protocol instance
+     */
+    private registerCapabilitiesWithBroker;
+    /**
+     * Register a tool (MCP-based)
+     *
+     * @template TInput - Tool input type
+     * @template TOutput - Tool output type
+     * @param definition - MCP-compliant tool definition
+     * @param handler - Tool handler function
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * client.registerTool({
+     *   name: 'add',
+     *   description: 'Add two numbers',
+     *   version: '1.0.0',
+     *   tags: ['math'],
+     *   inputSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       a: { type: 'number' },
+     *       b: { type: 'number' }
+     *     },
+     *     required: ['a', 'b']
+     *   },
+     *   outputSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       result: { type: 'number' }
+     *     }
+     *   }
+     * }, async ({ a, b }) => {
+     *   return { result: a + b };
+     * });
+     * ```
+     */
+    registerTool<TInput = unknown, TOutput = unknown>(definition: KadiTool, handler: ToolHandler<TInput, TOutput>): this;
+    /**
+     * Load an ability
+     *
+     * **Explicit Transport, Excellent Developer Experience:**
+     * - Explicit transport selection (no magic)
+     * - Transport-specific options (only relevant fields shown)
+     * - Smart caching (avoids duplicate loads)
+     * - Runtime validation (optional)
+     * - Helpful errors with suggestions
+     *
+     * @param name - Ability name
+     * @param transport - Transport type ('native', 'stdio', or 'broker')
+     * @param options - Load options (transport-specific, optional)
+     * @returns Proxied ability with dynamic method access
+     *
+     * @throws {KadiError} If loading fails
+     *
+     * @example
+     * ```typescript
+     * // Simple broker load
+     * const calc = await client.load('calculator', 'broker');
+     * await calc.add({ a: 5, b: 3 });
+     *
+     * // With options
+     * const remote = await client.load('gpu-service', 'broker', {
+     *   networks: ['global', 'gpu-cluster']
+     * });
+     *
+     * // With runtime validation
+     * const validated = await client.load('calculator', 'broker', {
+     *   validate: true  // Runtime check for expected methods
+     * });
+     *
+     * // Native transport
+     * const local = await client.load('math-lib', 'native', {
+     *   path: './abilities/math'
+     * });
+     * ```
+     */
+    load(name: string, transport: 'native' | 'stdio' | 'broker', options?: LoadOptions): Promise<LoadedAbility>;
+    /**
+     * Subscribe to events
+     *
+     * @template T - Event data type
+     * @param pattern - Event pattern (supports wildcards)
+     * @param callback - Event callback
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = client.subscribeToEvent('user.*', (data) => {
+     *   console.log('User event:', data);
+     * });
+     *
+     * // Later...
+     * unsubscribe();
+     * ```
+     */
+    subscribeToEvent<T = unknown>(pattern: string, callback: EventCallback<T>): UnsubscribeFunction;
+    /**
+     * Publish an event
+     *
+     * @template T - Event data type
+     * @param eventName - Event name
+     * @param data - Event data
+     * @param options - Publishing options
+     *
+     * @example
+     * ```typescript
+     * client.publishEvent('user.login', {
+     *   userId: '123',
+     *   timestamp: Date.now()
+     * });
+     * ```
+     */
+    publishEvent<T = unknown>(eventName: string, data: T, options?: PublishOptions): void;
+    /**
+     * Disconnect from all brokers and cleanup
+     *
+     * @example
+     * ```typescript
+     * await client.disconnect();
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get broker manager (implements IBrokerClient)
+     */
+    getBrokerManager(): BrokerConnectionManager;
+    /**
+     * Get broker protocol instance (implements IBrokerClient)
+     *
+     * @param brokerName - Optional broker name (uses default if not specified)
+     */
+    getBrokerProtocol(brokerName?: string): BrokerProtocol;
+    /**
+     * Networks (implements IBrokerClient)
+     */
+    get networks(): string[];
+    /**
+     * Create minimal configuration for constructor
+     * Full resolution happens in connect()
+     */
+    private createMinimalConfig;
+    /**
+     * Setup broker event forwarding
+     */
+    private setupBrokerEventForwarding;
+    /**
+     * Handle incoming tool invocation requests from broker
+     *
+     * Flow:
+     * 1. Extract id from top-level message (JSON-RPC request id)
+     * 2. Look up tool handler by name
+     * 3. Execute handler with toolInput
+     * 4. Send JSON-RPC response back to broker with matching id
+     *
+     * @param brokerName - Name of the broker connection to use for response
+     * @param message - Full JSON-RPC request message with id, method, and params
+     * @private
+     */
+    private handleIncomingToolRequest;
+}
+//# sourceMappingURL=KadiClient.d.ts.map

package/dist/client/KadiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KadiClient.d.ts","sourceRoot":"","sources":["../../src/client/KadiClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAEV,UAAU,EACV,cAAc,EACd,WAAW,EACX,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAoB,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAiB,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,UAAW,SAAQ,YAAa,YAAW,aAAa;IACnE;;OAEG;IACH,SAAgB,MAAM,EAAE,cAAc,CAAC;IAEvC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAElC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAE/D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAE9C;;OAEG;IACH,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;gBACS,MAAM,EAAE,UAAU;IAoB9B;;;;;;;;;;OAUG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB9B;;OAEG;YACW,gBAAgB;IA4C9B;;;;OAIG;YACW,8BAA8B;IAY5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,YAAY,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC9C,UAAU,EAAE,QAAQ,EACpB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,IAAI;IAwBP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,EACxC,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,aAAa,CAAC;IAIzB;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GACzB,mBAAmB;IAuBtB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,CAAC,GAAG,OAAO,EACtB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,cAAc,GACvB,IAAI;IAuBP;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBjC;;OAEG;IACH,gBAAgB,IAAI,uBAAuB;IAI3C;;;;OAIG;IACH,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,cAAc;IAuBtD;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,EAAE,CAEvB;IAED;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA4B3B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAwBlC;;;;;;;;;;;;OAYG;YACW,yBAAyB;CAwCxC"}