@soederpop/luca 0.1.1 → 0.1.3

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

@@ -0,0 +1,281 @@
+import { RestClient } from "../rest";
+import type { ContainerContext } from "@soederpop/luca/container";
+import { z } from 'zod';
+declare module "@soederpop/luca/client" {
+    interface AvailableClients {
+        comfyui: typeof ComfyUIClient;
+    }
+}
+export declare const ComfyUIClientStateSchema: z.ZodObject<{
+    connected: z.ZodDefault<z.ZodBoolean>;
+    clientId: z.ZodDefault<z.ZodString>;
+    queueRemaining: z.ZodDefault<z.ZodNumber>;
+    executing: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export declare const ComfyUIClientOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    baseURL: z.ZodOptional<z.ZodString>;
+    json: z.ZodOptional<z.ZodBoolean>;
+    wsURL: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ComfyUIClientState = z.infer<typeof ComfyUIClientStateSchema>;
+export type ComfyUIClientOptions = z.infer<typeof ComfyUIClientOptionsSchema>;
+export declare const ComfyUIClientEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    failure: z.ZodTuple<[z.ZodAny], null>;
+    execution_start: z.ZodTuple<[z.ZodObject<{
+        promptId: z.ZodString;
+    }, z.core.$strip>], null>;
+    executing: z.ZodTuple<[z.ZodObject<{
+        node: z.ZodString;
+        promptId: z.ZodString;
+    }, z.core.$strip>], null>;
+    progress: z.ZodTuple<[z.ZodObject<{
+        node: z.ZodString;
+        value: z.ZodNumber;
+        max: z.ZodNumber;
+        promptId: z.ZodString;
+    }, z.core.$strip>], null>;
+    executed: z.ZodTuple<[z.ZodObject<{
+        node: z.ZodString;
+        output: z.ZodAny;
+        promptId: z.ZodString;
+    }, z.core.$strip>], null>;
+    execution_cached: z.ZodTuple<[z.ZodObject<{
+        nodes: z.ZodArray<z.ZodString>;
+        promptId: z.ZodString;
+    }, z.core.$strip>], null>;
+    execution_error: z.ZodTuple<[z.ZodObject<{
+        promptId: z.ZodString;
+        exception_message: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>], null>;
+    execution_complete: z.ZodTuple<[z.ZodObject<{
+        promptId: z.ZodString;
+    }, z.core.$strip>], null>;
+}, z.core.$strip>;
+/** Maps a semantic input name to a specific node ID and field */
+export type InputMapping = Record<string, {
+    nodeId: string;
+    field: string;
+}>;
+export type WorkflowRunOptions = {
+    /** Use polling instead of WebSocket for tracking execution */
+    poll?: boolean;
+    /** Polling interval in ms (default 1000) */
+    pollInterval?: number;
+    /** Named input mapping: semantic name -> { nodeId, field } */
+    inputMap?: InputMapping;
+    /** If provided, output images are downloaded to this directory */
+    outputDir?: string;
+};
+export type WorkflowResult = {
+    promptId: string;
+    outputs: Record<string, any>;
+    images?: Array<{
+        filename: string;
+        subfolder: string;
+        type: string;
+        localPath?: string;
+    }>;
+};
+/**
+ * ComfyUI client — execute Stable Diffusion workflows via the ComfyUI API.
+ *
+ * Connects to a ComfyUI instance to queue prompts, track execution via WebSocket or polling,
+ * and download generated images. Supports both UI-format and API-format workflows with
+ * automatic conversion.
+ *
+ * @example
+ * ```typescript
+ * const comfy = container.client('comfyui', { baseURL: 'http://localhost:8188' })
+ * const result = await comfy.runWorkflow(workflow, {
+ *   '6': { text: 'a beautiful sunset' }
+ * })
+ * console.log(result.images)
+ * ```
+ */
+export declare class ComfyUIClient extends RestClient<ComfyUIClientState, ComfyUIClientOptions> {
+    static shortcut: "clients.comfyui";
+    static description: string;
+    static stateSchema: z.ZodObject<{
+        connected: z.ZodDefault<z.ZodBoolean>;
+        clientId: z.ZodDefault<z.ZodString>;
+        queueRemaining: z.ZodDefault<z.ZodNumber>;
+        executing: 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>;
+        wsURL: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        failure: z.ZodTuple<[z.ZodAny], null>;
+        execution_start: z.ZodTuple<[z.ZodObject<{
+            promptId: z.ZodString;
+        }, z.core.$strip>], null>;
+        executing: z.ZodTuple<[z.ZodObject<{
+            node: z.ZodString;
+            promptId: z.ZodString;
+        }, z.core.$strip>], null>;
+        progress: z.ZodTuple<[z.ZodObject<{
+            node: z.ZodString;
+            value: z.ZodNumber;
+            max: z.ZodNumber;
+            promptId: z.ZodString;
+        }, z.core.$strip>], null>;
+        executed: z.ZodTuple<[z.ZodObject<{
+            node: z.ZodString;
+            output: z.ZodAny;
+            promptId: z.ZodString;
+        }, z.core.$strip>], null>;
+        execution_cached: z.ZodTuple<[z.ZodObject<{
+            nodes: z.ZodArray<z.ZodString>;
+            promptId: z.ZodString;
+        }, z.core.$strip>], null>;
+        execution_error: z.ZodTuple<[z.ZodObject<{
+            promptId: z.ZodString;
+            exception_message: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>], null>;
+        execution_complete: z.ZodTuple<[z.ZodObject<{
+            promptId: z.ZodString;
+        }, z.core.$strip>], null>;
+    }, z.core.$strip>;
+    private ws;
+    constructor(options: ComfyUIClientOptions, context: ContainerContext);
+    /** Initial state with a random client ID. */
+    get initialState(): ComfyUIClientState;
+    /** The unique client ID used for WebSocket session tracking. */
+    get clientId(): string;
+    /** The WebSocket URL derived from baseURL or overridden via options. */
+    get wsURL(): string;
+    /**
+     * Queue a prompt (API-format workflow) for execution.
+     *
+     * @param prompt - The API-format workflow object
+     * @param clientId - Override the client ID for this request
+     * @returns The prompt ID and queue number
+     *
+     * @example
+     * ```typescript
+     * const { prompt_id } = await comfy.queuePrompt(apiWorkflow)
+     * ```
+     */
+    queuePrompt(prompt: Record<string, any>, clientId?: string): Promise<{
+        prompt_id: string;
+        number: number;
+    }>;
+    /**
+     * Get the current prompt queue status.
+     *
+     * @returns Running and pending queue items
+     */
+    getQueue(): Promise<{
+        queue_running: any[];
+        queue_pending: any[];
+    }>;
+    /**
+     * Get execution history, optionally for a specific prompt.
+     *
+     * @param promptId - If provided, returns history for this prompt only
+     * @returns History records keyed by prompt ID
+     */
+    getHistory(promptId?: string): Promise<Record<string, any>>;
+    /**
+     * Get system stats including GPU memory and queue info.
+     *
+     * @returns System statistics
+     */
+    getSystemStats(): Promise<any>;
+    /**
+     * Get node type info with input/output schemas.
+     *
+     * @param nodeClass - If provided, returns info for this node type only
+     * @returns Object info keyed by node class name
+     */
+    getObjectInfo(nodeClass?: string): Promise<any>;
+    /** Interrupt the currently executing prompt. */
+    interrupt(): Promise<void>;
+    /**
+     * List available models, optionally filtered by type.
+     *
+     * @param type - Model type filter (e.g., 'checkpoints', 'loras')
+     * @returns Array of model file names
+     */
+    getModels(type?: string): Promise<string[]>;
+    /** List available embedding models. */
+    getEmbeddings(): Promise<string[]>;
+    /**
+     * Upload an image to ComfyUI's input directory.
+     *
+     * @param file - The image data as Buffer or Blob
+     * @param filename - File name for the upload
+     * @param opts - Upload options (subfolder, type, overwrite)
+     * @returns Upload result from ComfyUI
+     */
+    uploadImage(file: Buffer | Blob, filename: string, opts?: {
+        subfolder?: string;
+        type?: string;
+        overwrite?: boolean;
+    }): Promise<any>;
+    /**
+     * Download a generated image from ComfyUI as a Buffer.
+     *
+     * @param filename - The image filename
+     * @param subfolder - Subfolder within the output directory
+     * @param type - Image type ('output', 'input', 'temp')
+     * @returns The image data as a Buffer
+     */
+    viewImage(filename: string, subfolder?: string, type?: string): Promise<Buffer>;
+    /**
+     * Open a WebSocket connection to ComfyUI for real-time execution tracking.
+     *
+     * Events emitted: `execution_start`, `executing`, `progress`, `executed`,
+     * `execution_cached`, `execution_error`, `execution_complete`.
+     */
+    connectWs(): Promise<void>;
+    /** Close the WebSocket connection. */
+    disconnectWs(): void;
+    private handleWsMessage;
+    /**
+     * Detect whether a workflow object is in UI format (exported from the graph
+     * editor) or API format (flat node-id-keyed object with class_type).
+     */
+    static isUIFormat(workflow: Record<string, any>): boolean;
+    /**
+     * Convert a UI-format workflow to the API format that /prompt expects.
+     *
+     * Requires a running ComfyUI instance to fetch `object_info` so we can
+     * map positional `widgets_values` to their named input fields.
+     *
+     * If the workflow is already in API format, it's returned as-is.
+     */
+    toApiFormat(workflow: Record<string, any>): Promise<Record<string, any>>;
+    /**
+     * Run a ComfyUI workflow with optional runtime input overrides.
+     *
+     * Inputs can be provided in two forms:
+     *
+     * **Direct node mapping** (when no `inputMap` in options):
+     * ```
+     * { '3': { seed: 42 }, '6': { text: 'a cat' } }
+     * ```
+     *
+     * **Named inputs** (when `inputMap` is provided in options):
+     * ```
+     * inputs: { positive_prompt: 'a cat', seed: 42 }
+     * options.inputMap: {
+     *   positive_prompt: { nodeId: '6', field: 'text' },
+     *   seed: { nodeId: '3', field: 'seed' }
+     * }
+     * ```
+     */
+    runWorkflow(workflow: Record<string, any>, inputs?: Record<string, any>, options?: WorkflowRunOptions): Promise<WorkflowResult>;
+    private waitForCompletionWs;
+    private pollForCompletion;
+}
+export default ComfyUIClient;
+//# sourceMappingURL=index.d.ts.map

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

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

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

@@ -0,0 +1,197 @@
+import { z } from 'zod';
+import { RestClient } from "../rest";
+import type { ContainerContext } from "@soederpop/luca/container";
+declare module "@soederpop/luca/client" {
+    interface AvailableClients {
+        elevenlabs: typeof ElevenLabsClient;
+    }
+}
+export declare const ElevenLabsClientOptionsSchema: 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>;
+    defaultVoiceId: z.ZodOptional<z.ZodString>;
+    defaultModelId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    outputFormat: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+export type ElevenLabsClientOptions = z.infer<typeof ElevenLabsClientOptionsSchema>;
+export declare const ElevenLabsClientStateSchema: z.ZodObject<{
+    connected: z.ZodDefault<z.ZodBoolean>;
+    requestCount: z.ZodDefault<z.ZodNumber>;
+    characterCount: z.ZodDefault<z.ZodNumber>;
+    lastRequestTime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$loose>;
+export type ElevenLabsClientState = z.infer<typeof ElevenLabsClientStateSchema>;
+export declare const ElevenLabsClientEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    failure: z.ZodTuple<[z.ZodAny], null>;
+    speech: z.ZodTuple<[z.ZodObject<{
+        voiceId: z.ZodString;
+        text: z.ZodString;
+        audioSize: z.ZodNumber;
+    }, z.core.$strip>], null>;
+    voices: z.ZodTuple<[z.ZodArray<z.ZodAny>], null>;
+}, z.core.$strip>;
+export type ElevenLabsVoiceSettings = {
+    stability?: number;
+    similarityBoost?: number;
+    style?: number;
+    speed?: number;
+    useSpeakerBoost?: boolean;
+};
+export type SynthesizeOptions = {
+    voiceId?: string;
+    modelId?: string;
+    outputFormat?: string;
+    voiceSettings?: ElevenLabsVoiceSettings;
+    disableCache?: boolean;
+};
+/**
+ * ElevenLabs client — text-to-speech synthesis via the ElevenLabs REST API.
+ *
+ * Provides methods for listing voices, listing models, and generating speech audio.
+ * Audio is returned as a Buffer; use `say()` for a convenience method that writes to disk.
+ *
+ * @example
+ * ```typescript
+ * const el = container.client('elevenlabs')
+ * await el.connect()
+ * const voices = await el.listVoices()
+ * const audio = await el.synthesize('Hello world')
+ * // audio is a Buffer of mp3 data
+ * ```
+ */
+export declare class ElevenLabsClient extends RestClient<ElevenLabsClientState, ElevenLabsClientOptions> {
+    static shortcut: "clients.elevenlabs";
+    static envVars: string[];
+    static stateSchema: z.ZodObject<{
+        connected: z.ZodDefault<z.ZodBoolean>;
+        requestCount: z.ZodDefault<z.ZodNumber>;
+        characterCount: z.ZodDefault<z.ZodNumber>;
+        lastRequestTime: z.ZodDefault<z.ZodNullable<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>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        defaultVoiceId: z.ZodOptional<z.ZodString>;
+        defaultModelId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        outputFormat: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        failure: z.ZodTuple<[z.ZodAny], null>;
+        speech: z.ZodTuple<[z.ZodObject<{
+            voiceId: z.ZodString;
+            text: z.ZodString;
+            audioSize: z.ZodNumber;
+        }, z.core.$strip>], null>;
+        voices: z.ZodTuple<[z.ZodArray<z.ZodAny>], null>;
+    }, z.core.$strip>;
+    get initialState(): ElevenLabsClientState;
+    constructor(options: ElevenLabsClientOptions, context: ContainerContext);
+    /** The resolved API key from options or environment. */
+    get apiKey(): string;
+    /**
+     * Inject the xi-api-key header before each request.
+     */
+    beforeRequest(): Promise<void>;
+    private trackRequest;
+    /**
+     * Validate the API key by listing available models.
+     *
+     * @returns This client instance
+     * @throws If the API key is invalid or the connection fails
+     *
+     * @example
+     * ```typescript
+     * await el.connect()
+     * ```
+     */
+    connect(): Promise<this>;
+    /**
+     * List available voices with optional search and filtering.
+     *
+     * @param options - Query parameters for filtering voices
+     * @returns Array of voice objects
+     *
+     * @example
+     * ```typescript
+     * const voices = await el.listVoices()
+     * const premade = await el.listVoices({ category: 'premade' })
+     * ```
+     */
+    listVoices(options?: {
+        search?: string;
+        category?: string;
+        voice_type?: string;
+        page_size?: number;
+        next_page_token?: string;
+    }): Promise<any>;
+    /**
+     * Get details for a single voice.
+     *
+     * @param voiceId - The voice ID to look up
+     * @returns Voice object with settings, labels, and metadata
+     *
+     * @example
+     * ```typescript
+     * const voice = await el.getVoice('21m00Tcm4TlvDq8ikWAM')
+     * console.log(voice.name, voice.settings)
+     * ```
+     */
+    getVoice(voiceId: string): Promise<any>;
+    /**
+     * List available TTS models.
+     *
+     * @returns Array of model objects with IDs and capabilities
+     *
+     * @example
+     * ```typescript
+     * const models = await el.listModels()
+     * console.log(models.map(m => m.model_id))
+     * ```
+     */
+    listModels(): Promise<any[]>;
+    /**
+     * Synthesize speech from text, returning audio as a Buffer.
+     *
+     * @param text - The text to convert to speech
+     * @param options - Voice, model, format, and voice settings overrides
+     * @returns Audio data as a Buffer
+     *
+     * @example
+     * ```typescript
+     * const audio = await el.synthesize('Hello world')
+     * // audio is a Buffer of mp3 data
+     *
+     * const custom = await el.synthesize('Hello', {
+     *   voiceId: '21m00Tcm4TlvDq8ikWAM',
+     *   voiceSettings: { stability: 0.5, similarityBoost: 0.8 }
+     * })
+     * ```
+     */
+    synthesize(text: string, options?: SynthesizeOptions): Promise<Buffer>;
+    private fetchSpeech;
+    /**
+     * Synthesize speech and write the audio to a file.
+     *
+     * @param text - The text to convert to speech
+     * @param outputPath - File path to write the audio to
+     * @param options - Voice, model, format, and voice settings overrides
+     * @returns The resolved output path
+     *
+     * @example
+     * ```typescript
+     * const path = await el.say('Hello world', './hello.mp3')
+     * console.log(`Audio saved to ${path}`)
+     * ```
+     */
+    say(text: string, outputPath: string, options?: SynthesizeOptions): Promise<string>;
+}
+export default ElevenLabsClient;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/clients/elevenlabs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,gBAAgB;QACxB,UAAU,EAAE,OAAO,gBAAgB,CAAC;KACrC;CACF;AAED,eAAO,MAAM,6BAA6B;;;;;;;;;iBAKxC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEnF,eAAO,MAAM,2BAA2B;;;;;iBAItC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAE/E,eAAO,MAAM,4BAA4B;;;;;;;;;iBAOvC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,uBAAuB,CAAA;IACvC,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,SAAQ,UAAU,CAAC,qBAAqB,EAAE,uBAAuB,CAAC;IAC9F,OAAgB,QAAQ,EAAG,oBAAoB,CAAS;IACxD,OAAgB,OAAO,WAAyB;IAChD,OAAgB,WAAW;;;;;sBAA8B;IACzD,OAAgB,aAAa;;;;;;;;;sBAAgC;IAC7D,OAAgB,YAAY;;;;;;;;;sBAA+B;IAI3D,IAAa,YAAY,IAAI,qBAAqB,CAOjD;gBAEW,OAAO,EAAE,uBAAuB,EAAE,OAAO,EAAE,gBAAgB;IAQvE,wDAAwD;IACxD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACY,aAAa;IAI5B,OAAO,CAAC,YAAY;IAUpB;;;;;;;;;;OAUG;IACY,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAYvC;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,OAAO,GAAE;QACxB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,eAAe,CAAC,EAAE,MAAM,CAAA;KACpB,GAAG,OAAO,CAAC,GAAG,CAAC;IASrB;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAK7C;;;;;;;;;;OAUG;IACG,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAKlC;;;;;;;;;;;;;;;;;OAiBG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC;YAoDlE,WAAW;IAmBzB;;;;;;;;;;;;;OAaG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC;CAM9F;AAED,eAAe,gBAAgB,CAAA"}

package/dist/clients/graph.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { RestClient } from './rest.js';
+import type { ClientState } from '../client.js';
+import { GraphClientOptionsSchema } 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 declare class GraphClient<T extends ClientState = ClientState, K extends GraphClientOptions = GraphClientOptions> extends RestClient<T, K> {
+    static shortcut: "clients.graph";
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        json: z.ZodOptional<z.ZodBoolean>;
+        endpoint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        failure: z.ZodTuple<[z.ZodAny], null>;
+        graphqlError: z.ZodTuple<[z.ZodArray<z.ZodAny>], null>;
+    }, z.core.$strip>;
+    /** The GraphQL endpoint path. Defaults to '/graphql'. */
+    get endpoint(): string;
+    /**
+     * 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
+     */
+    query<R = any>(query: string, variables?: Record<string, any>, operationName?: string): Promise<R>;
+    /**
+     * 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
+     */
+    mutate<R = any>(mutation: string, variables?: Record<string, any>, operationName?: string): Promise<R>;
+    /**
+     * 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 execute;
+}
+export default GraphClient;
+//# sourceMappingURL=graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/clients/graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EACL,wBAAwB,EACzB,MAAM,oBAAoB,CAAA;AAE3B,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAEzE,OAAO,QAAQ,WAAW,CAAC;IACzB,UAAU,gBAAgB;QACxB,KAAK,EAAE,OAAO,WAAW,CAAA;KAC1B;CACF;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW,CACtB,CAAC,SAAS,WAAW,GAAG,WAAW,EACnC,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,CACjD,SAAQ,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC;IACxB,OAAgB,QAAQ,EAAG,eAAe,CAAS;IACnD,OAAgB,aAAa;;;;;;sBAA2B;IACxD,OAAgB,YAAY;;;;sBAA0B;IAGtD,yDAAyD;IACzD,IAAI,QAAQ,WAEX;IAED;;;;;OAKG;IACG,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIxG;;;;;;OAMG;IACG,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAI5G;;;;;OAKG;YACW,OAAO;CActB;AAED,eAAe,WAAW,CAAA"}