@forgehive/hive-sdk 0.1.6 → 0.3.0

package/README.md

@@ -1,50 +1,23 @@
 # Hive SDK
 
-A TypeScript/JavaScript SDK for interacting with the Forge Hive logging and quality assessment platform.
-
-## ⚠️ Deprecation Notices
-
-- **`sendLog()` method**: Deprecated. Use `sendLogByName()` or `sendLogByUuid()` instead.
-- **`projectName`-only configuration**: Deprecated. Use `createClientFromForgeConf()` or include `projectUuid` in your configuration.
-
-Future versions will require `projectUuid` and remove support for the legacy `sendLog()` method and name-based project identification.
+A TypeScript/JavaScript SDK for interacting with the Forge Hive logging and task invocation platform.
 
 ## Quick Start
 
-Create a client from forge.json (recommended):
 ```typescript
 import { createClientFromForgeConf } from '@forgehive/hive-sdk'
 
-// Create client from forge.json (recommended)
+// Create client from forge.json
 const client = createClientFromForgeConf('./forge.json', {
   metadata: {
     environment: 'production',
     version: '1.0.0'
   }
 })
-```
 
-Or create with explicit configuration:
-```typescript
-import { HiveLogClient } from '@forgehive/hive-sdk'
-
-// Create client with explicit configuration
-const client = new HiveLogClient({
-  projectName: 'My Project',
-  projectUuid: 'your-project-uuid',
-  apiKey: 'your_api_key',
-  apiSecret: 'your_api_secret'
-})
-```
-
-On your app
-
-```typescript
-// Run a task
-const [res, error, record] = await someTask.safeRun(args)
-
-// Send a log using task name (recommended)
-await client.sendLogByName('stock:getPrice', record)
+// Run a task and send log
+const [result, error, record] = await someTask.safeRun(args)
+await client.sendLog(record, { environment: 'production' })
 ```
 
 ## Installation
@@ -59,236 +32,190 @@ or with pnpm:
 pnpm add @forgehive/hive-sdk
 ```
 
-## Setup
+## Core Concepts
 
-### 1. Configuration Options
+The Hive SDK provides two main clients:
 
-The Hive SDK can be configured in two ways:
+1. **HiveLogClient** - For logging task execution records to Hive
+2. **HiveClient** - For invoking tasks remotely
 
-#### Option A: Explicit Configuration (Recommended)
-
-```typescript
-import { HiveLogClient, createHiveLogClient } from '@forgehive/hive-sdk'
-
-// Direct configuration with credentials
-const config = {
-  projectName: 'My Project',
-  apiKey: 'your_api_key_here',
-  apiSecret: 'your_api_secret_here',
-  host: 'https://your-hive-instance.com', // Optional, defaults to https://www.forgehive.cloud
-  metadata: { // Optional base metadata
-    environment: 'production',
-    version: '1.2.0'
-  }
-}
+## HiveLogClient - Logging Task Executions
 
-const hiveLogger = new HiveLogClient(config)
-// or using the factory function
-const hiveLogger2 = createHiveLogClient(config)
-```
+### Configuration
 
-#### Option B: Environment Variables (Fallback)
+Create a client from your forge.json configuration file:
 
-If you prefer environment variables, the SDK will automatically use them when no explicit credentials are provided:
+```typescript
+import { createClientFromForgeConf } from '@forgehive/hive-sdk'
 
-```bash
-HIVE_API_KEY=your_api_key_here
-HIVE_API_SECRET=your_api_secret_here
-HIVE_HOST=https://your-hive-instance.com  # Optional, defaults to https://www.forgehive.cloud
-```
+// Use default forge.json path (./forge.json)
+const client = createClientFromForgeConf()
 
-```typescript
-import { HiveLogClient } from '@forgehive/hive-sdk'
+// Or specify a custom path
+const client = createClientFromForgeConf('./config/forge.json')
 
-// Uses environment variables for credentials
-const hiveLogger = new HiveLogClient({
-  projectName: 'My Project',
+// Add additional metadata
+const client = createClientFromForgeConf('./forge.json', {
   metadata: {
     environment: 'production',
-    version: '1.2.0'
+    version: '1.0.0'
   }
 })
 ```
 
-You can get your API credentials at [https://www.forgehive.cloud](https://www.forgehive.cloud).
+**Benefits:**
+- Automatically loads project name and UUID from forge.json
+- Automatically loads task UUIDs for logging
+- Supports task verification with `testConfig()`
+- Reduces configuration boilerplate
 
-### 2. Basic Usage
+**API Credentials:**
 
-```typescript
-import { HiveLogClient, createHiveLogClient } from '@forgehive/hive-sdk'
+Set your API credentials using environment variables:
 
-// Create client with explicit config
-const hiveLogger = new HiveLogClient({
-  projectName: 'Personal Knowledge Management System',
-  apiKey: 'your_api_key',
-  apiSecret: 'your_api_secret',
-  metadata: {
-    environment: 'production',
-    version: '1.2.0',
-    team: 'backend'
-  }
-})
-
-// Or using factory function
-const hiveLogger2 = createHiveLogClient({
-  projectName: 'Personal Knowledge Management System',
-  metadata: {
-    environment: 'production',
-    version: '1.2.0',
-    team: 'backend'
-  }
-})
+```bash
+HIVE_API_KEY=your_api_key_here
+HIVE_API_SECRET=your_api_secret_here
+HIVE_HOST=https://www.forgehive.cloud  # Optional
 ```
 
-## API Methods
+You can get your API credentials at [https://www.forgehive.cloud](https://www.forgehive.cloud).
 
-### `new HiveLogClient(config: HiveLogClientConfig): HiveLogClient`
+### Basic Usage
 
-Creates a new Hive log client instance with configuration object.
+#### Manual Logging
 
 ```typescript
-import { HiveLogClient, HiveLogClientConfig, Metadata } from '@forgehive/hive-sdk'
+import { createClientFromForgeConf } from '@forgehive/hive-sdk'
+import { myTask } from './tasks/myTask'
 
-// Minimal configuration (uses environment variables for credentials)
-const client = new HiveLogClient({
-  projectName: 'My Project'
-})
+// Create client
+const client = createClientFromForgeConf('./forge.json')
 
-// Full configuration with explicit credentials
-const config: HiveLogClientConfig = {
-  projectName: 'My Project',
-  apiKey: 'your_api_key',
-  apiSecret: 'your_api_secret',
-  host: 'https://your-hive-instance.com', // Optional, defaults to https://www.forgehive.cloud
-  metadata: {
+// Run task
+const [result, error, record] = await myTask.safeRun({ input: 'data' })
+
+// Manually send log
+if (record) {
+  const status = await client.sendLog(record, {
     environment: 'production',
-    version: '2.1.0',
-    datacenter: 'us-east-1'
-  }
+    requestId: 'req-123'
+  })
+  console.log('Log status:', status) // 'success', 'error', or 'silent'
 }
-const clientWithConfig = new HiveLogClient(config)
 ```
 
-**Configuration Object:**
-- `projectName`: Name of your project (required, ⚠️ deprecated - use `createClientFromForgeConf` instead)
-- `projectUuid`: UUID of your project (recommended for new implementations)
-- `apiKey`: API key (optional, falls back to `HIVE_API_KEY` environment variable)
-- `apiSecret`: API secret (optional, falls back to `HIVE_API_SECRET` environment variable)
-- `host`: Hive instance URL (optional, falls back to `HIVE_HOST` environment variable, then defaults to `https://www.forgehive.cloud`)
-- `metadata`: Base metadata that will be included with every log (optional)
-- `forgeConfigPath`: Path to forge.json file (optional, defaults to './forge.json')
-
-**Returns:** `HiveLogClient` - Configured client instance
-
-### `createClientFromForgeConf(forgeConfigPath?: string, additionalConfig?: Partial<HiveLogClientConfig>): HiveLogClient` (Recommended)
-
-Creates a Hive log client automatically configured from your forge.json file. This is the recommended way to create clients as it automatically loads project name, UUID, and task configurations.
+#### Automatic Logging with Global Listener
 
 ```typescript
+import { Task } from '@forgehive/task'
 import { createClientFromForgeConf } from '@forgehive/hive-sdk'
 
-// Use default forge.json path (./forge.json)
-const client = createClientFromForgeConf()
+// Create client
+const client = createClientFromForgeConf('./forge.json')
 
-// Use custom forge.json path
-const client = createClientFromForgeConf('./config/forge.json')
+// Set up global listener - automatically logs ALL task executions
+Task.listenExecutionRecords(client.getListener())
 
-// Use default path with additional config
-const client = createClientFromForgeConf(undefined, {
-  metadata: {
-    environment: 'production',
-    version: '1.0.0'
-  }
-})
-
-// Use custom path with additional config
-const client = createClientFromForgeConf('./forge.json', {
-  apiKey: 'override-key', // Override any forge.json values
-  metadata: {
-    environment: 'production'
-  }
-})
+// All task executions will now be automatically logged
+const [result1] = await task1.safeRun(args)  // Automatically logged
+const [result2] = await task2.safeRun(args)  // Automatically logged
 ```
 
+## API Reference - HiveLogClient
+
+### `createClientFromForgeConf(forgeConfigPath?: string, additionalConfig?: Partial<HiveLogClientConfig>): HiveLogClient`
+
+Creates a Hive log client automatically configured from your forge.json file.
+
 **Parameters:**
 - `forgeConfigPath` (optional): Path to forge.json file (defaults to './forge.json')
 - `additionalConfig` (optional): Additional config to override forge.json values
 
-**Returns:** `HiveLogClient` - Configured client with project name, UUID, and task mappings from forge.json
-
-**Benefits:**
-- Automatically loads project name and UUID from forge.json
-- Enables `sendLogByName()` method for easy task logging
-- Supports task verification with `testConfig()`
-- Reduces configuration boilerplate
+**Returns:** `HiveLogClient`
 
 ### `createHiveLogClient(config: HiveLogClientConfig): HiveLogClient`
 
-Factory function that creates a new Hive log client instance with explicit configuration.
-
-```typescript
-import { createHiveLogClient } from '@forgehive/hive-sdk'
-
-const client = createHiveLogClient({
-  projectName: 'My Project',
-  apiKey: 'your_api_key',
-  apiSecret: 'your_api_secret',
-  metadata: {
-    environment: 'production',
-    team: 'backend'
-  }
-})
-```
+Factory function that creates a new Hive log client instance.
 
-**Parameters:** Same as `HiveLogClient` constructor
-**Returns:** `HiveLogClient` - Configured client instance
+**Configuration Object:**
+- `projectName` (required): Name of your project
+- `projectUuid` (optional but recommended): UUID of your project
+- `apiKey` (optional): API key (falls back to `HIVE_API_KEY` env var)
+- `apiSecret` (optional): API secret (falls back to `HIVE_API_SECRET` env var)
+- `host` (optional): Hive instance URL (defaults to `https://www.forgehive.cloud`)
+- `metadata` (optional): Base metadata included with every log
+- `forgeConfigPath` (optional): Path to forge.json file (defaults to './forge.json')
 
-### `sendLog(record: ExecutionRecord, metadata?: Metadata): Promise<'success' | 'error' | 'silent' | LogApiSuccess>` ⚠️ DEPRECATED
+**Returns:** `HiveLogClient`
 
-> **⚠️ DEPRECATION WARNING**: `sendLog()` is deprecated and will be removed in a future version. Use `sendLogByName()` or `sendLogByUuid()` instead for better performance and enhanced features.
+### `client.sendLog(record: ExecutionRecord, metadata?: Metadata): Promise<'success' | 'error' | 'silent' | LogApiSuccess>`
 
-Sends a log entry to Hive using the legacy endpoint. This method still works but lacks the enhanced features of the newer UUID-based endpoints.
+Sends a log entry to Hive. Requires `projectUuid` to be set in client configuration.
 
 ```typescript
-// DEPRECATED - Use sendLogByName() instead
-const status = await client.sendLog(record, metadata)
+const [result, error, record] = await myTask.safeRun(args)
+
+if (record) {
+  const status = await client.sendLog(record, {
+    environment: 'production',
+    requestId: 'req-123'
+  })
 
-// RECOMMENDED - Use sendLogByName() for automatic UUID lookup
-const status = await client.sendLogByName('stock:getPrice', record, metadata)
+  switch (status) {
+    case 'success':
+      console.log('Log sent successfully')
+      break
+    case 'error':
+      console.error('Failed to send log')
+      break
+    case 'silent':
+      console.log('Running in silent mode - no credentials')
+      break
+  }
+}
 ```
 
-### `sendLogByName(taskName: string, record: ExecutionRecord, metadata?: Metadata): Promise<'success' | 'error' | 'silent' | LogApiSuccess>` (Recommended)
+**Parameters:**
+- `record`: ExecutionRecord from task execution
+- `metadata` (optional): Additional metadata for this log
 
-Sends a log entry to Hive using task name for automatic UUID lookup. Requires `projectUuid` to be set and forge.json to be loaded.
+**Returns:**
+- `'success'` - Log sent successfully
+- `'error'` - Network or API error
+- `'silent'` - Client not initialized (no credentials)
+- `LogApiSuccess` - Full API response with log details
 
-```typescript
-// Run a task and send log by name
-const [result, error, record] = await myTask.safeRun(args)
-const status = await client.sendLogByName('stock:getPrice', record, {
-  environment: 'production',
-  requestId: 'req-123'
-})
-```
-
-### `sendLogByUuid(record: ExecutionRecord, taskUuid: string, metadata?: Metadata): Promise<'success' | 'error' | 'silent' | LogApiSuccess>`
+### `client.getListener(): (record: ExecutionRecord) => Promise<void>`
 
-Sends a log entry to Hive using explicit task UUID. Requires `projectUuid` to be set in client config.
+Returns a listener function that can be passed to `Task.listenExecutionRecords()` for automatic logging.
 
 ```typescript
-const status = await client.sendLogByUuid(record, 'a45aafe3-8b01-4b58-b15d-9a96274858ee', metadata)
+import { Task } from '@forgehive/task'
+
+// Set up global automatic logging
+Task.listenExecutionRecords(client.getListener())
 ```
 
-### `testConfig(): Promise<TestConfigResult>`
+### `client.testConfig(): Promise<TestConfigResult>`
 
 Tests the client configuration by verifying credentials, project access, and task synchronization.
 
 ```typescript
 const result = await client.testConfig()
 console.log('Config test:', result)
-// Returns: { success, teamName, userName, projectName, projectExists, tasksVerified, error? }
+// Returns: {
+//   success: boolean
+//   teamName?: string
+//   userName?: string
+//   projectName?: string
+//   projectExists?: boolean
+//   tasksVerified?: { total: number, found: number, missing: string[] }
+//   error?: string
+// }
 ```
 
-### `getConf(): Record<string, unknown>`
+### `client.getConf(): Record<string, unknown>`
 
 Returns the client configuration with masked secrets (shows first 4 + last 4 characters).
 
@@ -298,281 +225,198 @@ console.log('Client config:', config)
 // Returns: { projectName, projectUuid, host, apiKey: 'abcd****wxyz', ... }
 ```
 
-### `isActive(): boolean`
+### `client.isActive(): boolean`
 
 Check if the client is properly initialized with credentials.
 
 ```typescript
-const hiveLogger = new HiveLogClient({
-  projectName: 'My Project',
-  apiKey: 'your_api_key',
-  apiSecret: 'your_api_secret'
-})
-
-if (hiveLogger.isActive()) {
+if (client.isActive()) {
   console.log('Client is initialized with credentials')
-  // Safe to call getLog and setQuality without try/catch
 } else {
   console.log('Client is in silent mode')
-  // Only sendLog will work (returns 'silent')
 }
 ```
 
-**Returns:** `boolean` - `true` if credentials are available, `false` if in silent mode
-
-### `sendLog(taskName: string, logItem: LogItemInput, metadata?: Metadata): Promise<'success' | 'error' | 'silent'>`
+### `client.getLog(taskName: string, uuid: string): Promise<LogApiResult | null>`
 
-Sends a log entry to Hive for a specific task with optional metadata. Accepts both manual log items and task execution records.
+Retrieves a specific log entry from Hive.
 
 ```typescript
-// Using a manual log item
-const status = await hiveLogger.sendLogByName('user-authentication', {
-  input: { username: 'john_doe', timestamp: Date.now() },
-  output: { success: true, userId: 12345 },
-  boundaries: {
-    database: [
-      {
-        input: 'SELECT * FROM users WHERE username = ?',
-        output: [{ id: 12345, username: 'john_doe' }],
-        error: null
-      }
-    ]
-  }
-}, {
-  // This metadata has highest priority
-  requestId: 'req-123',
-  userId: 'user-456'
-})
-
-// Using a task execution record directly
-const [result, error, record] = await someTask.safeRun(args)
-await hiveLogger.sendLogByName('task-name', record, {
-  environment: 'production'
-})
+const logData = await client.getLog('stock:getPrice', 'log-uuid-123')
 
-switch (status) {
-  case 'success':
-    console.log('Log sent successfully')
-    break
-  case 'error':
-    console.error('Failed to send log - network or API error')
-    break
-  case 'silent':
-    console.log('Running in silent mode - no credentials configured')
-    break
+if (logData && !isApiError(logData)) {
+  console.log('Log retrieved:', logData.logItem)
+} else if (logData && isApiError(logData)) {
+  console.error('API Error:', logData.error)
 }
 ```
 
 **Parameters:**
-- `taskName`: Name of the task being logged
-- `logItem`: LogItemInput object (supports both manual log items and task execution records)
-- `metadata` (optional): Additional metadata for this specific log
+- `taskName`: Name of the task
+- `uuid`: Unique identifier of the log entry
 
-**Returns:** `Promise<'success' | 'error' | 'silent'>` - Status of the operation
+**Returns:** `Promise<LogApiResult | null>`
 
-### `getLog(taskName: string, uuid: string): Promise<LogApiResult | null>`
+**Throws:** Error when credentials are missing
 
-Retrieves a specific log entry from Hive.
+### `client.setQuality(taskName: string, uuid: string, quality: Quality): Promise<boolean>`
+
+Sets a quality assessment for a specific log entry.
 
 ```typescript
-try {
-  const logData = await hiveLogger.getLog('user-authentication', 'log-uuid-123')
-
-  if (logData && !isApiError(logData)) {
-    console.log('Log retrieved:', logData.logItem)
-    console.log('Log metadata:', logData.logItem.metadata)
-  } else if (logData && isApiError(logData)) {
-    console.error('API Error:', logData.error)
-  } else {
-    console.error('Failed to retrieve log')
-  }
-} catch (error) {
-  console.error('Missing credentials:', error.message)
+import { Quality } from '@forgehive/hive-sdk'
+
+const quality: Quality = {
+  score: 8.5,
+  reason: 'Good performance with minor improvements needed',
+  suggestions: 'Consider optimizing the database query'
 }
+
+const success = await client.setQuality('stock:getPrice', 'log-uuid-123', quality)
 ```
 
 **Parameters:**
 - `taskName`: Name of the task
 - `uuid`: Unique identifier of the log entry
+- `quality`: Quality assessment object
+
+**Returns:** `Promise<boolean>` - `true` if successful, `false` if failed
 
-**Returns:** `Promise<LogApiResult | null>` - Log data, error object, or `null` if failed
 **Throws:** Error when credentials are missing
 
-### `setQuality(taskName: string, uuid: string, quality: Quality): Promise<boolean>`
+## HiveClient - Task Invocation
 
-Sets a quality assessment for a specific log entry.
+### Configuration
 
 ```typescript
-import { Quality } from '@forgehive/hive-sdk'
+import { createHiveClient } from '@forgehive/hive-sdk'
 
-const quality: Quality = {
-  score: 8.5,
-  reason: 'Good performance with minor improvements needed',
-  suggestions: 'Consider optimizing the database query for better performance'
-}
+const client = createHiveClient({
+  projectUuid: 'your-project-uuid',
+  apiKey: 'your_api_key',
+  apiSecret: 'your_api_secret',
+  host: 'https://www.forgehive.cloud' // Optional
+})
+```
 
-try {
-  const success = await hiveLogger.setQuality('user-authentication', 'log-uuid-123', quality)
+**Configuration Object:**
+- `projectUuid` (required): UUID of your project
+- `apiKey` (optional): API key (falls back to `HIVE_API_KEY` env var)
+- `apiSecret` (optional): API secret (falls back to `HIVE_API_SECRET` env var)
+- `host` (optional): Hive instance URL (defaults to `https://forgehive.dev`)
 
-  if (success) {
-    console.log('Quality assessment saved')
-  } else {
-    console.error('Failed to save quality assessment')
-  }
-} catch (error) {
-  console.error('Missing credentials:', error.message)
+### `client.invoke(taskUuid: string, payload: unknown): Promise<InvokeResult | null>`
+
+Invokes a task remotely on the Hive platform.
+
+```typescript
+import { createHiveClient, isInvokeError } from '@forgehive/hive-sdk'
+
+const client = createHiveClient({
+  projectUuid: process.env.HIVE_PROJECT_UUID || ''
+})
+
+const result = await client.invoke('task-uuid-here', {
+  ticker: 'AAPL'
+})
+
+if (isInvokeError(result)) {
+  console.error('Error invoking task:', result.error)
+} else {
+  console.log('Success:', result.responsePayload)
 }
 ```
 
 **Parameters:**
-- `taskName`: Name of the task
-- `uuid`: Unique identifier of the log entry
-- `quality`: Quality assessment object with score (number), reason (string), and suggestions (string)
+- `taskUuid`: UUID of the task to invoke
+- `payload`: Input data for the task
 
-**Returns:** `Promise<boolean>` - `true` if successful, `false` if failed
-**Throws:** Error when credentials are missing
+**Returns:** `Promise<InvokeResult | null>`
+- `{ responsePayload: unknown }` - Success response
+- `{ error: string }` - Error response
+- `null` - Network error
 
-## Metadata System
+### `client.testConfig(): Promise<TestConfigResult>`
 
-The Hive SDK supports a flexible metadata system that allows you to attach contextual information to your logs. Metadata can be provided at three levels with a clear priority system.
+Tests the client configuration by verifying credentials and project access.
 
-### Metadata Priority System
+### `client.getConf(): Record<string, unknown>`
 
-Metadata is merged using the following priority order (highest to lowest):
+Returns the client configuration with masked secrets.
 
-1. **sendLogByName metadata** - Metadata passed directly to the `sendLogByName` method
-2. **logItem metadata** - Metadata already present in the `logItem` object
+## Metadata System
+
+The Hive SDK supports a flexible metadata system with a clear priority order:
+
+### Metadata Priority (highest to lowest)
+
+1. **sendLog metadata** - Metadata passed directly to `sendLog()`
+2. **Record metadata** - Metadata in the ExecutionRecord
 3. **Client base metadata** - Metadata set when creating the client
 
+### Example
+
 ```typescript
 // Create client with base metadata
-const client = new HiveLogClient({
-  projectName: 'My Project',
-  apiKey: 'your_api_key',
-  apiSecret: 'your_api_secret',
+const client = createClientFromForgeConf('./forge.json', {
   metadata: {
     environment: 'production',
-    version: '1.0.0',
-    team: 'backend'
+    version: '1.0.0'
   }
 })
 
-// logItem with metadata
-const logItem = {
-  input: 'test input',
-  output: 'test output',
+// Record with metadata
+const record = {
+  taskName: 'myTask',
+  input: {},
+  output: {},
+  type: 'success',
+  boundaries: {},
   metadata: {
     sessionId: 'session-123',
-    version: '1.1.0'  // This overrides client version
+    version: '1.1.0'  // Overrides client version
   }
 }
 
-// Send log with additional metadata
-await client.sendLogByName('task-name', logItem, {
+// Send log with metadata
+await client.sendLog(record, {
   requestId: 'req-456',
-  version: '1.2.0'  // This overrides both logItem and client version
+  version: '1.2.0'  // Overrides all (highest priority)
 })
 
-// Final metadata sent will be:
+// Final metadata sent:
 // {
 //   environment: 'production',  // from client
-//   team: 'backend',            // from client
-//   sessionId: 'session-123',   // from logItem
-//   version: '1.2.0',           // from sendLogByName (highest priority)
-//   requestId: 'req-456'        // from sendLogByName
+//   sessionId: 'session-123',   // from record
+//   version: '1.2.0',           // from sendLog (highest priority)
+//   requestId: 'req-456'        // from sendLog
 // }
 ```
 
-### Metadata Usage Examples
-
-**Base metadata for all logs:**
-```typescript
-const client = new HiveLogClient({
-  projectName: 'My Service',
-  apiKey: 'your_api_key',
-  apiSecret: 'your_api_secret',
-  metadata: {
-    environment: process.env.NODE_ENV,
-    version: process.env.APP_VERSION,
-    datacenter: 'us-west-2'
-  }
-})
-```
-
-**Request-specific metadata:**
-```typescript
-app.post('/api/users', async (req, res) => {
-  const result = await client.sendLogByName('create-user', {
-    input: req.body,
-    output: newUser
-  }, {
-    requestId: req.headers['x-request-id'],
-    userId: req.user?.id,
-    ipAddress: req.ip
-  })
-})
-```
-
-**logItem with embedded metadata:**
-```typescript
-const logItem = {
-  input: { query: 'search term' },
-  output: { results: [...] },
-  metadata: {
-    searchDuration: '245',  // ms
-    resultCount: '15',
-    algorithm: 'fuzzy-v2'
-  }
-}
-
-await client.sendLogByName('search', logItem)
-```
-
 ## Types
 
 ### `HiveLogClientConfig`
 
 ```typescript
 interface HiveLogClientConfig {
-  projectName: string        // ⚠️ DEPRECATED - use createClientFromForgeConf() instead
-  projectUuid?: string       // Recommended for new implementations
+  projectName: string
+  projectUuid?: string       // Recommended
   apiKey?: string
   apiSecret?: string
   host?: string
   metadata?: Metadata
-  forgeConfigPath?: string   // Path to forge.json file
+  forgeConfigPath?: string
 }
 ```
 
-**⚠️ Migration Guide:**
-```typescript
-// OLD (deprecated) - projectName only
-const client = new HiveLogClient({
-  projectName: 'My Project'
-})
-
-// NEW (recommended) - use createClientFromForgeConf
-const client = createClientFromForgeConf('./forge.json')
-
-// NEW (alternative) - explicit projectUuid
-const client = new HiveLogClient({
-  projectName: 'My Project',
-  projectUuid: 'your-project-uuid'
-})
-```
-
-### `LogItemInput` (also exported as `LogItem`)
+### `HiveClientConfig`
 
 ```typescript
-interface LogItemInput {
-  input: unknown
-  output?: unknown
-  error?: unknown
-  boundaries?: unknown // Flexible to accept different boundary structures
-  metadata?: Metadata
-  taskName?: string
-  type?: string
-  [key: string]: unknown // Allows task execution records and other additional properties
+interface HiveClientConfig {
+  projectUuid: string        // Required
+  apiKey?: string
+  apiSecret?: string
+  host?: string
 }
 ```
 
@@ -584,25 +428,6 @@ interface Metadata {
 }
 ```
 
-### `LogApiResponse`
-
-```typescript
-interface LogApiResponse {
-  uuid: string
-  taskName: string
-  projectName: string
-  logItem: {
-    input: unknown
-    output?: unknown
-    error?: unknown
-    boundaries?: Record<string, Array<{ input: unknown; output: unknown, error: unknown }>>
-    metadata?: Metadata
-  }
-  replayFrom?: string
-  createdAt: string
-}
-```
-
 ### `Quality`
 
 ```typescript
@@ -613,6 +438,22 @@ interface Quality {
 }
 ```
 
+### `InvokeResponse`
+
+```typescript
+interface InvokeResponse {
+  responsePayload: unknown
+}
+```
+
+### `InvokeError`
+
+```typescript
+interface InvokeError {
+  error: string
+}
+```
+
 ### `ApiError`
 
 ```typescript
@@ -625,12 +466,12 @@ interface ApiError {
 
 ### `isApiError(response: unknown): response is ApiError`
 
-Use this type guard to check if a response is an error:
+Check if a response is an API error:
 
 ```typescript
 import { isApiError } from '@forgehive/hive-sdk'
 
-const result = await hiveLogger.getLog('task-name', 'log-uuid')
+const result = await client.getLog('task-name', 'log-uuid')
 
 if (result && isApiError(result)) {
   console.error('Error:', result.error)
@@ -639,9 +480,25 @@ if (result && isApiError(result)) {
 }
 ```
 
+### `isInvokeError(response: unknown): response is InvokeError`
+
+Check if an invoke response is an error:
+
+```typescript
+import { isInvokeError } from '@forgehive/hive-sdk'
+
+const result = await client.invoke('task-uuid', payload)
+
+if (isInvokeError(result)) {
+  console.error('Error:', result.error)
+} else {
+  console.log('Success:', result.responsePayload)
+}
+```
+
 ## Debugging
 
-The SDK uses the `debug` package for internal logging. To enable debug logs, set the `DEBUG` environment variable:
+The SDK uses the `debug` package for internal logging. To enable debug logs:
 
 ```bash
 # Enable all hive-sdk debug logs
@@ -649,28 +506,15 @@ DEBUG=hive-sdk node your-app.js
 
 # Enable all debug logs
 DEBUG=* node your-app.js
-
-# Enable hive-sdk logs along with other specific loggers
-DEBUG=hive-sdk,express:* node your-app.js
 ```
 
-When debugging is enabled, you'll see detailed logs like:
+Example debug output:
 
 ```
-# Normal mode (with credentials)
-hive-sdk Creating HiveLogClient for project "Personal Knowledge Management System" +0ms
-hive-sdk HiveLogClient initialized for project "Personal Knowledge Management System" with host "https://your-hive-instance.com" +2ms
-hive-sdk Sending log for task "user-authentication" to https://your-hive-instance.com/api/tasks/log-ingest +100ms
-hive-sdk Success: Sent log for task "user-authentication" +250ms
-
-# Silent mode (missing credentials)
-hive-sdk Creating HiveLogClient for project "Personal Knowledge Management System" +0ms
-hive-sdk HiveLogClient in silent mode for project "Personal Knowledge Management System" - missing credentials (get them at https://www.forgehive.cloud) +2ms
-hive-sdk Silent mode: Skipping sendLog for task "user-authentication" - client not initialized +100ms
-hive-sdk Error: getLog for task "user-task" with uuid "some-uuid" - missing credentials +150ms
-
-# Error handling
-hive-sdk Error: Failed to send log for task "another-task": Network timeout +300ms
+hive-sdk Creating HiveLogClient for project "My Project" +0ms
+hive-sdk HiveLogClient initialized for project "My Project" with host "https://www.forgehive.cloud" +2ms
+hive-sdk Sending log for task "stock:getPrice" (UUID: xxx) to https://www.forgehive.cloud/api/log-ingest +100ms
+hive-sdk Success: Sent log for task "stock:getPrice" (UUID: xxx) +250ms
 ```
 
 ## Error Handling
@@ -679,132 +523,78 @@ The SDK handles errors gracefully:
 
 - **Network errors**: Logged via debug, methods return `'error'` or `false`
 - **Authentication errors**: Logged via debug, methods return `'error'` or `false`
-- **API errors**: Returned as `ApiError` objects (for `getLog`) or logged via debug (for other methods)
 - **Missing credentials**:
   - `sendLog`: Returns `'silent'` (no errors thrown)
   - `getLog` and `setQuality`: Throw errors
+  - `invoke`: Requires credentials, throws if missing
 
-```typescript
-// sendLog works even without credentials (returns 'silent')
-const hiveLogger = new HiveLogClient({
-  projectName: 'My Project'
-  // No credentials provided - will use environment variables or go silent
-})
+### Silent Mode
 
-const status = await hiveLogger.sendLogByName('task-name', { data: 'example' })
-if (status === 'error') {
-  console.error('Network or API error')
-} else if (status === 'silent') {
-  console.log('Running in silent mode - no credentials')
-}
-```
-
-### Error Handling Patterns
+When credentials are missing, the client runs in "silent mode":
 
-**Check credentials before API calls:**
 ```typescript
-const hiveLogger = new HiveLogClient({
-  projectName: 'My Project'
-  // Credentials will be loaded from environment variables or explicit config
-})
+const client = createClientFromForgeConf('./forge.json')
+// No credentials in env vars - will go silent
 
-if (hiveLogger.isActive()) {
-  // Safe to use all methods
-  const logData = await hiveLogger.getLog('task', 'uuid')
-  await hiveLogger.setQuality('task', 'uuid', quality)
-} else {
-  console.log('Running in silent mode')
+const status = await client.sendLog(record)
+if (status === 'silent') {
+  console.log('Running in silent mode - logs not sent')
 }
-```
 
-**sendLogByName** - Returns status strings (never throws):
-```typescript
-const status = await hiveLogger.sendLogByName('task', { data: 'test' })
-// Returns: 'success', 'error', or 'silent'
-```
-
-**getLog and setQuality** - Throw errors when credentials missing:
-```typescript
-try {
-  await hiveLogger.getLog('task', 'uuid')
-  await hiveLogger.setQuality('task', 'uuid', quality)
-} catch (error) {
-  console.error('Missing credentials:', error.message)
+// Check before calling methods that throw
+if (client.isActive()) {
+  await client.getLog('task', 'uuid')
 }
 ```
 
-## Examples
-
-### Complete Example
+## Complete Example
 
 ```typescript
-import { HiveLogClient, isApiError, Quality, Metadata, LogItemInput } from '@forgehive/hive-sdk'
-
-async function main() {
-  // Initialize the client with configuration object
-  const hiveLogger = new HiveLogClient({
-    projectName: 'Personal Knowledge Management System',
-    apiKey: 'your_api_key_here',
-    apiSecret: 'your_api_secret_here',
-    host: 'https://your-hive-instance.com', // Optional, defaults to https://www.forgehive.cloud
-    metadata: {
-      environment: process.env.NODE_ENV || 'development',
-      version: '1.0.0',
-      service: 'document-search-service'
-    }
-  })
+import { createClientFromForgeConf, Quality } from '@forgehive/hive-sdk'
+import { Task } from '@forgehive/task'
+import { getPrice } from './tasks/stock/getPrice'
 
-  // Send a log with logItem containing metadata
-  const logData = {
-    input: { query: 'search for AI papers', userId: 123 },
-    output: { results: ['paper1.pdf', 'paper2.pdf'], count: 2 },
-    metadata: {
-      searchAlgorithm: 'semantic-search-v2',
-      processingTime: '245', // ms
-      cacheHit: 'false'
-    },
-    boundaries: {
-      search_engine: [
-        {
-          input: 'AI papers filetype:pdf',
-          output: { hits: 150, results: ['...'] },
-          error: null
-        }
-      ]
-    }
+// Create client from forge.json
+const client = createClientFromForgeConf('./forge.json', {
+  metadata: {
+    environment: process.env.NODE_ENV || 'development',
+    version: '1.0.0'
   }
+})
 
-  // Send log with additional high-priority metadata
-  const status = await hiveLogger.sendLogByName('document-search', logData, {
-    requestId: 'req-123456',
-    userId: 'user-789',
-    sessionId: 'sess-abc123'
+// Test configuration
+const configTest = await client.testConfig()
+if (!configTest.success) {
+  console.error('Config error:', configTest.error)
+  process.exit(1)
+}
+
+console.log('Connected as:', configTest.userName)
+console.log('Team:', configTest.teamName)
+console.log('Project:', configTest.projectName)
+
+// Option 1: Manual logging
+const [result, error, record] = await getPrice.safeRun({ ticker: 'AAPL' })
+
+if (error) {
+  console.error('Task failed:', error)
+} else {
+  console.log('Result:', result)
+
+  // Send log manually
+  const status = await client.sendLog(record, {
+    requestId: 'req-123',
+    userId: 'user-456'
   })
-  console.log('Log status:', status)
-
-    // Retrieve a log
-  try {
-    const retrievedLog = await hiveLogger.getLog('document-search', 'some-uuid')
-    if (retrievedLog && !isApiError(retrievedLog)) {
-      console.log('Retrieved log:', retrievedLog.logItem)
-      console.log('Log metadata:', retrievedLog.logItem.metadata)
-
-      // Set quality assessment
-      const quality: Quality = {
-        score: 9.0,
-        reason: 'Excellent search results with high relevance',
-        suggestions: 'Consider adding result ranking by publication date'
-      }
-
-      const qualitySet = await hiveLogger.setQuality('document-search', retrievedLog.uuid, quality)
-      console.log('Quality assessment saved:', qualitySet)
-    }
-  } catch (error) {
-    console.error('Missing credentials for getLog/setQuality:', error.message)
-  }
+  console.log('Log sent:', status)
 }
 
-main().catch(console.error)
+// Option 2: Automatic logging with global listener
+Task.listenExecutionRecords(client.getListener())
+
+// All subsequent task executions are automatically logged
+await getPrice.safeRun({ ticker: 'GOOGL' })  // Automatically logged
+await getPrice.safeRun({ ticker: 'MSFT' })   // Automatically logged
 ```
 
 ## License