@soederpop/luca 0.0.6 → 0.0.7

package/docs/apis/clients/graph.md

@@ -1,6 +1,6 @@
 # GraphClient (clients.graph)
 
-No description provided
+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.
 
 ## Usage
 
@@ -23,29 +23,69 @@ container.client('graph', {
 | `json` | `boolean` | Whether to automatically parse responses as JSON |
 | `endpoint` | `string` | The GraphQL endpoint path, defaults to /graphql |
 
+## Methods
+
+### query
+
+Execute a GraphQL query and return the unwrapped data.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | The GraphQL query string |
+| `variables` | `Record<string, any>` |  | Optional variables for the query |
+| `operationName` | `string` |  | Optional operation name when the query contains multiple operations |
+
+**Returns:** `Promise<R>`
+
+
+
+### mutate
+
+Execute a GraphQL mutation and return the unwrapped data. Semantically identical to query() but named for clarity when performing mutations.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `mutation` | `string` | ✓ | The GraphQL mutation string |
+| `variables` | `Record<string, any>` |  | Optional variables for the mutation |
+| `operationName` | `string` |  | Optional operation name when the mutation contains multiple operations |
+
+**Returns:** `Promise<R>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `endpoint` | `any` | The GraphQL endpoint path. Defaults to '/graphql'. |
+
 ## Events (Zod v4 schema)
 
-### failure
+### graphqlError
 
-Emitted when a request fails
+Emitted when GraphQL-level errors are present in the response
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `any` | The error object |
+| `arg0` | `array` | Array of GraphQL errors |
 
 
 
-### graphqlError
+### failure
 
-Emitted when GraphQL-level errors are present in the response
+Emitted when a request fails
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `array` | Array of GraphQL errors |
+| `arg0` | `any` | The error object |
 
 
 
@@ -53,4 +93,15 @@ Emitted when GraphQL-level errors are present in the response
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `connected` | `boolean` | Whether the client is currently connected |
+| `connected` | `boolean` | Whether the client is currently connected |
+
+## Examples
+
+**clients.graph**
+
+```ts
+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' })
+```
+

package/docs/apis/clients/openai.md

@@ -1,6 +1,6 @@
 # OpenAIClient (clients.openai)
 
-No description provided
+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.
 
 ## Usage
 
@@ -41,8 +41,214 @@ container.client('openai', {
 | `timeout` | `number` | Request timeout in milliseconds |
 | `maxRetries` | `number` | Maximum number of retries on failure |
 
+## Methods
+
+### connect
+
+Test the API connection by listing models.
+
+**Returns:** `Promise<this>`
+
+```ts
+await openai.connect()
+```
+
+
+
+### createChatCompletion
+
+Create a chat completion using the Chat Completions API.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `messages` | `OpenAI.Chat.Completions.ChatCompletionMessageParam[]` | ✓ | Array of chat messages |
+| `options` | `Partial<OpenAI.Chat.Completions.ChatCompletionCreateParams>` |  | Additional parameters for the completion |
+
+**Returns:** `Promise<OpenAI.Chat.Completions.ChatCompletion>`
+
+```ts
+const response = await openai.createChatCompletion([
+ { role: 'system', content: 'You are a helpful assistant.' },
+ { role: 'user', content: 'Hello!' }
+])
+console.log(response.choices[0]?.message?.content)
+```
+
+
+
+### createResponse
+
+Create a response using the Responses API.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `OpenAI.Responses.ResponseInput | string` | ✓ | The input prompt or message array |
+| `options` | `Partial<OpenAI.Responses.ResponseCreateParamsNonStreaming>` |  | Additional parameters for the response |
+
+**Returns:** `Promise<OpenAI.Responses.Response>`
+
+```ts
+const response = await openai.createResponse('Explain quantum computing')
+```
+
+
+
+### streamResponse
+
+Stream a response using the Responses API.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `OpenAI.Responses.ResponseInput | string` | ✓ | The input prompt or message array |
+| `options` | `Partial<OpenAI.Responses.ResponseCreateParamsStreaming>` |  | Additional parameters for the streaming response |
+
+**Returns:** `Promise<AsyncIterable<OpenAI.Responses.ResponseStreamEvent>>`
+
+```ts
+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)
+ }
+}
+```
+
+
+
+### createCompletion
+
+Create a legacy text completion.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `prompt` | `string` | ✓ | The text prompt to complete |
+| `options` | `Partial<OpenAI.Completions.CompletionCreateParams>` |  | Additional parameters for the completion |
+
+**Returns:** `Promise<OpenAI.Completions.Completion>`
+
+```ts
+const response = await openai.createCompletion('Once upon a time')
+```
+
+
+
+### createEmbedding
+
+Create text embeddings for semantic search or similarity comparisons.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string | string[]` | ✓ | A string or array of strings to embed |
+| `options` | `Partial<OpenAI.Embeddings.EmbeddingCreateParams>` |  | Additional parameters (model, etc.) |
+
+**Returns:** `Promise<OpenAI.Embeddings.CreateEmbeddingResponse>`
+
+```ts
+const response = await openai.createEmbedding('Hello world')
+console.log(response.data[0].embedding.length)
+```
+
+
+
+### createImage
+
+Generate an image from a text prompt using DALL-E.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `prompt` | `string` | ✓ | Description of the image to generate |
+| `options` | `Partial<OpenAI.Images.ImageGenerateParams>` |  | Additional parameters (size, n, etc.) |
+
+**Returns:** `Promise<OpenAI.Images.ImagesResponse>`
+
+```ts
+const response = await openai.createImage('A sunset over mountains')
+console.log(response.data[0].url)
+```
+
+
+
+### listModels
+
+List all available models.
+
+**Returns:** `Promise<OpenAI.Models.ModelsPage>`
+
+```ts
+const models = await openai.listModels()
+```
+
+
+
+### ask
+
+Ask a single question and get a text response. Convenience wrapper around `createChatCompletion` for simple Q&A.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `question` | `string` | ✓ | The question to ask |
+| `options` | `Partial<OpenAI.Chat.Completions.ChatCompletionCreateParams>` |  | Additional completion parameters |
+
+**Returns:** `Promise<string>`
+
+```ts
+const answer = await openai.ask('What is 2 + 2?')
+console.log(answer) // '4'
+```
+
+
+
+### chat
+
+Send a multi-turn conversation and get a text response. Convenience wrapper around `createChatCompletion` that returns just the text.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `messages` | `OpenAI.Chat.Completions.ChatCompletionMessageParam[]` | ✓ | Array of chat messages |
+| `options` | `Partial<OpenAI.Chat.Completions.ChatCompletionCreateParams>` |  | Additional completion parameters |
+
+**Returns:** `Promise<string>`
+
+```ts
+const reply = await openai.chat([
+ { role: 'system', content: 'You are a pirate.' },
+ { role: 'user', content: 'Hello!' }
+])
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `defaultModel` | `string` | The default model used for completions, from options or 'gpt-4o'. |
+| `raw` | `OpenAI` | The underlying OpenAI SDK instance for advanced use cases. |
+
 ## Events (Zod v4 schema)
 
+### connected
+
+Emitted when the API connection is verified
+
+
+
 ### failure
 
 Emitted when a request fails
@@ -55,6 +261,54 @@ Emitted when a request fails
 
 
 
+### completion
+
+Emitted after a chat completion, legacy completion, or response is created
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The completion or response object |
+
+
+
+### embedding
+
+Emitted after embeddings are created
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The embedding response object |
+
+
+
+### image
+
+Emitted after an image is generated
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The image generation response object |
+
+
+
+### models
+
+Emitted after listing available models
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The models list response |
+
+
+
 ## State (Zod v4 schema)
 
 | Property | Type | Description |
@@ -66,4 +320,110 @@ Emitted when a request fails
 
 ## Environment Variables
 
-- `OPENAI_API_KEY`
+- `OPENAI_API_KEY`
+
+## Examples
+
+**clients.openai**
+
+```ts
+const openai = container.client('openai', { defaultModel: 'gpt-4o' })
+const answer = await openai.ask('What is the meaning of life?')
+console.log(answer)
+```
+
+
+
+**connect**
+
+```ts
+await openai.connect()
+```
+
+
+
+**createChatCompletion**
+
+```ts
+const response = await openai.createChatCompletion([
+ { role: 'system', content: 'You are a helpful assistant.' },
+ { role: 'user', content: 'Hello!' }
+])
+console.log(response.choices[0]?.message?.content)
+```
+
+
+
+**createResponse**
+
+```ts
+const response = await openai.createResponse('Explain quantum computing')
+```
+
+
+
+**streamResponse**
+
+```ts
+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)
+ }
+}
+```
+
+
+
+**createCompletion**
+
+```ts
+const response = await openai.createCompletion('Once upon a time')
+```
+
+
+
+**createEmbedding**
+
+```ts
+const response = await openai.createEmbedding('Hello world')
+console.log(response.data[0].embedding.length)
+```
+
+
+
+**createImage**
+
+```ts
+const response = await openai.createImage('A sunset over mountains')
+console.log(response.data[0].url)
+```
+
+
+
+**listModels**
+
+```ts
+const models = await openai.listModels()
+```
+
+
+
+**ask**
+
+```ts
+const answer = await openai.ask('What is 2 + 2?')
+console.log(answer) // '4'
+```
+
+
+
+**chat**
+
+```ts
+const reply = await openai.chat([
+ { role: 'system', content: 'You are a pirate.' },
+ { role: 'user', content: 'Hello!' }
+])
+```
+

package/docs/apis/clients/rest.md

@@ -1,6 +1,6 @@
 # RestClient (clients.rest)
 
-No description provided
+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.
 
 ## Usage
 
@@ -20,6 +20,115 @@ container.client('rest', {
 | `baseURL` | `string` | Base URL for the client connection |
 | `json` | `boolean` | Whether to automatically parse responses as JSON |
 
+## Methods
+
+### beforeRequest
+
+**Returns:** `void`
+
+
+
+### patch
+
+Send a PATCH request.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | `string` | ✓ | Request path relative to baseURL |
+| `data` | `any` |  | Request body |
+| `options` | `AxiosRequestConfig` |  | Additional axios request config |
+
+**Returns:** `void`
+
+
+
+### put
+
+Send a PUT request.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | `string` | ✓ | Request path relative to baseURL |
+| `data` | `any` |  | Request body |
+| `options` | `AxiosRequestConfig` |  | Additional axios request config |
+
+**Returns:** `void`
+
+
+
+### post
+
+Send a POST request.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | `string` | ✓ | Request path relative to baseURL |
+| `data` | `any` |  | Request body |
+| `options` | `AxiosRequestConfig` |  | Additional axios request config |
+
+**Returns:** `void`
+
+
+
+### delete
+
+Send a DELETE request.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | `string` | ✓ | Request path relative to baseURL |
+| `params` | `any` |  | Query parameters |
+| `options` | `AxiosRequestConfig` |  | Additional axios request config |
+
+**Returns:** `void`
+
+
+
+### get
+
+Send a GET request.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | `string` | ✓ | Request path relative to baseURL |
+| `params` | `any` |  | Query parameters |
+| `options` | `AxiosRequestConfig` |  | Additional axios request config |
+
+**Returns:** `void`
+
+
+
+### handleError
+
+Handle an axios error by emitting 'failure' and returning the error as JSON.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `error` | `AxiosError` | ✓ | Parameter error |
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `useJSON` | `any` | Whether JSON content-type headers should be set automatically. |
+| `baseURL` | `any` |  |
+
 ## Events (Zod v4 schema)
 
 ### failure
@@ -38,4 +147,15 @@ Emitted when a request fails
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `connected` | `boolean` | Whether the client is currently connected |
+| `connected` | `boolean` | Whether the client is currently connected |
+
+## Examples
+
+**clients.rest**
+
+```ts
+const api = container.client('rest', { baseURL: 'https://api.example.com', json: true })
+const users = await api.get('/users')
+await api.post('/users', { name: 'Alice' })
+```
+