@forgehive/hive-sdk 0.1.4 → 0.1.6

package/README.md

@@ -2,15 +2,36 @@
 
 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.
+
 ## Quick Start
 
-Create a client with:
+Create a client from forge.json (recommended):
+```typescript
+import { createClientFromForgeConf } from '@forgehive/hive-sdk'
+
+// Create client from forge.json (recommended)
+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 (recommended)
+// Create client with explicit configuration
 const client = new HiveLogClient({
   projectName: 'My Project',
+  projectUuid: 'your-project-uuid',
   apiKey: 'your_api_key',
   apiSecret: 'your_api_secret'
 })
@@ -22,8 +43,8 @@ On your app
 // Run a task
 const [res, error, record] = await someTask.safeRun(args)
 
-// Send a log
-await client.sendLog('task-name', record)
+// Send a log using task name (recommended)
+await client.sendLogByName('stock:getPrice', record)
 ```
 
 ## Installation
@@ -149,17 +170,61 @@ const clientWithConfig = new HiveLogClient(config)
 ```
 
 **Configuration Object:**
-- `projectName`: Name of your project (required)
+- `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.
+
+```typescript
+import { createClientFromForgeConf } from '@forgehive/hive-sdk'
+
+// Use default forge.json path (./forge.json)
+const client = createClientFromForgeConf()
+
+// Use custom forge.json path
+const client = createClientFromForgeConf('./config/forge.json')
+
+// 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'
+  }
+})
+```
+
+**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
+
 ### `createHiveLogClient(config: HiveLogClientConfig): HiveLogClient`
 
-Factory function that creates a new Hive log client instance.
+Factory function that creates a new Hive log client instance with explicit configuration.
 
 ```typescript
 import { createHiveLogClient } from '@forgehive/hive-sdk'
@@ -178,6 +243,61 @@ const client = createHiveLogClient({
 **Parameters:** Same as `HiveLogClient` constructor
 **Returns:** `HiveLogClient` - Configured client instance
 
+### `sendLog(record: ExecutionRecord, metadata?: Metadata): Promise<'success' | 'error' | 'silent' | LogApiSuccess>` ⚠️ DEPRECATED
+
+> **⚠️ DEPRECATION WARNING**: `sendLog()` is deprecated and will be removed in a future version. Use `sendLogByName()` or `sendLogByUuid()` instead for better performance and enhanced features.
+
+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.
+
+```typescript
+// DEPRECATED - Use sendLogByName() instead
+const status = await client.sendLog(record, metadata)
+
+// RECOMMENDED - Use sendLogByName() for automatic UUID lookup
+const status = await client.sendLogByName('stock:getPrice', record, metadata)
+```
+
+### `sendLogByName(taskName: string, record: ExecutionRecord, metadata?: Metadata): Promise<'success' | 'error' | 'silent' | LogApiSuccess>` (Recommended)
+
+Sends a log entry to Hive using task name for automatic UUID lookup. Requires `projectUuid` to be set and forge.json to be loaded.
+
+```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>`
+
+Sends a log entry to Hive using explicit task UUID. Requires `projectUuid` to be set in client config.
+
+```typescript
+const status = await client.sendLogByUuid(record, 'a45aafe3-8b01-4b58-b15d-9a96274858ee', metadata)
+```
+
+### `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? }
+```
+
+### `getConf(): Record<string, unknown>`
+
+Returns the client configuration with masked secrets (shows first 4 + last 4 characters).
+
+```typescript
+const config = client.getConf()
+console.log('Client config:', config)
+// Returns: { projectName, projectUuid, host, apiKey: 'abcd****wxyz', ... }
+```
+
 ### `isActive(): boolean`
 
 Check if the client is properly initialized with credentials.
@@ -206,7 +326,7 @@ Sends a log entry to Hive for a specific task with optional metadata. Accepts bo
 
 ```typescript
 // Using a manual log item
-const status = await hiveLogger.sendLog('user-authentication', {
+const status = await hiveLogger.sendLogByName('user-authentication', {
   input: { username: 'john_doe', timestamp: Date.now() },
   output: { success: true, userId: 12345 },
   boundaries: {
@@ -226,7 +346,7 @@ const status = await hiveLogger.sendLog('user-authentication', {
 
 // Using a task execution record directly
 const [result, error, record] = await someTask.safeRun(args)
-await hiveLogger.sendLog('task-name', record, {
+await hiveLogger.sendLogByName('task-name', record, {
   environment: 'production'
 })
 
@@ -320,7 +440,7 @@ The Hive SDK supports a flexible metadata system that allows you to attach conte
 
 Metadata is merged using the following priority order (highest to lowest):
 
-1. **sendLog metadata** - Metadata passed directly to the `sendLog` method
+1. **sendLogByName metadata** - Metadata passed directly to the `sendLogByName` method
 2. **logItem metadata** - Metadata already present in the `logItem` object
 3. **Client base metadata** - Metadata set when creating the client
 
@@ -348,7 +468,7 @@ const logItem = {
 }
 
 // Send log with additional metadata
-await client.sendLog('task-name', logItem, {
+await client.sendLogByName('task-name', logItem, {
   requestId: 'req-456',
   version: '1.2.0'  // This overrides both logItem and client version
 })
@@ -358,8 +478,8 @@ await client.sendLog('task-name', logItem, {
 //   environment: 'production',  // from client
 //   team: 'backend',            // from client
 //   sessionId: 'session-123',   // from logItem
-//   version: '1.2.0',           // from sendLog (highest priority)
-//   requestId: 'req-456'        // from sendLog
+//   version: '1.2.0',           // from sendLogByName (highest priority)
+//   requestId: 'req-456'        // from sendLogByName
 // }
 ```
 
@@ -382,7 +502,7 @@ const client = new HiveLogClient({
 **Request-specific metadata:**
 ```typescript
 app.post('/api/users', async (req, res) => {
-  const result = await client.sendLog('create-user', {
+  const result = await client.sendLogByName('create-user', {
     input: req.body,
     output: newUser
   }, {
@@ -405,7 +525,7 @@ const logItem = {
   }
 }
 
-await client.sendLog('search', logItem)
+await client.sendLogByName('search', logItem)
 ```
 
 ## Types
@@ -414,14 +534,33 @@ await client.sendLog('search', logItem)
 
 ```typescript
 interface HiveLogClientConfig {
-  projectName: string
+  projectName: string        // ⚠️ DEPRECATED - use createClientFromForgeConf() instead
+  projectUuid?: string       // Recommended for new implementations
   apiKey?: string
   apiSecret?: string
   host?: string
   metadata?: Metadata
+  forgeConfigPath?: string   // Path to forge.json file
 }
 ```
 
+**⚠️ 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`)
 
 ```typescript
@@ -552,7 +691,7 @@ const hiveLogger = new HiveLogClient({
   // No credentials provided - will use environment variables or go silent
 })
 
-const status = await hiveLogger.sendLog('task-name', { data: 'example' })
+const status = await hiveLogger.sendLogByName('task-name', { data: 'example' })
 if (status === 'error') {
   console.error('Network or API error')
 } else if (status === 'silent') {
@@ -578,9 +717,9 @@ if (hiveLogger.isActive()) {
 }
 ```
 
-**sendLog** - Returns status strings (never throws):
+**sendLogByName** - Returns status strings (never throws):
 ```typescript
-const status = await hiveLogger.sendLog('task', { data: 'test' })
+const status = await hiveLogger.sendLogByName('task', { data: 'test' })
 // Returns: 'success', 'error', or 'silent'
 ```
 
@@ -636,7 +775,7 @@ async function main() {
   }
 
   // Send log with additional high-priority metadata
-  const status = await hiveLogger.sendLog('document-search', logData, {
+  const status = await hiveLogger.sendLogByName('document-search', logData, {
     requestId: 'req-123456',
     userId: 'user-789',
     sessionId: 'sess-abc123'

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export interface HiveLogClientConfig {
     apiSecret?: string;
     host?: string;
     metadata?: Metadata;
+    forgeConfigPath?: string;
 }
 export interface LogApiResponse {
     uuid: string;
@@ -39,14 +40,34 @@ export declare class HiveLogClient {
     private projectUuid;
     private baseMetadata;
     private isInitialized;
+    private forgeConfig;
     constructor(config: HiveLogClientConfig);
     isActive(): boolean;
+    private maskSecret;
+    getConf(): Record<string, unknown>;
+    testConfig(): Promise<{
+        success: boolean;
+        teamName?: string;
+        teamUuid?: string;
+        userName?: string;
+        projectName?: string;
+        projectExists?: boolean;
+        tasksVerified?: {
+            total: number;
+            found: number;
+            missing: string[];
+        };
+        error?: string;
+    }>;
     private mergeMetadata;
     sendLog(record: ExecutionRecord, metadata?: Metadata): Promise<'success' | 'error' | 'silent' | LogApiSuccess>;
     sendLogByUuid(record: ExecutionRecord, taskUuid: string, metadata?: Metadata): Promise<'success' | 'error' | 'silent' | LogApiSuccess>;
     getListener(): (record: ExecutionRecord) => Promise<void>;
     getLog(taskName: string, uuid: string): Promise<LogApiResult | null>;
     setQuality(taskName: string, uuid: string, quality: Quality): Promise<boolean>;
+    private loadForgeConfig;
+    private getTaskUUID;
+    sendLogByName(taskName: string, record: ExecutionRecord, metadata?: Metadata): Promise<'success' | 'error' | 'silent' | LogApiSuccess>;
 }
 export declare const createHiveLogClient: (config: HiveLogClientConfig) => HiveLogClient;
 export interface HiveClientConfig {
@@ -69,6 +90,29 @@ export declare class HiveClient {
     private host;
     private projectUuid;
     constructor(config: HiveClientConfig);
-    invoke(taskName: string, payload: unknown): Promise<InvokeResult | null>;
+    private maskSecret;
+    getConf(): Record<string, unknown>;
+    testConfig(): Promise<{
+        success: boolean;
+        teamName?: string;
+        teamUuid?: string;
+        userName?: string;
+        projectName?: string;
+        projectExists?: boolean;
+        tasksVerified?: {
+            total: number;
+            found: number;
+            missing: string[];
+        };
+        error?: string;
+    }>;
+    invoke(taskUuid: string, payload: unknown): Promise<InvokeResult | null>;
 }
 export declare const createHiveClient: (config: HiveClientConfig) => HiveClient;
+/**
+ * Create a HiveLogClient from forge.json configuration
+ * @param forgeConfigPath Path to forge.json file (defaults to './forge.json')
+ * @param additionalConfig Additional config options to override forge.json values
+ * @returns HiveLogClient configured from forge.json
+ */
+export declare const createClientFromForgeConf: (forgeConfigPath?: string, additionalConfig?: Partial<HiveLogClientConfig>) => HiveLogClient;

package/dist/index.js

@@ -3,12 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createHiveClient = exports.HiveClient = exports.createHiveLogClient = exports.HiveLogClient = void 0;
+exports.createClientFromForgeConf = exports.createHiveClient = exports.HiveClient = exports.createHiveLogClient = exports.HiveLogClient = void 0;
 exports.isApiError = isApiError;
 exports.isInvokeError = isInvokeError;
 const axios_1 = __importDefault(require("axios"));
 const debug_1 = __importDefault(require("debug"));
 const uuid_1 = require("uuid");
+const fs_1 = __importDefault(require("fs"));
 const log = (0, debug_1.default)('hive-sdk');
 // Type guard to check if response is an error
 function isApiError(response) {
@@ -16,6 +17,7 @@ function isApiError(response) {
 }
 class HiveLogClient {
     constructor(config) {
+        this.forgeConfig = null;
         const apiKey = config.apiKey || process.env.HIVE_API_KEY;
         const apiSecret = config.apiSecret || process.env.HIVE_API_SECRET;
         const host = config.host || process.env.HIVE_HOST || 'https://www.forgehive.cloud';
@@ -36,10 +38,117 @@ class HiveLogClient {
             this.isInitialized = true;
             log('HiveLogClient initialized for project "%s" with host "%s"', config.projectName, host);
         }
+        // Load forge.json - use provided path or default to ./forge.json
+        const configPath = config.forgeConfigPath || './forge.json';
+        this.loadForgeConfig(configPath);
     }
     isActive() {
         return this.isInitialized;
     }
+    maskSecret(secret) {
+        if (!secret || secret.length <= 8) {
+            return secret ? '****' : 'null';
+        }
+        const first4 = secret.slice(0, 4);
+        const last4 = secret.slice(-4);
+        const middle = '*'.repeat(secret.length - 8);
+        return `${first4}${middle}${last4}`;
+    }
+    getConf() {
+        return {
+            projectName: this.projectName,
+            projectUuid: this.projectUuid,
+            host: this.host,
+            apiKey: this.maskSecret(this.apiKey),
+            apiSecret: this.maskSecret(this.apiSecret),
+            isInitialized: this.isInitialized,
+            baseMetadata: this.baseMetadata,
+            forgeConfig: this.forgeConfig
+        };
+    }
+    async testConfig() {
+        if (!this.isInitialized) {
+            return {
+                success: false,
+                error: 'Client not initialized - missing API credentials'
+            };
+        }
+        try {
+            // First verify credentials with /api/me
+            const meResponse = await axios_1.default.get(`${this.host}/api/me`, {
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}:${this.apiSecret}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+            if (meResponse.status !== 200) {
+                const error = `Credential verification failed: HTTP ${meResponse.status}`;
+                log('Failed to verify credentials: %s', error);
+                return { success: false, error };
+            }
+            const meData = meResponse.data;
+            log('Successfully verified credentials for user "%s" in team "%s"', meData.user?.name, meData.team?.name);
+            // Then verify project exists if we have a projectUuid
+            let projectExists = false;
+            let projectName;
+            let tasksVerified;
+            if (this.projectUuid) {
+                try {
+                    const projectResponse = await axios_1.default.get(`${this.host}/api/projects/${this.projectUuid}`, {
+                        headers: {
+                            'Authorization': `Bearer ${this.apiKey}:${this.apiSecret}`,
+                            'Content-Type': 'application/json'
+                        }
+                    });
+                    if (projectResponse.status === 200) {
+                        projectExists = true;
+                        projectName = projectResponse.data.project?.projectName;
+                        log('Successfully verified project "%s" exists with UUID "%s"', projectName, this.projectUuid);
+                        // Verify tasks if we have forge config
+                        if (this.forgeConfig && this.forgeConfig.tasks) {
+                            const localTasks = Object.keys(this.forgeConfig.tasks);
+                            const remoteTasks = projectResponse.data.project?.tasks || [];
+                            const remoteTaskUuids = new Set(remoteTasks.map((task) => task.uuid));
+                            const missing = [];
+                            let found = 0;
+                            for (const taskName of localTasks) {
+                                const taskUuid = this.forgeConfig.tasks[taskName].uuid;
+                                if (remoteTaskUuids.has(taskUuid)) {
+                                    found++;
+                                }
+                                else {
+                                    missing.push(taskName);
+                                }
+                            }
+                            tasksVerified = {
+                                total: localTasks.length,
+                                found,
+                                missing
+                            };
+                            log('Task verification: %d/%d tasks found, missing: %s', found, localTasks.length, missing.join(', '));
+                        }
+                    }
+                }
+                catch (projectError) {
+                    log('Project verification failed for UUID "%s": %s', this.projectUuid, projectError instanceof Error ? projectError.message : String(projectError));
+                }
+            }
+            return {
+                success: true,
+                teamName: meData.team?.name,
+                teamUuid: meData.team?.uuid,
+                userName: meData.user?.name,
+                projectName,
+                projectExists: this.projectUuid ? projectExists : undefined,
+                tasksVerified
+            };
+        }
+        catch (e) {
+            const error = e instanceof Error ? e.message : 'Network error';
+            log('Error during config test: %s', error);
+            return { success: false, error };
+        }
+    }
     mergeMetadata(record, sendLogMetadata) {
         // Start with base metadata from client
         let finalMetadata = { ...this.baseMetadata };
@@ -198,6 +307,52 @@ class HiveLogClient {
             return false;
         }
     }
+    loadForgeConfig(configPath) {
+        try {
+            if (fs_1.default.existsSync(configPath)) {
+                const configContent = fs_1.default.readFileSync(configPath, 'utf8');
+                this.forgeConfig = JSON.parse(configContent);
+                log('Found forge.json configuration at %s', configPath);
+            }
+            else {
+                log('No forge.json configuration found at %s', configPath);
+            }
+        }
+        catch (error) {
+            log('Error loading forge.json: %s', error instanceof Error ? error.message : String(error));
+        }
+    }
+    getTaskUUID(taskName) {
+        if (!this.forgeConfig) {
+            log('No forge.json configuration loaded, cannot get UUID for task "%s"', taskName);
+            return null;
+        }
+        const task = this.forgeConfig.tasks[taskName];
+        if (!task) {
+            log('Task "%s" not found in forge.json configuration', taskName);
+            return null;
+        }
+        log('Found UUID "%s" for task "%s"', task.uuid, taskName);
+        return task.uuid;
+    }
+    async sendLogByName(taskName, record, metadata) {
+        if (!this.isInitialized) {
+            log('Silent mode: Skipping sendLogByName for task "%s" - client not initialized', taskName);
+            return 'silent';
+        }
+        if (!this.projectUuid) {
+            log('Error: sendLogByName requires projectUuid to be set in client config');
+            return 'error';
+        }
+        const taskUuid = this.getTaskUUID(taskName);
+        if (!taskUuid) {
+            log('Error: Cannot find UUID for task "%s" in forge.json', taskName);
+            return 'error';
+        }
+        // Use the existing sendLogByUuid method
+        log('Sending log for task "%s" with uuid "%s"', taskName, taskUuid);
+        return await this.sendLogByUuid(record, taskUuid, metadata);
+    }
 }
 exports.HiveLogClient = HiveLogClient;
 const createHiveLogClient = (config) => {
@@ -223,10 +378,77 @@ class HiveClient {
         this.apiSecret = apiSecret;
         log('HiveClient initialized for project "%s" with host "%s"', config.projectUuid, host);
     }
-    async invoke(taskName, payload) {
+    maskSecret(secret) {
+        if (secret.length <= 8) {
+            return '****';
+        }
+        const first4 = secret.slice(0, 4);
+        const last4 = secret.slice(-4);
+        const middle = '*'.repeat(secret.length - 8);
+        return `${first4}${middle}${last4}`;
+    }
+    getConf() {
+        return {
+            projectUuid: this.projectUuid,
+            host: this.host,
+            apiKey: this.maskSecret(this.apiKey),
+            apiSecret: this.maskSecret(this.apiSecret)
+        };
+    }
+    async testConfig() {
         try {
-            const invokeUrl = `${this.host}/api/project/${this.projectUuid}/task/${taskName}/invoke`;
-            log('Invoking task "%s" at %s', taskName, invokeUrl);
+            // First verify credentials with /api/me
+            const meResponse = await axios_1.default.get(`${this.host}/api/me`, {
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}:${this.apiSecret}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+            if (meResponse.status !== 200) {
+                const error = `Credential verification failed: HTTP ${meResponse.status}`;
+                log('Failed to verify credentials: %s', error);
+                return { success: false, error };
+            }
+            const meData = meResponse.data;
+            log('Successfully verified credentials for user "%s" in team "%s"', meData.user?.name, meData.team?.name);
+            // Then verify project exists
+            let projectExists = false;
+            let projectName;
+            try {
+                const projectResponse = await axios_1.default.get(`${this.host}/api/projects/${this.projectUuid}`, {
+                    headers: {
+                        'Authorization': `Bearer ${this.apiKey}:${this.apiSecret}`,
+                        'Content-Type': 'application/json'
+                    }
+                });
+                if (projectResponse.status === 200) {
+                    projectExists = true;
+                    projectName = projectResponse.data.project?.projectName;
+                    log('Successfully verified project "%s" exists with UUID "%s"', projectName, this.projectUuid);
+                }
+            }
+            catch (projectError) {
+                log('Project verification failed for UUID "%s": %s', this.projectUuid, projectError instanceof Error ? projectError.message : String(projectError));
+            }
+            return {
+                success: true,
+                teamName: meData.team?.name,
+                teamUuid: meData.team?.uuid,
+                userName: meData.user?.name,
+                projectName,
+                projectExists
+            };
+        }
+        catch (e) {
+            const error = e instanceof Error ? e.message : 'Network error';
+            log('Error during config test: %s', error);
+            return { success: false, error };
+        }
+    }
+    async invoke(taskUuid, payload) {
+        try {
+            const invokeUrl = `${this.host}/api/projects/${this.projectUuid}/tasks/${taskUuid}/invoke`;
+            log('Invoking task UUID "%s" at %s', taskUuid, invokeUrl);
             const authToken = `${this.apiKey}:${this.apiSecret}`;
             const response = await axios_1.default.post(invokeUrl, {
                 payload
@@ -236,12 +458,12 @@ class HiveClient {
                     'Content-Type': 'application/json'
                 }
             });
-            log('Success: Invoked task "%s"', taskName);
+            log('Success: Invoked task UUID "%s"', taskUuid);
             return response.data;
         }
         catch (e) {
             const error = e;
-            log('Error: Failed to invoke task "%s": %s', taskName, error.message);
+            log('Error: Failed to invoke task UUID "%s": %s', taskUuid, error.message);
             // Check if it's an axios error with response data
             if (axios_1.default.isAxiosError(error) && error.response?.data) {
                 return error.response.data;
@@ -256,3 +478,36 @@ const createHiveClient = (config) => {
     return new HiveClient(config);
 };
 exports.createHiveClient = createHiveClient;
+/**
+ * Create a HiveLogClient from forge.json configuration
+ * @param forgeConfigPath Path to forge.json file (defaults to './forge.json')
+ * @param additionalConfig Additional config options to override forge.json values
+ * @returns HiveLogClient configured from forge.json
+ */
+const createClientFromForgeConf = (forgeConfigPath = './forge.json', additionalConfig = {}) => {
+    log('Creating HiveLogClient from forge.json at "%s"', forgeConfigPath);
+    let forgeConfig = null;
+    try {
+        if (fs_1.default.existsSync(forgeConfigPath)) {
+            const configContent = fs_1.default.readFileSync(forgeConfigPath, 'utf8');
+            forgeConfig = JSON.parse(configContent);
+            log('Loaded forge.json configuration from %s', forgeConfigPath);
+        }
+        else {
+            log('No forge.json found at %s', forgeConfigPath);
+            throw new Error(`forge.json not found at ${forgeConfigPath}`);
+        }
+    }
+    catch (error) {
+        log('Error loading forge.json: %s', error instanceof Error ? error.message : String(error));
+        throw error;
+    }
+    const config = {
+        projectName: forgeConfig.project.name,
+        projectUuid: forgeConfig.project.uuid,
+        forgeConfigPath,
+        ...additionalConfig // Allow overriding any config values
+    };
+    return new HiveLogClient(config);
+};
+exports.createClientFromForgeConf = createClientFromForgeConf;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@forgehive/hive-sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
     "access": "public",
     "dependencies": {
-      "@forgehive/task": "^0.2.6"
+      "@forgehive/task": "^0.2.7"
     }
   },
   "devDependencies": {
@@ -24,7 +24,7 @@
     "axios": "^1.8.4",
     "debug": "^4.4.1",
     "uuid": "^11.1.0",
-    "@forgehive/task": "0.2.6"
+    "@forgehive/task": "0.2.7"
   },
   "scripts": {
     "build": "tsc",

package/src/index.ts

@@ -1,10 +1,25 @@
 import axios from 'axios'
 import debug from 'debug'
 import { v7 as uuidv7 } from 'uuid'
+import fs from 'fs'
 import type { ExecutionRecord } from '@forgehive/task'
 
 const log = debug('hive-sdk')
 
+interface ForgeConfig {
+  project: {
+    name: string
+    uuid: string
+  }
+  tasks: {
+    [taskName: string]: {
+      path: string
+      handler: string
+      uuid: string
+    }
+  }
+}
+
 // Metadata interface
 export interface Metadata {
   [key: string]: string
@@ -21,6 +36,7 @@ export interface HiveLogClientConfig {
   apiSecret?: string
   host?: string
   metadata?: Metadata
+  forgeConfigPath?: string // Optional path to forge.json file
 }
 
 // API Response Types
@@ -61,6 +77,7 @@ export class HiveLogClient {
   private projectUuid: string | null
   private baseMetadata: Metadata
   private isInitialized: boolean
+  private forgeConfig: ForgeConfig | null = null
 
   constructor(config: HiveLogClientConfig) {
     const apiKey = config.apiKey || process.env.HIVE_API_KEY
@@ -84,12 +101,145 @@ export class HiveLogClient {
       this.isInitialized = true
       log('HiveLogClient initialized for project "%s" with host "%s"', config.projectName, host)
     }
+
+    // Load forge.json - use provided path or default to ./forge.json
+    const configPath = config.forgeConfigPath || './forge.json'
+    this.loadForgeConfig(configPath)
   }
 
   isActive(): boolean {
     return this.isInitialized
   }
 
+  private maskSecret(secret: string | null): string {
+    if (!secret || secret.length <= 8) {
+      return secret ? '****' : 'null'
+    }
+    const first4 = secret.slice(0, 4)
+    const last4 = secret.slice(-4)
+    const middle = '*'.repeat(secret.length - 8)
+    return `${first4}${middle}${last4}`
+  }
+
+  getConf(): Record<string, unknown> {
+    return {
+      projectName: this.projectName,
+      projectUuid: this.projectUuid,
+      host: this.host,
+      apiKey: this.maskSecret(this.apiKey),
+      apiSecret: this.maskSecret(this.apiSecret),
+      isInitialized: this.isInitialized,
+      baseMetadata: this.baseMetadata,
+      forgeConfig: this.forgeConfig
+    }
+  }
+
+  async testConfig(): Promise<{
+    success: boolean
+    teamName?: string
+    teamUuid?: string
+    userName?: string
+    projectName?: string
+    projectExists?: boolean
+    tasksVerified?: {
+      total: number
+      found: number
+      missing: string[]
+    }
+    error?: string
+  }> {
+    if (!this.isInitialized) {
+      return {
+        success: false,
+        error: 'Client not initialized - missing API credentials'
+      }
+    }
+
+    try {
+      // First verify credentials with /api/me
+      const meResponse = await axios.get(`${this.host}/api/me`, {
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}:${this.apiSecret}`,
+          'Content-Type': 'application/json'
+        }
+      })
+
+      if (meResponse.status !== 200) {
+        const error = `Credential verification failed: HTTP ${meResponse.status}`
+        log('Failed to verify credentials: %s', error)
+        return { success: false, error }
+      }
+
+      const meData = meResponse.data
+      log('Successfully verified credentials for user "%s" in team "%s"', meData.user?.name, meData.team?.name)
+
+      // Then verify project exists if we have a projectUuid
+      let projectExists = false
+      let projectName: string | undefined
+      let tasksVerified: { total: number; found: number; missing: string[] } | undefined
+
+      if (this.projectUuid) {
+        try {
+          const projectResponse = await axios.get(`${this.host}/api/projects/${this.projectUuid}`, {
+            headers: {
+              'Authorization': `Bearer ${this.apiKey}:${this.apiSecret}`,
+              'Content-Type': 'application/json'
+            }
+          })
+
+          if (projectResponse.status === 200) {
+            projectExists = true
+            projectName = projectResponse.data.project?.projectName
+            log('Successfully verified project "%s" exists with UUID "%s"', projectName, this.projectUuid)
+
+            // Verify tasks if we have forge config
+            if (this.forgeConfig && this.forgeConfig.tasks) {
+              const localTasks = Object.keys(this.forgeConfig.tasks)
+              const remoteTasks = projectResponse.data.project?.tasks || []
+              const remoteTaskUuids = new Set(remoteTasks.map((task: { uuid: string }) => task.uuid))
+
+              const missing: string[] = []
+              let found = 0
+
+              for (const taskName of localTasks) {
+                const taskUuid = this.forgeConfig.tasks[taskName].uuid
+                if (remoteTaskUuids.has(taskUuid)) {
+                  found++
+                } else {
+                  missing.push(taskName)
+                }
+              }
+
+              tasksVerified = {
+                total: localTasks.length,
+                found,
+                missing
+              }
+
+              log('Task verification: %d/%d tasks found, missing: %s', found, localTasks.length, missing.join(', '))
+            }
+          }
+        } catch (projectError) {
+          log('Project verification failed for UUID "%s": %s', this.projectUuid, projectError instanceof Error ? projectError.message : String(projectError))
+        }
+      }
+
+      return {
+        success: true,
+        teamName: meData.team?.name,
+        teamUuid: meData.team?.uuid,
+        userName: meData.user?.name,
+        projectName,
+        projectExists: this.projectUuid ? projectExists : undefined,
+        tasksVerified
+      }
+    } catch (e) {
+      const error = e instanceof Error ? e.message : 'Network error'
+      log('Error during config test: %s', error)
+      return { success: false, error }
+    }
+  }
+
   private mergeMetadata(record: ExecutionRecord, sendLogMetadata?: Metadata): Metadata {
     // Start with base metadata from client
     let finalMetadata = { ...this.baseMetadata }
@@ -280,6 +430,58 @@ export class HiveLogClient {
       return false
     }
   }
+
+  private loadForgeConfig(configPath: string): void {
+    try {
+      if (fs.existsSync(configPath)) {
+        const configContent = fs.readFileSync(configPath, 'utf8')
+        this.forgeConfig = JSON.parse(configContent) as ForgeConfig
+        log('Found forge.json configuration at %s', configPath)
+      } else {
+        log('No forge.json configuration found at %s', configPath)
+      }
+    } catch (error) {
+      log('Error loading forge.json: %s', error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  private getTaskUUID(taskName: string): string | null {
+    if (!this.forgeConfig) {
+      log('No forge.json configuration loaded, cannot get UUID for task "%s"', taskName)
+      return null
+    }
+
+    const task = this.forgeConfig.tasks[taskName]
+    if (!task) {
+      log('Task "%s" not found in forge.json configuration', taskName)
+      return null
+    }
+
+    log('Found UUID "%s" for task "%s"', task.uuid, taskName)
+    return task.uuid
+  }
+
+  async sendLogByName(taskName: string, record: ExecutionRecord, metadata?: Metadata): Promise<'success' | 'error' | 'silent' | LogApiSuccess> {
+    if (!this.isInitialized) {
+      log('Silent mode: Skipping sendLogByName for task "%s" - client not initialized', taskName)
+      return 'silent'
+    }
+
+    if (!this.projectUuid) {
+      log('Error: sendLogByName requires projectUuid to be set in client config')
+      return 'error'
+    }
+
+    const taskUuid = this.getTaskUUID(taskName)
+    if (!taskUuid) {
+      log('Error: Cannot find UUID for task "%s" in forge.json', taskName)
+      return 'error'
+    }
+
+    // Use the existing sendLogByUuid method
+    log('Sending log for task "%s" with uuid "%s"', taskName, taskUuid)
+    return await this.sendLogByUuid(record, taskUuid, metadata)
+  }
 }
 
 export const createHiveLogClient = (config: HiveLogClientConfig): HiveLogClient => {
@@ -334,10 +536,97 @@ export class HiveClient {
     log('HiveClient initialized for project "%s" with host "%s"', config.projectUuid, host)
   }
 
-  async invoke(taskName: string, payload: unknown): Promise<InvokeResult | null> {
+  private maskSecret(secret: string): string {
+    if (secret.length <= 8) {
+      return '****'
+    }
+    const first4 = secret.slice(0, 4)
+    const last4 = secret.slice(-4)
+    const middle = '*'.repeat(secret.length - 8)
+    return `${first4}${middle}${last4}`
+  }
+
+  getConf(): Record<string, unknown> {
+    return {
+      projectUuid: this.projectUuid,
+      host: this.host,
+      apiKey: this.maskSecret(this.apiKey),
+      apiSecret: this.maskSecret(this.apiSecret)
+    }
+  }
+
+  async testConfig(): Promise<{
+    success: boolean
+    teamName?: string
+    teamUuid?: string
+    userName?: string
+    projectName?: string
+    projectExists?: boolean
+    tasksVerified?: {
+      total: number
+      found: number
+      missing: string[]
+    }
+    error?: string
+  }> {
     try {
-      const invokeUrl = `${this.host}/api/project/${this.projectUuid}/task/${taskName}/invoke`
-      log('Invoking task "%s" at %s', taskName, invokeUrl)
+      // First verify credentials with /api/me
+      const meResponse = await axios.get(`${this.host}/api/me`, {
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}:${this.apiSecret}`,
+          'Content-Type': 'application/json'
+        }
+      })
+
+      if (meResponse.status !== 200) {
+        const error = `Credential verification failed: HTTP ${meResponse.status}`
+        log('Failed to verify credentials: %s', error)
+        return { success: false, error }
+      }
+
+      const meData = meResponse.data
+      log('Successfully verified credentials for user "%s" in team "%s"', meData.user?.name, meData.team?.name)
+
+      // Then verify project exists
+      let projectExists = false
+      let projectName: string | undefined
+
+      try {
+        const projectResponse = await axios.get(`${this.host}/api/projects/${this.projectUuid}`, {
+          headers: {
+            'Authorization': `Bearer ${this.apiKey}:${this.apiSecret}`,
+            'Content-Type': 'application/json'
+          }
+        })
+
+        if (projectResponse.status === 200) {
+          projectExists = true
+          projectName = projectResponse.data.project?.projectName
+          log('Successfully verified project "%s" exists with UUID "%s"', projectName, this.projectUuid)
+        }
+      } catch (projectError) {
+        log('Project verification failed for UUID "%s": %s', this.projectUuid, projectError instanceof Error ? projectError.message : String(projectError))
+      }
+
+      return {
+        success: true,
+        teamName: meData.team?.name,
+        teamUuid: meData.team?.uuid,
+        userName: meData.user?.name,
+        projectName,
+        projectExists
+      }
+    } catch (e) {
+      const error = e instanceof Error ? e.message : 'Network error'
+      log('Error during config test: %s', error)
+      return { success: false, error }
+    }
+  }
+
+  async invoke(taskUuid: string, payload: unknown): Promise<InvokeResult | null> {
+    try {
+      const invokeUrl = `${this.host}/api/projects/${this.projectUuid}/tasks/${taskUuid}/invoke`
+      log('Invoking task UUID "%s" at %s', taskUuid, invokeUrl)
 
       const authToken = `${this.apiKey}:${this.apiSecret}`
 
@@ -350,11 +639,11 @@ export class HiveClient {
         }
       })
 
-      log('Success: Invoked task "%s"', taskName)
+      log('Success: Invoked task UUID "%s"', taskUuid)
       return response.data as InvokeResult
     } catch (e) {
       const error = e as Error
-      log('Error: Failed to invoke task "%s": %s', taskName, error.message)
+      log('Error: Failed to invoke task UUID "%s": %s', taskUuid, error.message)
 
       // Check if it's an axios error with response data
       if (axios.isAxiosError(error) && error.response?.data) {
@@ -370,3 +659,41 @@ export const createHiveClient = (config: HiveClientConfig): HiveClient => {
   log('Creating HiveClient for project "%s"', config.projectUuid)
   return new HiveClient(config)
 }
+
+/**
+ * Create a HiveLogClient from forge.json configuration
+ * @param forgeConfigPath Path to forge.json file (defaults to './forge.json')
+ * @param additionalConfig Additional config options to override forge.json values
+ * @returns HiveLogClient configured from forge.json
+ */
+export const createClientFromForgeConf = (
+  forgeConfigPath: string = './forge.json',
+  additionalConfig: Partial<HiveLogClientConfig> = {}
+): HiveLogClient => {
+  log('Creating HiveLogClient from forge.json at "%s"', forgeConfigPath)
+
+  let forgeConfig: ForgeConfig | null = null
+
+  try {
+    if (fs.existsSync(forgeConfigPath)) {
+      const configContent = fs.readFileSync(forgeConfigPath, 'utf8')
+      forgeConfig = JSON.parse(configContent) as ForgeConfig
+      log('Loaded forge.json configuration from %s', forgeConfigPath)
+    } else {
+      log('No forge.json found at %s', forgeConfigPath)
+      throw new Error(`forge.json not found at ${forgeConfigPath}`)
+    }
+  } catch (error) {
+    log('Error loading forge.json: %s', error instanceof Error ? error.message : String(error))
+    throw error
+  }
+
+  const config: HiveLogClientConfig = {
+    projectName: forgeConfig.project.name,
+    projectUuid: forgeConfig.project.uuid,
+    forgeConfigPath,
+    ...additionalConfig // Allow overriding any config values
+  }
+
+  return new HiveLogClient(config)
+}