@soederpop/luca 0.0.5 → 0.0.7

package/src/client.ts

@@ -1,25 +1,24 @@
 import { Helper } from "./helper.js";
 import type { Container, ContainerContext } from "./container.js";
-import axios, { type AxiosError, type AxiosInstance, type AxiosRequestConfig } from "axios";
 import { Registry } from "./registry.js";
 import { z } from 'zod'
 import {
   ClientStateSchema, ClientOptionsSchema, ClientEventsSchema,
-  WebSocketClientStateSchema, WebSocketClientOptionsSchema, WebSocketClientEventsSchema,
-  GraphClientOptionsSchema, GraphClientEventsSchema,
 } from './schemas/base.js'
 
 export type ClientOptions = z.infer<typeof ClientOptionsSchema>
 export type ClientState = z.infer<typeof ClientStateSchema>
-export type WebSocketClientState = z.infer<typeof WebSocketClientStateSchema>
-export type WebSocketClientOptions = z.infer<typeof WebSocketClientOptionsSchema>
-export type GraphClientOptions = z.infer<typeof GraphClientOptionsSchema>
 
-export interface AvailableClients {
-  rest: typeof RestClient;
-  graph: typeof GraphClient;
-  websocket: typeof WebSocketClient;
-}
+// Subclass types re-exported for backward compatibility.
+// Import the concrete classes from their individual files:
+//   import { RestClient } from './clients/rest'
+//   import { GraphClient } from './clients/graph'
+//   import { WebSocketClient } from './clients/websocket'
+export type { WebSocketClientState, WebSocketClientOptions } from './clients/websocket.js'
+export type { GraphClientOptions } from './clients/graph.js'
+
+// AvailableClients is an open interface — subclasses augment it via `declare module`
+export interface AvailableClients {}
 
 export interface ClientsInterface {
   clients: ClientsRegistry;
@@ -29,6 +28,14 @@ export interface ClientsInterface {
   ): InstanceType<AvailableClients[T]>;
 }
 
+/**
+ * Base client class for all Luca network clients. Provides connection state
+ * tracking, configuration, and the registry/factory infrastructure for
+ * creating typed client instances via `container.client('rest')`.
+ *
+ * Subclasses should override `connect()` and add protocol-specific methods.
+ * Register subclasses using `Client.register(this, 'myClient')` in a static block.
+ */
 export class Client<
   T extends ClientState = ClientState,
   K extends ClientOptions = ClientOptions
@@ -81,6 +88,7 @@ export class Client<
     this.state.set("connected", false);
   }
 
+  /** The base URL for this client's connections/requests. */
   get baseURL() {
     return this.options.baseURL || ''
   }
@@ -89,14 +97,17 @@ export class Client<
     return this._options as K;
   }
 
+  /** Configure this client instance with additional options. */
   configure(options?: any): this {
     return this;
   }
 
+  /** Whether the client is currently connected. */
   get isConnected() {
     return !!this.state.get("connected");
   }
 
+  /** Establish a connection. Subclasses should override with protocol-specific logic. */
   async connect(): Promise<this> {
     this.state.set("connected", true);
     return this;
@@ -104,7 +115,7 @@ export class Client<
 }
 
 // --- Registry and Client.register must be defined BEFORE subclasses ---
-// because static blocks in RestClient/GraphClient/WebSocketClient run at class declaration time.
+// because static blocks in subclass files run at class declaration time.
 
 export class ClientsRegistry extends Registry<Client<any>> {
   override scope = "clients"
@@ -156,349 +167,4 @@ Client.register = function registerClient(
   return SubClass
 }
 
-// --- Built-in client subclasses ---
-
-export class RestClient<
-  T extends ClientState = ClientState,
-  K extends ClientOptions = ClientOptions
-> extends Client<T, K> {
-  axios!: AxiosInstance;
-
-  static override shortcut: string = "clients.rest"
-  static { Client.register(this, 'rest') }
-
-  constructor(options: K, context: ContainerContext) {
-    super(options, context);
-
-    this.axios = axios.create({
-      baseURL: this.baseURL,
-    });
-
-    if (this.useJSON) {
-      this.axios.defaults.headers.common = {
-        ...this.axios.defaults.headers.common,
-        "Content-Type": "application/json",
-        Accept: "application/json",
-      }
-    }
-  }
-
-  async beforeRequest() {
-  }
-
-  get useJSON() {
-    return !!this.options.json
-  }
-
-  override get baseURL() {
-    return this.options.baseURL || '/'
-  }
-
-  async patch(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
-    await this.beforeRequest();
-    return this.axios({
-      ...options,
-      method: "PATCH",
-      url,
-      data,
-    })
-      .then((r) => r.data)
-      .catch((e: any) => {
-        if (e.isAxiosError) {
-          return this.handleError(e);
-        } else {
-          throw e;
-        }
-      });
-  }
-
-  async put(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
-    await this.beforeRequest();
-    return this.axios({
-      ...options,
-      method: "PUT",
-      url,
-      data,
-    })
-      .then((r) => r.data)
-      .catch((e: any) => {
-        if (e.isAxiosError) {
-          return this.handleError(e);
-        } else {
-          throw e;
-        }
-      });
-  }
-
-  async post(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
-    await this.beforeRequest();
-    return this.axios({
-      ...options,
-      method: "POST",
-      url,
-      data,
-    })
-      .then((r) => r.data)
-      .catch((e: any) => {
-        if (e.isAxiosError) {
-          return this.handleError(e);
-        } else {
-          throw e;
-        }
-      });
-  }
-
-  async delete(url: string, params: any = {}, options: AxiosRequestConfig = {}) {
-    await this.beforeRequest();
-    return this.axios({
-      ...options,
-      method: "DELETE",
-      url,
-      params,
-    })
-      .then((r) => r.data)
-      .catch((e: any) => {
-        if (e.isAxiosError) {
-          return this.handleError(e);
-        } else {
-          throw e;
-        }
-      });
-  }
-
-
-  async get(url: string, params: any = {}, options: AxiosRequestConfig = {}) {
-    await this.beforeRequest()
-    return this.axios({
-      ...options,
-      method: "GET",
-      url,
-      params,
-    })
-      .then((r) => r.data)
-      .catch((e: any) => {
-        if (e.isAxiosError) {
-          return this.handleError(e);
-        } else {
-          throw e;
-        }
-      });
-  }
-
-  async handleError(error: AxiosError) {
-    this.emit('failure', error)
-    return error.toJSON();
-  }
-}
-
-/**
- * GraphQL client that wraps RestClient with convenience methods for executing
- * queries and mutations. Automatically handles the GraphQL request envelope
- * (query/variables/operationName) and unwraps responses, extracting the `data`
- * field and emitting events for GraphQL-level errors.
- */
-export class GraphClient<
-  T extends ClientState = ClientState,
-  K extends GraphClientOptions = GraphClientOptions
-> extends RestClient<T, K> {
-  static override shortcut = "clients.graph" as const
-  static override optionsSchema = GraphClientOptionsSchema
-  static override eventsSchema = GraphClientEventsSchema
-  static { Client.register(this, 'graph') }
-
-  /** The GraphQL endpoint path. Defaults to '/graphql'. */
-  get endpoint() {
-    return (this.options as GraphClientOptions).endpoint || '/graphql'
-  }
-
-  /**
-   * Execute a GraphQL query and return the unwrapped data.
-   * @param query - The GraphQL query string
-   * @param variables - Optional variables for the query
-   * @param operationName - Optional operation name when the query contains multiple operations
-   */
-  async query<R = any>(query: string, variables?: Record<string, any>, operationName?: string): Promise<R> {
-    return this.execute<R>(query, variables, operationName)
-  }
-
-  /**
-   * Execute a GraphQL mutation and return the unwrapped data.
-   * Semantically identical to query() but named for clarity when performing mutations.
-   * @param mutation - The GraphQL mutation string
-   * @param variables - Optional variables for the mutation
-   * @param operationName - Optional operation name when the mutation contains multiple operations
-   */
-  async mutate<R = any>(mutation: string, variables?: Record<string, any>, operationName?: string): Promise<R> {
-    return this.execute<R>(mutation, variables, operationName)
-  }
-
-  /**
-   * Execute a GraphQL operation, unwrap the response, and handle errors.
-   * Posts to the configured endpoint with the standard GraphQL envelope.
-   * If the response contains GraphQL-level errors, emits both 'graphqlError'
-   * and 'failure' events before returning the data.
-   */
-  private async execute<R = any>(query: string, variables?: Record<string, any>, operationName?: string): Promise<R> {
-    const body: Record<string, any> = { query }
-    if (variables) body.variables = variables
-    if (operationName) body.operationName = operationName
-
-    const response = await this.post(this.endpoint, body)
-
-    if (response?.errors?.length) {
-      this.emit('graphqlError', response.errors)
-      this.emit('failure', response.errors)
-    }
-
-    return response?.data as R
-  }
-}
-
-/**
- * WebSocket client that bridges raw WebSocket events to Luca's Helper event bus,
- * providing a clean interface for sending/receiving messages, tracking connection
- * state, and optional auto-reconnection with exponential backoff.
- *
- * Events emitted:
- * - `open` — connection established
- * - `message` — message received (JSON-parsed when possible)
- * - `close` — connection closed (with code and reason)
- * - `error` — connection error
- * - `reconnecting` — attempting reconnection (with attempt number)
- */
-export class WebSocketClient<
-  T extends WebSocketClientState = WebSocketClientState,
-  K extends WebSocketClientOptions = WebSocketClientOptions
-> extends Client<T, K> {
-  ws!: WebSocket
-  _intentionalClose: boolean
-
-  static override shortcut = "clients.websocket" as const
-  static override stateSchema = WebSocketClientStateSchema
-  static override optionsSchema = WebSocketClientOptionsSchema
-  static override eventsSchema = WebSocketClientEventsSchema
-  static { Client.register(this, 'websocket') }
-
-  constructor(options?: K, context?: ContainerContext) {
-    super(options, context)
-    this._intentionalClose = false
-  }
-
-  override get initialState(): T {
-    return {
-      connected: false,
-      reconnectAttempts: 0,
-    } as T
-  }
-
-  /**
-   * Establish a WebSocket connection to the configured baseURL.
-   * Wires all raw WebSocket events (open, message, close, error) to the
-   * Helper event bus and updates connection state accordingly.
-   * Resolves once the connection is open; rejects on error.
-   */
-  override async connect(): Promise<this> {
-    if (this.isConnected) {
-      return this
-    }
-
-    const ws = this.ws = new WebSocket(this.baseURL)
-    const state = this.state as any
-
-    await new Promise<void>((resolve, reject) => {
-      ws.onopen = () => {
-        state.set('connected', true)
-        state.set('connectionError', undefined)
-        state.set('reconnectAttempts', 0)
-        this.emit('open')
-        resolve()
-      }
-
-      ws.onerror = (event: any) => {
-        state.set('connectionError', event)
-        this.emit('error', event)
-        reject(event)
-      }
-
-      ws.onmessage = (event: any) => {
-        let data = event?.data ?? event
-        try {
-          data = JSON.parse(data)
-        } catch {}
-        this.emit('message', data)
-      }
-
-      ws.onclose = (event: any) => {
-        state.set('connected', false)
-        this.emit('close', event?.code, event?.reason)
-        if (!this._intentionalClose) {
-          this.maybeReconnect()
-        }
-        this._intentionalClose = false
-      }
-    })
-
-    return this
-  }
-
-  /**
-   * Send data over the WebSocket connection. Automatically JSON-serializes
-   * the payload. If not currently connected, attempts to connect first.
-   * @param data - The data to send (will be JSON.stringify'd)
-   */
-  async send(data: any): Promise<void> {
-    if (!this.isConnected) {
-      await this.connect()
-    }
-
-    if (!this.ws) {
-      throw new Error('WebSocket instance not available')
-    }
-
-    this.ws.send(JSON.stringify(data))
-  }
-
-  /**
-   * Gracefully close the WebSocket connection. Suppresses auto-reconnect
-   * and updates connection state to disconnected.
-   */
-  async disconnect(): Promise<this> {
-    this._intentionalClose = true
-    if (this.ws) {
-      this.ws.close()
-    }
-    ;(this.state as any).set('connected', false)
-    return this
-  }
-
-  /** Whether the client is in an error state. */
-  get hasError() {
-    return !!(this.state as any).get('connectionError')
-  }
-
-  /**
-   * Attempt to reconnect if the reconnect option is enabled and we haven't
-   * exceeded maxReconnectAttempts. Uses exponential backoff capped at 30s.
-   */
-  private maybeReconnect() {
-    const opts = this.options as WebSocketClientOptions
-    if (!opts.reconnect) return
-
-    const state = this.state as any
-    const maxAttempts = opts.maxReconnectAttempts ?? Infinity
-    const baseInterval = opts.reconnectInterval ?? 1000
-    const attempts = ((state.get('reconnectAttempts') as number) ?? 0) + 1
-
-    if (attempts > maxAttempts) return
-
-    state.set('reconnectAttempts', attempts)
-    this.emit('reconnecting', attempts)
-
-    const delay = Math.min(baseInterval * Math.pow(2, attempts - 1), 30000)
-    setTimeout(() => {
-      this.connect().catch(() => {})
-    }, delay)
-  }
-}
-
 export default Client;

package/src/clients/civitai/index.ts

@@ -1,8 +1,8 @@
 import {
   Client,
   type ClientOptions,
-  RestClient,
 } from "@soederpop/luca/client";
+import { RestClient } from "../rest";
 import { type ContainerContext } from "@soederpop/luca/container";
 import { isEmpty, maxBy, omitBy } from "lodash-es";
 import { NodeContainer } from "@soederpop/luca/node/container";

package/src/clients/client-template.ts

@@ -2,8 +2,8 @@ import {
   type ClientOptions,
   type ClientsInterface,
   clients,
-  RestClient,
 } from "@soederpop/luca/client";
+import { RestClient } from "./rest";
 import { type ContainerContext } from "@soederpop/luca/container";
 import { z } from 'zod'
 import { ClientStateSchema } from '@soederpop/luca/schemas/base.js'

package/src/clients/comfyui/index.ts

@@ -1,10 +1,10 @@
 import {
   Client,
-  RestClient,
 } from "@soederpop/luca/client";
+import { RestClient } from "../rest";
 import type { ContainerContext } from "@soederpop/luca/container";
 import { z } from 'zod'
-import { ClientStateSchema, ClientOptionsSchema } from '@soederpop/luca/schemas/base.js'
+import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca/schemas/base.js'
 
 declare module "@soederpop/luca/client" {
   interface AvailableClients {
@@ -25,6 +25,16 @@ export const ComfyUIClientOptionsSchema = ClientOptionsSchema.extend({
 export type ComfyUIClientState = z.infer<typeof ComfyUIClientStateSchema>
 export type ComfyUIClientOptions = z.infer<typeof ComfyUIClientOptionsSchema>
 
+export const ComfyUIClientEventsSchema = ClientEventsSchema.extend({
+  execution_start: z.tuple([z.object({ promptId: z.string().describe('The prompt ID that started executing') })]).describe('Emitted when prompt execution begins'),
+  executing: z.tuple([z.object({ node: z.string().describe('The node ID currently executing'), promptId: z.string().describe('The prompt ID') })]).describe('Emitted when a specific node begins executing'),
+  progress: z.tuple([z.object({ node: z.string().describe('The node ID'), value: z.number().describe('Current progress value'), max: z.number().describe('Maximum progress value'), promptId: z.string().describe('The prompt ID') })]).describe('Emitted during node execution with progress updates'),
+  executed: z.tuple([z.object({ node: z.string().describe('The node ID that finished'), output: z.any().describe('The node output data'), promptId: z.string().describe('The prompt ID') })]).describe('Emitted when a node finishes execution'),
+  execution_cached: z.tuple([z.object({ nodes: z.array(z.string()).describe('Array of cached node IDs'), promptId: z.string().describe('The prompt ID') })]).describe('Emitted when nodes are served from cache'),
+  execution_error: z.tuple([z.object({ promptId: z.string().describe('The prompt ID'), exception_message: z.string().optional().describe('Error message') }).passthrough()]).describe('Emitted when prompt execution fails'),
+  execution_complete: z.tuple([z.object({ promptId: z.string().describe('The prompt ID that completed') })]).describe('Emitted when prompt execution finishes successfully'),
+}).describe('ComfyUI client events')
+
 /** Maps a semantic input name to a specific node ID and field */
 export type InputMapping = Record<string, { nodeId: string; field: string }>;
 
@@ -66,6 +76,7 @@ export class ComfyUIClient extends RestClient<ComfyUIClientState, ComfyUIClientO
   static override description = "ComfyUI workflow execution client";
   static override stateSchema = ComfyUIClientStateSchema;
   static override optionsSchema = ComfyUIClientOptionsSchema;
+  static override eventsSchema = ComfyUIClientEventsSchema;
 
   static { Client.register(this, 'comfyui') }
 

package/src/clients/elevenlabs/index.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca/schemas/base.js'
-import { Client, RestClient } from "@soederpop/luca/client";
+import { Client } from "@soederpop/luca/client";
+import { RestClient } from "../rest";
 import type { ContainerContext } from "@soederpop/luca/container";
 import type { AxiosRequestConfig } from 'axios'
 

package/src/clients/graph.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod'
+import { Client } from '../client.js'
+import { RestClient } from './rest.js'
+import type { ClientState } from '../client.js'
+import {
+  GraphClientOptionsSchema, GraphClientEventsSchema,
+} from '../schemas/base.js'
+
+export type GraphClientOptions = z.infer<typeof GraphClientOptionsSchema>
+
+declare module '../client' {
+  interface AvailableClients {
+    graph: typeof GraphClient
+  }
+}
+
+/**
+ * GraphQL client that wraps RestClient with convenience methods for executing
+ * queries and mutations. Automatically handles the GraphQL request envelope
+ * (query/variables/operationName) and unwraps responses, extracting the `data`
+ * field and emitting events for GraphQL-level errors.
+ *
+ * @example
+ * ```typescript
+ * const gql = container.client('graph', { baseURL: 'https://api.example.com' })
+ * const data = await gql.query(`{ users { id name } }`)
+ * await gql.mutate(`mutation($name: String!) { createUser(name: $name) { id } }`, { name: 'Alice' })
+ * ```
+ */
+export class GraphClient<
+  T extends ClientState = ClientState,
+  K extends GraphClientOptions = GraphClientOptions
+> extends RestClient<T, K> {
+  static override shortcut = "clients.graph" as const
+  static override optionsSchema = GraphClientOptionsSchema
+  static override eventsSchema = GraphClientEventsSchema
+  static { Client.register(this, 'graph') }
+
+  /** The GraphQL endpoint path. Defaults to '/graphql'. */
+  get endpoint() {
+    return (this.options as GraphClientOptions).endpoint || '/graphql'
+  }
+
+  /**
+   * Execute a GraphQL query and return the unwrapped data.
+   * @param query - The GraphQL query string
+   * @param variables - Optional variables for the query
+   * @param operationName - Optional operation name when the query contains multiple operations
+   */
+  async query<R = any>(query: string, variables?: Record<string, any>, operationName?: string): Promise<R> {
+    return this.execute<R>(query, variables, operationName)
+  }
+
+  /**
+   * Execute a GraphQL mutation and return the unwrapped data.
+   * Semantically identical to query() but named for clarity when performing mutations.
+   * @param mutation - The GraphQL mutation string
+   * @param variables - Optional variables for the mutation
+   * @param operationName - Optional operation name when the mutation contains multiple operations
+   */
+  async mutate<R = any>(mutation: string, variables?: Record<string, any>, operationName?: string): Promise<R> {
+    return this.execute<R>(mutation, variables, operationName)
+  }
+
+  /**
+   * Execute a GraphQL operation, unwrap the response, and handle errors.
+   * Posts to the configured endpoint with the standard GraphQL envelope.
+   * If the response contains GraphQL-level errors, emits both 'graphqlError'
+   * and 'failure' events before returning the data.
+   */
+  private async execute<R = any>(query: string, variables?: Record<string, any>, operationName?: string): Promise<R> {
+    const body: Record<string, any> = { query }
+    if (variables) body.variables = variables
+    if (operationName) body.operationName = operationName
+
+    const response = await this.post(this.endpoint, body)
+
+    if (response?.errors?.length) {
+      this.emit('graphqlError', response.errors)
+      this.emit('failure', response.errors)
+    }
+
+    return response?.data as R
+  }
+}
+
+export default GraphClient

package/src/clients/openai/index.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { ClientStateSchema, ClientOptionsSchema } from '@soederpop/luca/schemas/base.js'
+import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca/schemas/base.js'
 import { Client } from "@soederpop/luca/client";
 import type { Container, ContainerContext } from "@soederpop/luca/container";
 
@@ -27,6 +27,14 @@ export const OpenAIClientOptionsSchema = ClientOptionsSchema.extend({
 })
 export type OpenAIClientOptions = z.infer<typeof OpenAIClientOptionsSchema>
 
+export const OpenAIClientEventsSchema = ClientEventsSchema.extend({
+  connected: z.tuple([]).describe('Emitted when the API connection is verified'),
+  completion: z.tuple([z.any().describe('The completion or response object')]).describe('Emitted after a chat completion, legacy completion, or response is created'),
+  embedding: z.tuple([z.any().describe('The embedding response object')]).describe('Emitted after embeddings are created'),
+  image: z.tuple([z.any().describe('The image generation response object')]).describe('Emitted after an image is generated'),
+  models: z.tuple([z.any().describe('The models list response')]).describe('Emitted after listing available models'),
+}).describe('OpenAI client events')
+
 /**
  * OpenAI client — wraps the OpenAI SDK for chat completions, responses API, embeddings, and image generation.
  *
@@ -47,6 +55,7 @@ export class OpenAIClient extends Client<OpenAIClientState, OpenAIClientOptions>
   static override envVars = ['OPENAI_API_KEY']
   static override stateSchema = OpenAIClientStateSchema
   static override optionsSchema = OpenAIClientOptionsSchema
+  static override eventsSchema = OpenAIClientEventsSchema
 
   static { Client.register(this, 'openai') }