luca 2.0.0 → 3.0.0

package/src/clients/supabase/index.ts

@@ -0,0 +1,357 @@
+import {
+  Client,
+} from "@soederpop/luca/client";
+import type { ContainerContext } from "@soederpop/luca/container";
+import { z } from "zod";
+import {
+  ClientStateSchema,
+  ClientOptionsSchema,
+  ClientEventsSchema,
+} from "@soederpop/luca/schemas/base.js";
+import {
+  createClient,
+  type SupabaseClient as SupabaseSDKClient,
+  type SupabaseClientOptions as SupabaseSDKOptions,
+  type RealtimeChannel,
+} from "@supabase/supabase-js";
+
+declare module "@soederpop/luca/client" {
+  interface AvailableClients {
+    supabase: typeof SupabaseClient;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+export const SupabaseClientOptionsSchema = ClientOptionsSchema.extend({
+  supabaseUrl: z
+    .string()
+    .describe("The Supabase project URL (e.g. https://xyz.supabase.co)"),
+  supabaseKey: z
+    .string()
+    .describe("The Supabase anon or service-role key"),
+  clientOptions: z
+    .record(z.string(), z.any())
+    .optional()
+    .describe(
+      "Pass-through options forwarded directly to the Supabase SDK createClient()"
+    ),
+}).describe("Options for creating a Supabase client");
+
+export const SupabaseClientStateSchema = ClientStateSchema.extend({
+  authenticated: z
+    .boolean()
+    .default(false)
+    .describe("Whether a user session is currently active"),
+  userId: z
+    .string()
+    .nullable()
+    .default(null)
+    .describe("The authenticated user's ID, if any"),
+  userEmail: z
+    .string()
+    .nullable()
+    .default(null)
+    .describe("The authenticated user's email, if any"),
+  realtimeChannels: z
+    .array(z.string())
+    .default([])
+    .describe("Names of currently subscribed realtime channels"),
+  lastError: z
+    .string()
+    .nullable()
+    .default(null)
+    .describe("The most recent error message, if any"),
+}).describe("Supabase client state");
+
+export const SupabaseClientEventsSchema = ClientEventsSchema.extend({
+  authStateChange: z
+    .tuple([
+      z.string().describe("The auth event name (e.g. SIGNED_IN, SIGNED_OUT)"),
+      z.any().describe("The session object"),
+    ])
+    .describe("Emitted when the auth state changes"),
+  realtimeMessage: z
+    .tuple([
+      z.string().describe("The channel name"),
+      z.any().describe("The payload"),
+    ])
+    .describe("Emitted when a realtime message is received"),
+  realtimeStatus: z
+    .tuple([
+      z.string().describe("The channel name"),
+      z.string().describe("The status (e.g. SUBSCRIBED, CLOSED)"),
+    ])
+    .describe("Emitted when a realtime channel status changes"),
+  error: z
+    .tuple([z.any().describe("The error object")])
+    .describe("Emitted on any Supabase error"),
+}).describe("Supabase client events");
+
+export type SupabaseClientOptions = z.infer<typeof SupabaseClientOptionsSchema>;
+export type SupabaseClientState = z.infer<typeof SupabaseClientStateSchema>;
+
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+
+/**
+ * Supabase client for the Luca container system.
+ *
+ * Wraps the official `@supabase/supabase-js` SDK and exposes it through Luca's
+ * typed state, events, and introspection system. The SDK is isomorphic so this
+ * single implementation works in both Node and browser containers.
+ *
+ * Use `client.sdk` for full SDK access, or use the convenience wrappers for
+ * common operations (auth, database queries, storage, edge functions, realtime).
+ *
+ * @example
+ * ```typescript
+ * const supabase = container.client('supabase', {
+ *   supabaseUrl: 'https://xyz.supabase.co',
+ *   supabaseKey: 'your-anon-key',
+ * })
+ *
+ * // Query data
+ * const { data } = await supabase.from('users').select('*')
+ *
+ * // Auth
+ * await supabase.signInWithPassword('user@example.com', 'password')
+ *
+ * // Realtime
+ * supabase.subscribe('changes', 'users', (payload) => {
+ *   console.log('Change:', payload)
+ * })
+ * ```
+ */
+export class SupabaseClient extends Client<
+  SupabaseClientState,
+  SupabaseClientOptions
+> {
+  static override shortcut = "clients.supabase" as const;
+  static override description =
+    "Supabase client wrapping the official SDK with typed state, events, and realtime channel management";
+
+  static override stateSchema = SupabaseClientStateSchema;
+  static override optionsSchema = SupabaseClientOptionsSchema;
+  static override eventsSchema = SupabaseClientEventsSchema;
+
+  static { Client.register(this, 'supabase') }
+
+  private _sdk!: SupabaseSDKClient<any, any>;
+  private _channels = new Map<string, RealtimeChannel>();
+
+  constructor(options: SupabaseClientOptions, context: ContainerContext) {
+    super(options, context);
+
+    const sdkOptions = (options.clientOptions ?? {}) as SupabaseSDKOptions<string>;
+    this._sdk = createClient(options.supabaseUrl, options.supabaseKey, sdkOptions);
+
+    this._sdk.auth.onAuthStateChange((event, session) => {
+      const user = session?.user;
+      this.state.set("authenticated", !!session);
+      this.state.set("userId", user?.id ?? null);
+      this.state.set("userEmail", user?.email ?? null);
+      this.emit("authStateChange" as any, event, session);
+    });
+
+    this.state.set("connected", true);
+  }
+
+  // ---------------------------------------------------------------------------
+  // SDK access
+  // ---------------------------------------------------------------------------
+
+  /** Returns the raw Supabase SDK client for full access to all SDK methods. */
+  get sdk(): SupabaseSDKClient<any, any> {
+    return this._sdk;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Database
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Start a query on a Postgres table or view.
+   * @param table - The table or view name to query
+   */
+  from(table: string) {
+    return this._sdk.from(table);
+  }
+
+  /**
+   * Call a Postgres function (RPC).
+   * @param fn - The function name
+   * @param params - Arguments to pass to the function
+   * @param options - Optional settings (head, get, count)
+   */
+  rpc(fn: string, params?: Record<string, unknown>, options?: { head?: boolean; get?: boolean; count?: "exact" | "planned" | "estimated" }) {
+    return this._sdk.rpc(fn, params, options);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Auth
+  // ---------------------------------------------------------------------------
+
+  /** Sign in with email and password. */
+  async signInWithPassword(email: string, password: string) {
+    const result = await this._sdk.auth.signInWithPassword({ email, password });
+    if (result.error) {
+      this._setError(result.error.message);
+    }
+    return result;
+  }
+
+  /** Create a new user account with email and password. */
+  async signUp(email: string, password: string) {
+    const result = await this._sdk.auth.signUp({ email, password });
+    if (result.error) {
+      this._setError(result.error.message);
+    }
+    return result;
+  }
+
+  /** Sign the current user out. */
+  async signOut() {
+    const result = await this._sdk.auth.signOut();
+    if (result.error) {
+      this._setError(result.error.message);
+    }
+    return result;
+  }
+
+  /** Get the current session, if any. */
+  async getSession() {
+    return this._sdk.auth.getSession();
+  }
+
+  /** Get the current user, if any. */
+  async getUser() {
+    return this._sdk.auth.getUser();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Storage
+  // ---------------------------------------------------------------------------
+
+  /** Returns the Supabase Storage client for managing buckets and files. */
+  get storage() {
+    return this._sdk.storage;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Edge Functions
+  // ---------------------------------------------------------------------------
+
+  /** Returns the Supabase Functions client. */
+  get functions() {
+    return this._sdk.functions;
+  }
+
+  /** Invoke a Supabase Edge Function by name. */
+  async invoke(name: string, body?: any) {
+    const result = await this._sdk.functions.invoke(name, { body });
+    if (result.error) {
+      this._setError(result.error.message);
+    }
+    return result;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Realtime
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Subscribe to realtime changes on a Postgres table.
+   * @param channelName - A name for this subscription channel
+   * @param table - The table to listen to
+   * @param callback - Called with the payload on each change
+   * @param event - The event type to listen for (default: all changes)
+   */
+  subscribe(
+    channelName: string,
+    table: string,
+    callback: (payload: any) => void,
+    event: "INSERT" | "UPDATE" | "DELETE" | "*" = "*"
+  ): RealtimeChannel {
+    const channel = this._sdk
+      .channel(channelName)
+      .on(
+        "postgres_changes" as any,
+        { event, schema: "public", table },
+        (payload: any) => {
+          this.emit("realtimeMessage" as any, channelName, payload);
+          callback(payload);
+        }
+      )
+      .subscribe((status: string) => {
+        this.emit("realtimeStatus" as any, channelName, status);
+      });
+
+    this._channels.set(channelName, channel);
+    this._syncChannelState();
+    return channel;
+  }
+
+  /**
+   * Unsubscribe and remove a realtime channel by name.
+   * @param channelName - The channel name to remove
+   */
+  async unsubscribe(channelName: string) {
+    const channel = this._channels.get(channelName);
+    if (channel) {
+      await this._sdk.removeChannel(channel);
+      this._channels.delete(channelName);
+      this._syncChannelState();
+    }
+  }
+
+  /** Unsubscribe and remove all realtime channels. */
+  async unsubscribeAll() {
+    await this._sdk.removeAllChannels();
+    this._channels.clear();
+    this._syncChannelState();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Connect is a no-op since the Supabase SDK initializes on construction.
+   * The client is ready to use immediately after creation.
+   */
+  override async connect() {
+    this.state.set("connected", true);
+    return this;
+  }
+
+  /**
+   * Disconnect by signing out and removing all realtime channels.
+   */
+  async disconnect() {
+    await this.unsubscribeAll();
+    await this._sdk.auth.signOut();
+    this.state.set("connected", false);
+    this.state.set("authenticated", false);
+    this.state.set("userId", null);
+    this.state.set("userEmail", null);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private _syncChannelState() {
+    this.state.set("realtimeChannels", Array.from(this._channels.keys()));
+  }
+
+  private _setError(message: string) {
+    this.state.set("lastError", message);
+    this.emit("error" as any, new Error(message));
+  }
+}
+
+export default SupabaseClient;

package/src/clients/voicebox/index.ts

@@ -0,0 +1,300 @@
+import { z } from 'zod'
+import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca/schemas/base.js'
+import { Client } from "@soederpop/luca/client";
+import { RestClient } from "../rest";
+import type { ContainerContext } from "@soederpop/luca/container";
+import type { NodeContainer } from "../../node/container.js";
+
+declare module "@soederpop/luca/client" {
+  interface AvailableClients {
+    voicebox: typeof VoiceBoxClient;
+  }
+}
+
+export const VoiceBoxClientOptionsSchema = ClientOptionsSchema.extend({
+  baseURL: z.string().optional().describe('VoiceBox server URL (falls back to VOICEBOX_URL env var, default http://127.0.0.1:17493)'),
+  defaultProfileId: z.string().optional().describe('Default voice profile ID for synthesis'),
+  defaultEngine: z.string().optional().default('qwen').describe('Default TTS engine (qwen, luxtts, chatterbox, chatterbox_turbo)'),
+  defaultModelSize: z.string().optional().default('1.7B').describe('Default model size (1.7B or 0.6B)'),
+  defaultLanguage: z.string().optional().default('en').describe('Default language code'),
+})
+export type VoiceBoxClientOptions = z.infer<typeof VoiceBoxClientOptionsSchema>
+
+export const VoiceBoxClientStateSchema = ClientStateSchema.extend({
+  requestCount: z.number().default(0).describe('Total number of API requests made'),
+  characterCount: z.number().default(0).describe('Total characters sent for synthesis'),
+  lastRequestTime: z.number().nullable().default(null).describe('Timestamp of the last API request'),
+})
+export type VoiceBoxClientState = z.infer<typeof VoiceBoxClientStateSchema>
+
+export const VoiceBoxClientEventsSchema = ClientEventsSchema.extend({
+  speech: z.tuple([z.object({
+    profileId: z.string(),
+    text: z.string(),
+    audioSize: z.number(),
+  })]).describe('Emitted after speech synthesis completes'),
+  profiles: z.tuple([z.array(z.any())]).describe('Emitted after listing profiles'),
+})
+
+export type EffectConfig = {
+  type: string
+  enabled?: boolean
+  params?: Record<string, any>
+}
+
+export type SynthesizeOptions = {
+  profileId?: string
+  engine?: string
+  modelSize?: string
+  language?: string
+  instruct?: string
+  seed?: number
+  maxChunkChars?: number
+  crossfadeMs?: number
+  normalize?: boolean
+  effectsChain?: EffectConfig[]
+  disableCache?: boolean
+}
+
+/**
+ * VoiceBox client — local TTS synthesis via VoiceBox.sh REST API (Qwen3-TTS).
+ *
+ * Provides methods for managing voice profiles and generating speech audio locally.
+ * Uses the streaming endpoint for synchronous synthesis (returns WAV buffer).
+ *
+ * @example
+ * ```typescript
+ * const vb = container.client('voicebox')
+ * await vb.connect()
+ * const profiles = await vb.listProfiles()
+ * const audio = await vb.synthesize('Hello world', { profileId: profiles[0].id })
+ * // audio is a Buffer of WAV data
+ * ```
+ */
+export class VoiceBoxClient extends RestClient<VoiceBoxClientState, VoiceBoxClientOptions> {
+  static override shortcut = "clients.voicebox" as const
+  static override envVars = ['VOICEBOX_URL']
+  static override stateSchema = VoiceBoxClientStateSchema
+  static override optionsSchema = VoiceBoxClientOptionsSchema
+  static override eventsSchema = VoiceBoxClientEventsSchema
+
+  static { Client.register(this, 'voicebox') }
+
+  override get initialState(): VoiceBoxClientState {
+    return {
+      ...super.initialState,
+      requestCount: 0,
+      characterCount: 0,
+      lastRequestTime: null,
+    }
+  }
+
+  constructor(options: VoiceBoxClientOptions, context: ContainerContext) {
+    options = {
+      ...options,
+      baseURL: options.baseURL || process.env.VOICEBOX_URL || 'http://127.0.0.1:17493',
+    }
+    super(options, context)
+  }
+
+  override get container(): NodeContainer {
+    return super.container as unknown as NodeContainer
+  }
+
+  private trackRequest(characters = 0) {
+    const requestCount = this.state.get('requestCount') || 0
+    const characterCount = this.state.get('characterCount') || 0
+    this.setState({
+      requestCount: requestCount + 1,
+      characterCount: characterCount + characters,
+      lastRequestTime: Date.now(),
+    })
+  }
+
+  /**
+   * Validate the VoiceBox server is reachable by hitting the health endpoint.
+   */
+  override async connect(): Promise<this> {
+    try {
+      const health = await this.get('/health')
+      if (health?.status !== 'ok' && health?.status !== 'healthy') {
+        // Accept any 200 response as healthy
+      }
+      await super.connect()
+      this.emit('connected' as any)
+      return this
+    } catch (error) {
+      this.emit('failure', error)
+      throw error
+    }
+  }
+
+  /**
+   * List all voice profiles.
+   *
+   * @returns Array of voice profile objects
+   *
+   * @example
+   * ```typescript
+   * const profiles = await vb.listProfiles()
+   * console.log(profiles.map(p => `${p.name} (${p.sample_count} samples)`))
+   * ```
+   */
+  async listProfiles(): Promise<any[]> {
+    this.trackRequest()
+    const result = await this.get('/profiles')
+    const profiles = Array.isArray(result) ? result : []
+    this.emit('profiles', profiles)
+    return profiles
+  }
+
+  /**
+   * Get a single voice profile by ID.
+   */
+  async getProfile(profileId: string): Promise<any> {
+    this.trackRequest()
+    return this.get(`/profiles/${profileId}`)
+  }
+
+  /**
+   * Create a new voice profile.
+   */
+  async createProfile(name: string, options: { description?: string; language?: string } = {}): Promise<any> {
+    this.trackRequest()
+    return this.post('/profiles', { name, ...options })
+  }
+
+  /**
+   * List available audio effects and their parameter definitions.
+   */
+  async listEffects(): Promise<any> {
+    this.trackRequest()
+    return this.get('/effects/available')
+  }
+
+  /**
+   * Synthesize speech from text using the streaming endpoint.
+   * Returns audio as a WAV Buffer (synchronous — blocks until audio is ready).
+   *
+   * @param text - The text to convert to speech
+   * @param options - Profile, engine, model, and other synthesis options
+   * @returns Audio data as a WAV Buffer
+   *
+   * @example
+   * ```typescript
+   * const audio = await vb.synthesize('Hello world', { profileId: 'abc-123' })
+   * // audio is a Buffer of WAV data
+   * ```
+   */
+  async synthesize(text: string, options: SynthesizeOptions = {}): Promise<Buffer> {
+    const profileId = options.profileId || this.options.defaultProfileId
+    if (!profileId) throw new Error('profileId is required for VoiceBox synthesis')
+
+    const engine = options.engine || this.options.defaultEngine || 'qwen'
+    const modelSize = options.modelSize || this.options.defaultModelSize || '1.7B'
+    const language = options.language || this.options.defaultLanguage || 'en'
+
+    const body: Record<string, any> = {
+      profile_id: profileId,
+      text,
+      language,
+      engine,
+      model_size: modelSize,
+    }
+
+    if (options.instruct) body.instruct = options.instruct
+    if (options.seed != null) body.seed = options.seed
+    if (options.maxChunkChars != null) body.max_chunk_chars = options.maxChunkChars
+    if (options.crossfadeMs != null) body.crossfade_ms = options.crossfadeMs
+    if (options.normalize != null) body.normalize = options.normalize
+    if (options.effectsChain) body.effects_chain = options.effectsChain
+
+    // Check disk cache
+    if (!options.disableCache) {
+      const { hashObject } = this.container.utils
+      const cacheKey = `voicebox:${hashObject({ text, profileId, engine, modelSize, language, instruct: options.instruct })}`
+      const diskCache = this.container.feature('diskCache')
+
+      if (await diskCache.has(cacheKey)) {
+        const cached = await diskCache.get(cacheKey)
+        const audioBuffer = Buffer.from(cached, 'base64')
+        this.emit('speech', { profileId, text, audioSize: audioBuffer.length })
+        return audioBuffer
+      }
+
+      const audioBuffer = await this.fetchStreamAudio(body, text.length)
+      await diskCache.set(cacheKey, audioBuffer.toString('base64'))
+      this.emit('speech', { profileId, text, audioSize: audioBuffer.length })
+      return audioBuffer
+    }
+
+    const audioBuffer = await this.fetchStreamAudio(body, text.length)
+    this.emit('speech', { profileId, text, audioSize: audioBuffer.length })
+    return audioBuffer
+  }
+
+  /**
+   * Generate speech asynchronously (returns metadata, not audio).
+   * Use getAudio() to fetch the audio after generation completes.
+   */
+  async generate(text: string, options: SynthesizeOptions = {}): Promise<any> {
+    const profileId = options.profileId || this.options.defaultProfileId
+    if (!profileId) throw new Error('profileId is required for VoiceBox generation')
+
+    const body: Record<string, any> = {
+      profile_id: profileId,
+      text,
+      language: options.language || this.options.defaultLanguage || 'en',
+      engine: options.engine || this.options.defaultEngine || 'qwen',
+      model_size: options.modelSize || this.options.defaultModelSize || '1.7B',
+    }
+
+    if (options.instruct) body.instruct = options.instruct
+    if (options.seed != null) body.seed = options.seed
+    if (options.effectsChain) body.effects_chain = options.effectsChain
+
+    this.trackRequest(text.length)
+    return this.post('/generate', body)
+  }
+
+  /**
+   * Fetch generated audio by generation ID. Returns WAV Buffer.
+   */
+  async getAudio(generationId: string): Promise<Buffer> {
+    this.trackRequest()
+    const response = await this.axios({
+      method: 'GET',
+      url: `/audio/${generationId}`,
+      responseType: 'arraybuffer',
+      headers: { Accept: 'audio/wav' },
+    })
+    return Buffer.from(response.data)
+  }
+
+  /**
+   * Synthesize and write audio to a file.
+   */
+  async say(text: string, outputPath: string, options: SynthesizeOptions = {}): Promise<string> {
+    const audio = await this.synthesize(text, options)
+    const resolvedPath = this.container.paths.resolve(outputPath)
+    await this.container.fs.writeFileAsync(resolvedPath, audio)
+    return resolvedPath
+  }
+
+  private async fetchStreamAudio(body: Record<string, any>, charCount: number): Promise<Buffer> {
+    this.trackRequest(charCount)
+    const response = await this.axios({
+      method: 'POST',
+      url: '/generate/stream',
+      data: body,
+      responseType: 'arraybuffer',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'audio/wav',
+      },
+    })
+    return Buffer.from(response.data)
+  }
+}
+
+export default VoiceBoxClient