@soederpop/luca 0.0.6 → 0.0.8

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') }
 

package/src/clients/rest.ts

@@ -0,0 +1,207 @@
+import axios, { type AxiosError, type AxiosInstance, type AxiosRequestConfig } from "axios";
+import { Client, type ClientOptions, type ClientState } from '../client.js'
+import type { ContainerContext } from '../container.js'
+import { ClientEventsSchema } from '../schemas/base.js'
+import { z } from 'zod'
+
+export const RestClientEventsSchema = ClientEventsSchema.extend({}).describe('REST client events')
+
+declare module '../client' {
+  interface AvailableClients {
+    rest: typeof RestClient
+  }
+}
+
+/**
+ * HTTP REST client built on top of axios. Provides convenience methods for
+ * GET, POST, PUT, PATCH, and DELETE requests with automatic JSON handling,
+ * configurable base URL, and error event emission.
+ *
+ * @example
+ * ```typescript
+ * const api = container.client('rest', { baseURL: 'https://api.example.com', json: true })
+ * const users = await api.get('/users')
+ * await api.post('/users', { name: 'Alice' })
+ * ```
+ */
+export class RestClient<
+  T extends ClientState = ClientState,
+  K extends ClientOptions = ClientOptions
+> extends Client<T, K> {
+  axios!: AxiosInstance;
+
+  static override shortcut: string = "clients.rest"
+  static override eventsSchema = RestClientEventsSchema
+  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() {
+  }
+
+  /** Whether JSON content-type headers should be set automatically. */
+  get useJSON() {
+    return !!this.options.json
+  }
+
+  override get baseURL() {
+    return this.options.baseURL || '/'
+  }
+
+  /**
+   * Send a PATCH request. Returns the parsed response body directly (not an
+   * axios Response wrapper). On HTTP errors, returns the error as JSON instead
+   * of throwing.
+   * @param url - Request path relative to baseURL
+   * @param data - Request body
+   * @param options - Additional axios request config
+   * @returns Parsed response body
+   */
+  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;
+        }
+      });
+  }
+
+  /**
+   * Send a PUT request. Returns the parsed response body directly (not an
+   * axios Response wrapper). On HTTP errors, returns the error as JSON instead
+   * of throwing.
+   * @param url - Request path relative to baseURL
+   * @param data - Request body
+   * @param options - Additional axios request config
+   * @returns Parsed response body
+   */
+  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;
+        }
+      });
+  }
+
+  /**
+   * Send a POST request. Returns the parsed response body directly (not an
+   * axios Response wrapper). On HTTP errors, returns the error as JSON instead
+   * of throwing.
+   * @param url - Request path relative to baseURL
+   * @param data - Request body
+   * @param options - Additional axios request config
+   * @returns Parsed response body
+   */
+  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;
+        }
+      });
+  }
+
+  /**
+   * Send a DELETE request. Returns the parsed response body directly (not an
+   * axios Response wrapper). On HTTP errors, returns the error as JSON instead
+   * of throwing.
+   * @param url - Request path relative to baseURL
+   * @param params - Query parameters
+   * @param options - Additional axios request config
+   * @returns Parsed response body
+   */
+  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;
+        }
+      });
+  }
+
+  /**
+   * Send a GET request. Returns the parsed response body directly (not an
+   * axios Response wrapper). On HTTP errors, returns the error as JSON instead
+   * of throwing.
+   * @param url - Request path relative to baseURL
+   * @param params - Query parameters
+   * @param options - Additional axios request config
+   * @returns Parsed response body
+   */
+  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;
+        }
+      });
+  }
+
+  /** Handle an axios error by emitting 'failure' and returning the error as JSON. */
+  async handleError(error: AxiosError) {
+    this.emit('failure', error)
+    return error.toJSON();
+  }
+}
+
+export default RestClient

package/src/clients/websocket.ts

@@ -0,0 +1,176 @@
+import { z } from 'zod'
+import { Client } from '../client.js'
+import type { ContainerContext } from '../container.js'
+import {
+  WebSocketClientStateSchema, WebSocketClientOptionsSchema, WebSocketClientEventsSchema,
+} from '../schemas/base.js'
+
+export type WebSocketClientState = z.infer<typeof WebSocketClientStateSchema>
+export type WebSocketClientOptions = z.infer<typeof WebSocketClientOptionsSchema>
+
+declare module '../client' {
+  interface AvailableClients {
+    websocket: typeof WebSocketClient
+  }
+}
+
+/**
+ * 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)
+ *
+ * @example
+ * ```typescript
+ * const ws = container.client('websocket', {
+ *   baseURL: 'ws://localhost:8080',
+ *   reconnect: true,
+ *   maxReconnectAttempts: 5
+ * })
+ * ws.on('message', (data) => console.log('Received:', data))
+ * await ws.connect()
+ * await ws.send({ type: 'hello' })
+ * ```
+ */
+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 WebSocketClient