@soederpop/luca 0.1.1 → 0.1.3

package/dist/clients/openai/index.d.ts

@@ -0,0 +1,247 @@
+import { z } from 'zod';
+import { Client } from "@soederpop/luca/client";
+import type { ContainerContext } from "@soederpop/luca/container";
+import OpenAI from "openai";
+export declare const OpenAIClientStateSchema: z.ZodObject<{
+    connected: z.ZodDefault<z.ZodBoolean>;
+    requestCount: z.ZodDefault<z.ZodNumber>;
+    lastRequestTime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    tokenUsage: z.ZodDefault<z.ZodObject<{
+        prompt: z.ZodDefault<z.ZodNumber>;
+        completion: z.ZodDefault<z.ZodNumber>;
+        total: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export type OpenAIClientState = z.infer<typeof OpenAIClientStateSchema>;
+export declare const OpenAIClientOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    baseURL: z.ZodOptional<z.ZodString>;
+    json: z.ZodOptional<z.ZodBoolean>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    organization: z.ZodOptional<z.ZodString>;
+    project: z.ZodOptional<z.ZodString>;
+    dangerouslyAllowBrowser: z.ZodOptional<z.ZodBoolean>;
+    defaultModel: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    maxRetries: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type OpenAIClientOptions = z.infer<typeof OpenAIClientOptionsSchema>;
+export declare const OpenAIClientEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    failure: z.ZodTuple<[z.ZodAny], null>;
+    connected: z.ZodTuple<[], null>;
+    completion: z.ZodTuple<[z.ZodAny], null>;
+    embedding: z.ZodTuple<[z.ZodAny], null>;
+    image: z.ZodTuple<[z.ZodAny], null>;
+    models: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+/**
+ * OpenAI client — wraps the OpenAI SDK for chat completions, responses API, embeddings, and image generation.
+ *
+ * Provides convenience methods for common operations while tracking token usage and request counts.
+ * Supports both the Chat Completions API and the newer Responses API.
+ *
+ * @example
+ * ```typescript
+ * const openai = container.client('openai', { defaultModel: 'gpt-4o' })
+ * const answer = await openai.ask('What is the meaning of life?')
+ * console.log(answer)
+ * ```
+ */
+export declare class OpenAIClient extends Client<OpenAIClientState, OpenAIClientOptions> {
+    private openai;
+    static shortcut: "clients.openai";
+    static envVars: string[];
+    static stateSchema: z.ZodObject<{
+        connected: z.ZodDefault<z.ZodBoolean>;
+        requestCount: z.ZodDefault<z.ZodNumber>;
+        lastRequestTime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        tokenUsage: z.ZodDefault<z.ZodObject<{
+            prompt: z.ZodDefault<z.ZodNumber>;
+            completion: z.ZodDefault<z.ZodNumber>;
+            total: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        json: z.ZodOptional<z.ZodBoolean>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        organization: z.ZodOptional<z.ZodString>;
+        project: z.ZodOptional<z.ZodString>;
+        dangerouslyAllowBrowser: z.ZodOptional<z.ZodBoolean>;
+        defaultModel: z.ZodOptional<z.ZodString>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+        maxRetries: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        failure: z.ZodTuple<[z.ZodAny], null>;
+        connected: z.ZodTuple<[], null>;
+        completion: z.ZodTuple<[z.ZodAny], null>;
+        embedding: z.ZodTuple<[z.ZodAny], null>;
+        image: z.ZodTuple<[z.ZodAny], null>;
+        models: z.ZodTuple<[z.ZodAny], null>;
+    }, z.core.$strip>;
+    /** Initial state with zeroed token usage counters. */
+    get initialState(): OpenAIClientState;
+    constructor(options: OpenAIClientOptions, context: ContainerContext);
+    private initializeOpenAI;
+    /**
+     * Test the API connection by listing models.
+     *
+     * @returns This client instance
+     * @throws If the API key is invalid or the connection fails
+     *
+     * @example
+     * ```typescript
+     * await openai.connect()
+     * ```
+     */
+    connect(): Promise<this>;
+    /** The default model used for completions, from options or 'gpt-4o'. */
+    get defaultModel(): string;
+    private updateTokenUsage;
+    private updateResponsesTokenUsage;
+    private trackRequest;
+    /**
+     * Create a chat completion using the Chat Completions API.
+     *
+     * @param messages - Array of chat messages
+     * @param options - Additional parameters for the completion
+     * @returns The complete chat completion response
+     *
+     * @example
+     * ```typescript
+     * const response = await openai.createChatCompletion([
+     *   { role: 'system', content: 'You are a helpful assistant.' },
+     *   { role: 'user', content: 'Hello!' }
+     * ])
+     * console.log(response.choices[0]?.message?.content)
+     * ```
+     */
+    createChatCompletion(messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], options?: Partial<OpenAI.Chat.Completions.ChatCompletionCreateParams>): Promise<OpenAI.Chat.Completions.ChatCompletion>;
+    /**
+     * Create a response using the Responses API.
+     *
+     * @param input - The input prompt or message array
+     * @param options - Additional parameters for the response
+     * @returns The complete response object
+     *
+     * @example
+     * ```typescript
+     * const response = await openai.createResponse('Explain quantum computing')
+     * ```
+     */
+    createResponse(input: OpenAI.Responses.ResponseInput | string, options?: Partial<OpenAI.Responses.ResponseCreateParamsNonStreaming>): Promise<OpenAI.Responses.Response>;
+    /**
+     * Stream a response using the Responses API.
+     *
+     * @param input - The input prompt or message array
+     * @param options - Additional parameters for the streaming response
+     * @returns An async iterable of response stream events
+     *
+     * @example
+     * ```typescript
+     * const stream = await openai.streamResponse('Write a poem')
+     * for await (const event of stream) {
+     *   if (event.type === 'response.output_text.delta') {
+     *     process.stdout.write(event.delta)
+     *   }
+     * }
+     * ```
+     */
+    streamResponse(input: OpenAI.Responses.ResponseInput | string, options?: Partial<OpenAI.Responses.ResponseCreateParamsStreaming>): Promise<AsyncIterable<OpenAI.Responses.ResponseStreamEvent>>;
+    /**
+     * Create a legacy text completion.
+     *
+     * @param prompt - The text prompt to complete
+     * @param options - Additional parameters for the completion
+     * @returns The complete completion response
+     *
+     * @example
+     * ```typescript
+     * const response = await openai.createCompletion('Once upon a time')
+     * ```
+     */
+    createCompletion(prompt: string, options?: Partial<OpenAI.Completions.CompletionCreateParams>): Promise<OpenAI.Completions.Completion>;
+    /**
+     * Create text embeddings for semantic search or similarity comparisons.
+     *
+     * @param input - A string or array of strings to embed
+     * @param options - Additional parameters (model, etc.)
+     * @returns The embedding response with vectors
+     *
+     * @example
+     * ```typescript
+     * const response = await openai.createEmbedding('Hello world')
+     * console.log(response.data[0].embedding.length)
+     * ```
+     */
+    createEmbedding(input: string | string[], options?: Partial<OpenAI.Embeddings.EmbeddingCreateParams>): Promise<OpenAI.Embeddings.CreateEmbeddingResponse>;
+    /**
+     * Generate an image from a text prompt using DALL-E.
+     *
+     * @param prompt - Description of the image to generate
+     * @param options - Additional parameters (size, n, etc.)
+     * @returns The image response with URLs or base64 data
+     *
+     * @example
+     * ```typescript
+     * const response = await openai.createImage('A sunset over mountains')
+     * console.log(response.data[0].url)
+     * ```
+     */
+    createImage(prompt: string, options?: Partial<OpenAI.Images.ImageGenerateParams>): Promise<OpenAI.Images.ImagesResponse>;
+    /**
+     * List all available models.
+     *
+     * @returns Paginated list of available models
+     *
+     * @example
+     * ```typescript
+     * const models = await openai.listModels()
+     * ```
+     */
+    listModels(): Promise<OpenAI.Models.ModelsPage>;
+    /**
+     * Ask a single question and get a text response.
+     *
+     * Convenience wrapper around `createChatCompletion` for simple Q&A.
+     *
+     * @param question - The question to ask
+     * @param options - Additional completion parameters
+     * @returns The assistant's text response
+     *
+     * @example
+     * ```typescript
+     * const answer = await openai.ask('What is 2 + 2?')
+     * console.log(answer) // '4'
+     * ```
+     */
+    ask(question: string, options?: Partial<OpenAI.Chat.Completions.ChatCompletionCreateParams>): Promise<string>;
+    /**
+     * Send a multi-turn conversation and get a text response.
+     *
+     * Convenience wrapper around `createChatCompletion` that returns just the text.
+     *
+     * @param messages - Array of chat messages
+     * @param options - Additional completion parameters
+     * @returns The assistant's text response
+     *
+     * @example
+     * ```typescript
+     * const reply = await openai.chat([
+     *   { role: 'system', content: 'You are a pirate.' },
+     *   { role: 'user', content: 'Hello!' }
+     * ])
+     * ```
+     */
+    chat(messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], options?: Partial<OpenAI.Chat.Completions.ChatCompletionCreateParams>): Promise<string>;
+    /** The underlying OpenAI SDK instance for advanced use cases. */
+    get raw(): OpenAI;
+}
+export default OpenAIClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/clients/openai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/clients/openai/index.ts"],"names":[],"mappings":"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"}

package/dist/clients/rest.d.ts

@@ -0,0 +1,92 @@
+import { type AxiosError, type AxiosInstance, type AxiosRequestConfig } from "axios";
+import { Client, type ClientOptions, type ClientState } from '../client.js';
+import type { ContainerContext } from '../container.js';
+import { z } from 'zod';
+export declare const RestClientEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    failure: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+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 declare class RestClient<T extends ClientState = ClientState, K extends ClientOptions = ClientOptions> extends Client<T, K> {
+    axios: AxiosInstance;
+    static shortcut: string;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        failure: z.ZodTuple<[z.ZodAny], null>;
+    }, z.core.$strip>;
+    constructor(options: K, context: ContainerContext);
+    beforeRequest(): Promise<void>;
+    /** Whether JSON content-type headers should be set automatically. */
+    get useJSON(): boolean;
+    get baseURL(): string;
+    /**
+     * 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
+     */
+    patch(url: string, data?: any, options?: AxiosRequestConfig): Promise<any>;
+    /**
+     * 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
+     */
+    put(url: string, data?: any, options?: AxiosRequestConfig): Promise<any>;
+    /**
+     * 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
+     */
+    post(url: string, data?: any, options?: AxiosRequestConfig): Promise<any>;
+    /**
+     * 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
+     */
+    delete(url: string, params?: any, options?: AxiosRequestConfig): Promise<any>;
+    /**
+     * 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
+     */
+    get(url: string, params?: any, options?: AxiosRequestConfig): Promise<any>;
+    /** Handle an axios error by emitting 'failure' and returning the error as JSON. */
+    handleError(error: AxiosError): Promise<object>;
+}
+export default RestClient;
+//# sourceMappingURL=rest.d.ts.map

package/dist/clients/rest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.d.ts","sourceRoot":"","sources":["../../src/clients/rest.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAC5F,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,sBAAsB;;;iBAA+D,CAAA;AAElG,OAAO,QAAQ,WAAW,CAAC;IACzB,UAAU,gBAAgB;QACxB,IAAI,EAAE,OAAO,UAAU,CAAA;KACxB;CACF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU,CACrB,CAAC,SAAS,WAAW,GAAG,WAAW,EACnC,CAAC,SAAS,aAAa,GAAG,aAAa,CACvC,SAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IACpB,KAAK,EAAG,aAAa,CAAC;IAEtB,OAAgB,QAAQ,EAAE,MAAM,CAAiB;IACjD,OAAgB,YAAY;;;sBAAyB;gBAGzC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,gBAAgB;IAgB3C,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAGpC,qEAAqE;IACrE,IAAI,OAAO,YAEV;IAED,IAAa,OAAO,WAEnB;IAED;;;;;;;;OAQG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,GAAQ,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC;IAkBxF;;;;;;;;OAQG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,GAAQ,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC;IAkBtF;;;;;;;;OAQG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,GAAQ,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC;IAkBvF;;;;;;;;OAQG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,GAAQ,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC;IAkB3F;;;;;;;;OAQG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,GAAQ,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC;IAkBxF,mFAAmF;IAC7E,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;CAItD;AAED,eAAe,UAAU,CAAA"}

package/dist/clients/supabase/index.d.ts

@@ -0,0 +1,176 @@
+import { Client } from "@soederpop/luca/client";
+import type { ContainerContext } from "@soederpop/luca/container";
+import { z } from "zod";
+import { type SupabaseClient as SupabaseSDKClient, type RealtimeChannel } from "@supabase/supabase-js";
+declare module "@soederpop/luca/client" {
+    interface AvailableClients {
+        supabase: typeof SupabaseClient;
+    }
+}
+export declare const SupabaseClientOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    baseURL: z.ZodOptional<z.ZodString>;
+    json: z.ZodOptional<z.ZodBoolean>;
+    supabaseUrl: z.ZodString;
+    supabaseKey: z.ZodString;
+    clientOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>;
+export declare const SupabaseClientStateSchema: z.ZodObject<{
+    connected: z.ZodDefault<z.ZodBoolean>;
+    authenticated: z.ZodDefault<z.ZodBoolean>;
+    userId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    userEmail: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    realtimeChannels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    lastError: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export declare const SupabaseClientEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    failure: z.ZodTuple<[z.ZodAny], null>;
+    authStateChange: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+    realtimeMessage: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+    realtimeStatus: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    error: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+export type SupabaseClientOptions = z.infer<typeof SupabaseClientOptionsSchema>;
+export type SupabaseClientState = z.infer<typeof SupabaseClientStateSchema>;
+/**
+ * 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 declare class SupabaseClient extends Client<SupabaseClientState, SupabaseClientOptions> {
+    static shortcut: "clients.supabase";
+    static description: string;
+    static stateSchema: z.ZodObject<{
+        connected: z.ZodDefault<z.ZodBoolean>;
+        authenticated: z.ZodDefault<z.ZodBoolean>;
+        userId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        userEmail: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        realtimeChannels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        lastError: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        json: z.ZodOptional<z.ZodBoolean>;
+        supabaseUrl: z.ZodString;
+        supabaseKey: z.ZodString;
+        clientOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        failure: z.ZodTuple<[z.ZodAny], null>;
+        authStateChange: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+        realtimeMessage: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+        realtimeStatus: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+        error: z.ZodTuple<[z.ZodAny], null>;
+    }, z.core.$strip>;
+    private _sdk;
+    private _channels;
+    constructor(options: SupabaseClientOptions, context: ContainerContext);
+    /** Returns the raw Supabase SDK client for full access to all SDK methods. */
+    get sdk(): SupabaseSDKClient<any, any>;
+    /**
+     * Start a query on a Postgres table or view.
+     * @param table - The table or view name to query
+     */
+    from(table: string): import("@supabase/postgrest-js").PostgrestQueryBuilder<any, any, any, string, unknown>;
+    /**
+     * 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";
+    }): import("@supabase/postgrest-js").PostgrestFilterBuilder<any, any, any, any, string, null, "RPC">;
+    /** Sign in with email and password. */
+    signInWithPassword(email: string, password: string): Promise<import("@supabase/auth-js").AuthTokenResponsePassword>;
+    /** Create a new user account with email and password. */
+    signUp(email: string, password: string): Promise<import("@supabase/auth-js").AuthResponse>;
+    /** Sign the current user out. */
+    signOut(): Promise<{
+        error: import("@supabase/auth-js").AuthError | null;
+    }>;
+    /** Get the current session, if any. */
+    getSession(): Promise<{
+        data: {
+            session: import("@supabase/auth-js").Session;
+        };
+        error: null;
+    } | {
+        data: {
+            session: null;
+        };
+        error: import("@supabase/auth-js").AuthError;
+    } | {
+        data: {
+            session: null;
+        };
+        error: null;
+    }>;
+    /** Get the current user, if any. */
+    getUser(): Promise<import("@supabase/auth-js").UserResponse>;
+    /** Returns the Supabase Storage client for managing buckets and files. */
+    get storage(): import("@supabase/storage-js").StorageClient;
+    /** Returns the Supabase Functions client. */
+    get functions(): import("@supabase/functions-js").FunctionsClient;
+    /** Invoke a Supabase Edge Function by name. */
+    invoke(name: string, body?: any): Promise<import("@supabase/functions-js").FunctionsResponse<any>>;
+    /**
+     * 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;
+    /**
+     * Unsubscribe and remove a realtime channel by name.
+     * @param channelName - The channel name to remove
+     */
+    unsubscribe(channelName: string): Promise<void>;
+    /** Unsubscribe and remove all realtime channels. */
+    unsubscribeAll(): Promise<void>;
+    /**
+     * Connect is a no-op since the Supabase SDK initializes on construction.
+     * The client is ready to use immediately after creation.
+     */
+    connect(): Promise<this>;
+    /**
+     * Disconnect by signing out and removing all realtime channels.
+     */
+    disconnect(): Promise<void>;
+    private _syncChannelState;
+    private _setError;
+}
+export default SupabaseClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/clients/supabase/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/clients/supabase/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACP,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,OAAO,EAEL,KAAK,cAAc,IAAI,iBAAiB,EAExC,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,gBAAgB;QACxB,QAAQ,EAAE,OAAO,cAAc,CAAC;KACjC;CACF;AAMD,eAAO,MAAM,2BAA2B;;;;;;;;iBAaa,CAAC;AAEtD,eAAO,MAAM,yBAAyB;;;;;;;iBAwBF,CAAC;AAErC,eAAO,MAAM,0BAA0B;;;;;;;iBAsBF,CAAC;AAEtC,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAM5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,cAAe,SAAQ,MAAM,CACxC,mBAAmB,EACnB,qBAAqB,CACtB;IACC,OAAgB,QAAQ,EAAG,kBAAkB,CAAU;IACvD,OAAgB,WAAW,SAC6E;IAExG,OAAgB,WAAW;;;;;;;sBAA6B;IACxD,OAAgB,aAAa;;;;;;;;sBAA+B;IAC5D,OAAgB,YAAY;;;;;;;sBAA8B;IAI1D,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,SAAS,CAAsC;gBAE3C,OAAO,EAAE,qBAAqB,EAAE,OAAO,EAAE,gBAAgB;IAqBrE,8EAA8E;IAC9E,IAAI,GAAG,IAAI,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,CAErC;IAMD;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM;IAIlB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,WAAW,CAAA;KAAE;IAQxI,uCAAuC;IACjC,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAQxD,yDAAyD;IACnD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAQ5C,iCAAiC;IAC3B,OAAO;;;IAQb,uCAAuC;IACjC,UAAU;;;;;;;;;;;;;;;;IAIhB,oCAAoC;IAC9B,OAAO;IAQb,0EAA0E;IAC1E,IAAI,OAAO,iDAEV;IAMD,6CAA6C;IAC7C,IAAI,SAAS,qDAEZ;IAED,+CAA+C;IACzC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;IAYrC;;;;;;OAMG;IACH,SAAS,CACP,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,EAChC,KAAK,GAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,GAAS,GAChD,eAAe;IAoBlB;;;OAGG;IACG,WAAW,CAAC,WAAW,EAAE,MAAM;IASrC,oDAAoD;IAC9C,cAAc;IAUpB;;;OAGG;IACY,OAAO;IAKtB;;OAEG;IACG,UAAU;IAahB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,SAAS;CAIlB;AAED,eAAe,cAAc,CAAC"}

package/dist/clients/websocket.d.ts

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import { Client } from '../client.js';
+import type { ContainerContext } from '../container.js';
+import { WebSocketClientStateSchema, WebSocketClientOptionsSchema } 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.
+ *
+ * Supports ask/reply semantics when paired with the Luca WebSocket server.
+ * The client can `ask(type, data)` the server and await a typed response.
+ * Incoming messages with a `requestId` are treated as asks from the server
+ * and can be answered with `send({ replyTo: requestId, data })`. Requests
+ * time out if no reply arrives within the configurable window.
+ *
+ * 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' })
+ *
+ * // ask/reply: request data from the server
+ * const result = await ws.ask('getUser', { id: 42 })
+ * ```
+ */
+export interface PendingRequest<T = any> {
+    resolve: (value: T) => void;
+    reject: (reason: any) => void;
+    timer: ReturnType<typeof setTimeout>;
+}
+export declare class WebSocketClient<T extends WebSocketClientState = WebSocketClientState, K extends WebSocketClientOptions = WebSocketClientOptions> extends Client<T, K> {
+    ws: WebSocket;
+    _intentionalClose: boolean;
+    _pending: Map<string, PendingRequest<any>>;
+    static shortcut: "clients.websocket";
+    static stateSchema: z.ZodObject<{
+        connected: z.ZodDefault<z.ZodBoolean>;
+        connectionError: z.ZodOptional<z.ZodAny>;
+        reconnectAttempts: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        json: z.ZodOptional<z.ZodBoolean>;
+        reconnect: z.ZodOptional<z.ZodBoolean>;
+        reconnectInterval: z.ZodOptional<z.ZodNumber>;
+        maxReconnectAttempts: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        failure: z.ZodTuple<[z.ZodAny], null>;
+        message: z.ZodTuple<[z.ZodAny], null>;
+        open: z.ZodTuple<[], null>;
+        close: z.ZodTuple<[z.ZodOptional<z.ZodNumber>, z.ZodOptional<z.ZodString>], null>;
+        error: z.ZodTuple<[z.ZodAny], null>;
+        reconnecting: z.ZodTuple<[z.ZodNumber], null>;
+    }, z.core.$strip>;
+    constructor(options?: K, context?: ContainerContext);
+    get initialState(): 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.
+     */
+    connect(): Promise<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)
+     */
+    send(data: any): Promise<void>;
+    /**
+     * Send a request and wait for a correlated response. The message is sent
+     * with a unique `requestId`; the remote side is expected to reply with a
+     * message containing `replyTo` set to that same ID.
+     *
+     * @param type - A string identifying the request type
+     * @param data - Optional payload to include with the request
+     * @param timeout - How long to wait for a response (default 10 000 ms)
+     * @returns The `data` field of the response message
+     *
+     * @example
+     * ```typescript
+     * const result = await ws.ask('getUser', { id: 42 })
+     * ```
+     */
+    ask<R = any>(type: string, data?: any, timeout?: number): Promise<R>;
+    /** @internal Resolve a pending ask() if the incoming message has a replyTo field. Returns true if handled. */
+    _handleReply(message: any): boolean;
+    /** @internal Reject all pending ask() calls — used on disconnect. */
+    _rejectAllPending(reason: string): void;
+    /**
+     * Gracefully close the WebSocket connection. Suppresses auto-reconnect
+     * and updates connection state to disconnected.
+     */
+    disconnect(): Promise<this>;
+    /** Whether the client is in an error state. */
+    get hasError(): boolean;
+    /**
+     * Attempt to reconnect if the reconnect option is enabled and we haven't
+     * exceeded maxReconnectAttempts. Uses exponential backoff capped at 30s.
+     */
+    private maybeReconnect;
+}
+export default WebSocketClient;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/clients/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/clients/websocket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EACL,0BAA0B,EAAE,4BAA4B,EACzD,MAAM,oBAAoB,CAAA;AAE3B,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAC7E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEjF,OAAO,QAAQ,WAAW,CAAC;IACzB,UAAU,gBAAgB;QACxB,SAAS,EAAE,OAAO,eAAe,CAAA;KAClC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,GAAG;IACrC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;IAC3B,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7B,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAA;CACrC;AAED,qBAAa,eAAe,CAC1B,CAAC,SAAS,oBAAoB,GAAG,oBAAoB,EACrD,CAAC,SAAS,sBAAsB,GAAG,sBAAsB,CACzD,SAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IACpB,EAAE,EAAG,SAAS,CAAA;IACd,iBAAiB,EAAE,OAAO,CAAA;IAC1B,QAAQ,mCAAoC;IAE5C,OAAgB,QAAQ,EAAG,mBAAmB,CAAS;IACvD,OAAgB,WAAW;;;;sBAA6B;IACxD,OAAgB,aAAa;;;;;;;;sBAA+B;IAC5D,OAAgB,YAAY;;;;;;;;sBAA8B;gBAG9C,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAKnD,IAAa,YAAY,IAAI,CAAC,CAK7B;IAED;;;;;OAKG;IACY,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA8CvC;;;;OAIG;IACG,IAAI,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpC;;;;;;;;;;;;;;OAcG;IACG,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,SAAQ,GAAG,OAAO,CAAC,CAAC,CAAC;IAczE,8GAA8G;IAC9G,YAAY,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO;IAiBnC,qEAAqE;IACrE,iBAAiB,CAAC,MAAM,EAAE,MAAM;IAQhC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAUjC,+CAA+C;IAC/C,IAAI,QAAQ,YAEX;IAED;;;OAGG;IACH,OAAO,CAAC,cAAc;CAmBvB;AAED,eAAe,eAAe,CAAA"}