@soederpop/luca 0.0.5 → 0.0.7

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