@forgehive/hive-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ForgeHive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,357 @@
+# Hive SDK
+
+A TypeScript/JavaScript SDK for interacting with the Forge Hive logging and quality assessment platform.
+
+## Installation
+
+```bash
+npm install @forgehive/hive-sdk
+```
+
+or with pnpm:
+
+```bash
+pnpm add @forgehive/hive-sdk
+```
+
+## Setup
+
+### 1. Environment Variables
+
+Before using the SDK, you need to set up the following environment variables:
+
+```bash
+HIVE_API_KEY=your_api_key_here
+HIVE_API_SECRET=your_api_secret_here
+HIVE_HOST=https://your-hive-instance.com
+```
+
+You can get your API credentials at [https://forgehive.dev](https://forgehive.dev).
+
+### 2. Basic Usage
+
+```typescript
+import { createHiveLogClient } from '@forgehive/hive-sdk'
+
+const hiveLogger = createHiveLogClient('Personal Knowledge Management System')
+```
+
+## API Methods
+
+### `isActive(): boolean`
+
+Check if the client is properly initialized with credentials.
+
+```typescript
+const hiveLogger = createHiveLogClient('My Project')
+
+if (hiveLogger.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: unknown): Promise<'success' | 'error' | 'silent'>`
+
+Sends a log entry to Hive for a specific task.
+
+```typescript
+const status = await hiveLogger.sendLog('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
+      }
+    ]
+  }
+})
+
+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
+}
+```
+
+**Parameters:**
+- `taskName`: Name of the task being logged
+- `logItem`: Object containing input, output, error, and boundaries data
+
+**Returns:** `Promise<'success' | 'error' | 'silent'>` - Status of the operation
+
+### `getLog(taskName: string, uuid: string): Promise<LogApiResult | null>`
+
+Retrieves a specific log entry from Hive.
+
+```typescript
+try {
+  const logData = await hiveLogger.getLog('user-authentication', 'log-uuid-123')
+
+  if (logData && !isApiError(logData)) {
+    console.log('Log retrieved:', logData.logItem)
+  } 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)
+}
+```
+
+**Parameters:**
+- `taskName`: Name of the task
+- `uuid`: Unique identifier of the log entry
+
+**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>`
+
+Sets a quality assessment for a specific log entry.
+
+```typescript
+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 for better performance'
+}
+
+try {
+  const success = await hiveLogger.setQuality('user-authentication', 'log-uuid-123', quality)
+
+  if (success) {
+    console.log('Quality assessment saved')
+  } else {
+    console.error('Failed to save quality assessment')
+  }
+} catch (error) {
+  console.error('Missing credentials:', error.message)
+}
+```
+
+**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)
+
+**Returns:** `Promise<boolean>` - `true` if successful, `false` if failed
+**Throws:** Error when credentials are missing
+
+## Types
+
+### `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 }>>
+  }
+  replayFrom?: string
+  createdAt: string
+}
+```
+
+### `Quality`
+
+```typescript
+interface Quality {
+  score: number        // Quality score (typically 0-10)
+  reason: string       // Explanation for the score
+  suggestions: string  // Suggestions for improvement
+}
+```
+
+### `ApiError`
+
+```typescript
+interface ApiError {
+  error: string
+}
+```
+
+## Type Guards
+
+### `isApiError(response: unknown): response is ApiError`
+
+Use this type guard to check if a response is an error:
+
+```typescript
+import { isApiError } from '@forgehive/hive-sdk'
+
+const result = await hiveLogger.getLog('task-name', 'log-uuid')
+
+if (result && isApiError(result)) {
+  console.error('Error:', result.error)
+} else if (result) {
+  console.log('Success:', result.logItem)
+}
+```
+
+## Debugging
+
+The SDK uses the `debug` package for internal logging. To enable debug logs, set the `DEBUG` environment variable:
+
+```bash
+# Enable all hive-sdk debug logs
+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:
+
+```
+# 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://forgehive.dev) +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
+```
+
+## Error Handling
+
+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
+
+```typescript
+// sendLog works even without credentials (returns 'silent')
+const hiveLogger = createHiveLogClient('My Project')
+
+const status = await hiveLogger.sendLog('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
+
+**Check credentials before API calls:**
+```typescript
+const hiveLogger = createHiveLogClient('My Project')
+
+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')
+}
+```
+
+**sendLog** - Returns status strings (never throws):
+```typescript
+const status = await hiveLogger.sendLog('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)
+}
+```
+
+## Examples
+
+### Complete Example
+
+```typescript
+import { createHiveLogClient, isApiError, Quality } from '@forgehive/hive-sdk'
+
+async function main() {
+  // Initialize the client
+  const hiveLogger = createHiveLogClient('Personal Knowledge Management System')
+
+  // Send a log
+  const logData = {
+    input: { query: 'search for AI papers', userId: 123 },
+    output: { results: ['paper1.pdf', 'paper2.pdf'], count: 2 },
+    boundaries: {
+      search_engine: [
+        {
+          input: 'AI papers filetype:pdf',
+          output: { hits: 150, results: ['...'] },
+          error: null
+        }
+      ]
+    }
+  }
+
+  const status = await hiveLogger.sendLog('document-search', logData)
+  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)
+
+      // 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)
+  }
+}
+
+main().catch(console.error)
+```
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+export 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;
+        }>>;
+    };
+    replayFrom?: string;
+    createdAt: string;
+}
+export interface ApiError {
+    error: string;
+}
+export interface LogApiSuccess extends LogApiResponse {
+}
+export type LogApiResult = LogApiSuccess | ApiError;
+export interface Quality {
+    score: number;
+    reason: string;
+    suggestions: string;
+}
+export declare function isApiError(response: unknown): response is ApiError;
+export declare class HiveLogClient {
+    private apiKey;
+    private apiSecret;
+    private host;
+    private projectName;
+    private isInitialized;
+    constructor(projectName: string);
+    isActive(): boolean;
+    sendLog(taskName: string, logItem: unknown): Promise<'success' | 'error' | 'silent'>;
+    getLog(taskName: string, uuid: string): Promise<LogApiResult | null>;
+    setQuality(taskName: string, uuid: string, quality: Quality): Promise<boolean>;
+}
+export declare const createHiveLogClient: (projectName: string) => HiveLogClient;

package/dist/index.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHiveLogClient = exports.HiveLogClient = void 0;
+exports.isApiError = isApiError;
+const axios_1 = __importDefault(require("axios"));
+const debug_1 = __importDefault(require("debug"));
+const log = (0, debug_1.default)('hive-sdk');
+// Type guard to check if response is an error
+function isApiError(response) {
+    return response !== null && typeof response === 'object' && 'error' in response;
+}
+class HiveLogClient {
+    constructor(projectName) {
+        const apiKey = process.env.HIVE_API_KEY;
+        const apiSecret = process.env.HIVE_API_SECRET;
+        const host = process.env.HIVE_HOST;
+        this.projectName = projectName;
+        if (!apiKey || !apiSecret || !host) {
+            this.apiKey = null;
+            this.apiSecret = null;
+            this.host = null;
+            this.isInitialized = false;
+            log('HiveLogClient in silent mode for project "%s" - missing credentials (get them at https://forgehive.dev)', projectName);
+        }
+        else {
+            this.apiKey = apiKey;
+            this.apiSecret = apiSecret;
+            this.host = host;
+            this.isInitialized = true;
+            log('HiveLogClient initialized for project "%s" with host "%s"', projectName, host);
+        }
+    }
+    isActive() {
+        return this.isInitialized;
+    }
+    async sendLog(taskName, logItem) {
+        if (!this.isInitialized) {
+            log('Silent mode: Skipping sendLog for task "%s" - client not initialized', taskName);
+            return 'silent';
+        }
+        try {
+            const logsUrl = `${this.host}/api/tasks/log-ingest`;
+            log('Sending log for task "%s" to %s', taskName, logsUrl);
+            const authToken = `${this.apiKey}:${this.apiSecret}`;
+            await axios_1.default.post(logsUrl, {
+                projectName: this.projectName,
+                taskName,
+                logItem: JSON.stringify(logItem)
+            }, {
+                headers: {
+                    Authorization: `Bearer ${authToken}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+            log('Success: Sent log for task "%s"', taskName);
+            return 'success';
+        }
+        catch (e) {
+            const error = e;
+            log('Error: Failed to send log for task "%s": %s', taskName, error.message);
+            return 'error';
+        }
+    }
+    async getLog(taskName, uuid) {
+        if (!this.isInitialized) {
+            log('Error: getLog for task "%s" with uuid "%s" - missing credentials', taskName, uuid);
+            throw new Error('Missing Hive API credentials or host, get them at https://forgehive.dev');
+        }
+        try {
+            const logUrl = `${this.host}/api/tasks/${taskName}/logs/${uuid}`;
+            log('Fetching log for task "%s" with uuid "%s" from %s', taskName, uuid, logUrl);
+            const authToken = `${this.apiKey}:${this.apiSecret}`;
+            const response = await axios_1.default.get(logUrl, {
+                headers: {
+                    Authorization: `Bearer ${authToken}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+            log('Success: Fetched log for task "%s" with uuid "%s"', taskName, uuid);
+            return response.data;
+        }
+        catch (e) {
+            const error = e;
+            log('Error: Failed to fetch log for task "%s" with uuid "%s": %s', taskName, uuid, error.message);
+            return null;
+        }
+    }
+    async setQuality(taskName, uuid, quality) {
+        if (!this.isInitialized) {
+            log('Error: setQuality for task "%s" with uuid "%s" - missing credentials', taskName, uuid);
+            throw new Error('Missing Hive API credentials or host, get them at https://forgehive.dev');
+        }
+        try {
+            const qualityUrl = `${this.host}/api/tasks/${taskName}/logs/${uuid}/set-quality`;
+            log('Setting quality for task "%s" with uuid "%s" (score: %d) to %s', taskName, uuid, quality.score, qualityUrl);
+            const authToken = `${this.apiKey}:${this.apiSecret}`;
+            await axios_1.default.post(qualityUrl, {
+                quality
+            }, {
+                headers: {
+                    Authorization: `Bearer ${authToken}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+            log('Success: Set quality for task "%s" with uuid "%s" (score: %d)', taskName, uuid, quality.score);
+            return true;
+        }
+        catch (e) {
+            const error = e;
+            log('Error: Failed to set quality for task "%s" with uuid "%s": %s', taskName, uuid, error.message);
+            return false;
+        }
+    }
+}
+exports.HiveLogClient = HiveLogClient;
+const createHiveLogClient = (projectName) => {
+    log('Creating HiveLogClient for project "%s"', projectName);
+    return new HiveLogClient(projectName);
+};
+exports.createHiveLogClient = createHiveLogClient;

package/dist/test/getLog.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/getLog.test.js

@@ -0,0 +1,144 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const axios_1 = __importDefault(require("axios"));
+const index_1 = require("../index");
+// Mock axios
+jest.mock('axios');
+const mockedAxios = axios_1.default;
+describe('HiveLogClient getLog', () => {
+    const originalEnv = process.env;
+    let client;
+    beforeEach(() => {
+        jest.resetModules();
+        process.env = { ...originalEnv };
+        // Set up environment variables
+        process.env.HIVE_API_KEY = 'test-api-key';
+        process.env.HIVE_API_SECRET = 'test-api-secret';
+        process.env.HIVE_HOST = 'https://test-host.com';
+        // Create client instance
+        client = new index_1.HiveLogClient('test-project');
+        // Clear all mocks
+        jest.clearAllMocks();
+    });
+    afterAll(() => {
+        process.env = originalEnv;
+    });
+    describe('successful getLog', () => {
+        it('should fetch log successfully and return LogApiResponse', async () => {
+            const mockLogResponse = {
+                uuid: 'test-uuid-123',
+                taskName: 'test-task',
+                projectName: 'test-project',
+                logItem: {
+                    input: { userId: 123, action: 'login' },
+                    output: { success: true, sessionId: 'abc123' },
+                    error: null,
+                    boundaries: {
+                        database: [{ input: 'SELECT * FROM users', output: [{ id: 123 }], error: null }]
+                    }
+                },
+                replayFrom: 'some-replay-id',
+                createdAt: '2023-12-01T10:00:00Z'
+            };
+            // Mock successful axios response
+            mockedAxios.get.mockResolvedValueOnce({ data: mockLogResponse });
+            const result = await client.getLog('test-task', 'test-uuid-123');
+            expect(result).toEqual(mockLogResponse);
+            expect(mockedAxios.get).toHaveBeenCalledTimes(1);
+            expect(mockedAxios.get).toHaveBeenCalledWith('https://test-host.com/api/tasks/test-task/logs/test-uuid-123', {
+                headers: {
+                    Authorization: 'Bearer test-api-key:test-api-secret',
+                    'Content-Type': 'application/json'
+                }
+            });
+        });
+        it('should handle API error response', async () => {
+            const mockErrorResponse = {
+                error: 'Log not found'
+            };
+            mockedAxios.get.mockResolvedValueOnce({ data: mockErrorResponse });
+            const result = await client.getLog('test-task', 'non-existent-uuid');
+            expect(result).toEqual(mockErrorResponse);
+            expect((0, index_1.isApiError)(result)).toBe(true);
+        });
+        it('should handle minimal log response', async () => {
+            const mockMinimalResponse = {
+                uuid: 'minimal-uuid',
+                taskName: 'minimal-task',
+                projectName: 'test-project',
+                logItem: {
+                    input: 'simple input'
+                },
+                createdAt: '2023-12-01T10:00:00Z'
+            };
+            mockedAxios.get.mockResolvedValueOnce({ data: mockMinimalResponse });
+            const result = await client.getLog('minimal-task', 'minimal-uuid');
+            expect(result).toEqual(mockMinimalResponse);
+            expect((0, index_1.isApiError)(result)).toBe(false);
+        });
+    });
+    describe('failed getLog', () => {
+        it('should return null when axios throws an error', async () => {
+            // Mock axios to throw an error
+            mockedAxios.get.mockRejectedValueOnce(new Error('Network error'));
+            const result = await client.getLog('test-task', 'test-uuid');
+            expect(result).toBeNull();
+        });
+        it('should return null when server returns 404', async () => {
+            // Mock axios to throw a 404 error
+            const notFoundError = new Error('Request failed with status code 404');
+            mockedAxios.get.mockRejectedValueOnce(notFoundError);
+            const result = await client.getLog('test-task', 'non-existent-uuid');
+            expect(result).toBeNull();
+        });
+        it('should return null when server returns 500', async () => {
+            // Mock axios to throw a server error
+            const serverError = new Error('Server Error');
+            mockedAxios.get.mockRejectedValueOnce(serverError);
+            const result = await client.getLog('test-task', 'test-uuid');
+            expect(result).toBeNull();
+        });
+    });
+    describe('getLog parameters', () => {
+        it('should handle special characters in taskName and uuid', async () => {
+            const mockResponse = {
+                uuid: 'uuid-with-special-chars-!@#',
+                taskName: 'task-with-special-chars-!@#',
+                projectName: 'test-project',
+                logItem: { input: 'test' },
+                createdAt: '2023-12-01T10:00:00Z'
+            };
+            mockedAxios.get.mockResolvedValueOnce({ data: mockResponse });
+            const result = await client.getLog('task-with-special-chars-!@#', 'uuid-with-special-chars-!@#');
+            expect(result).toEqual(mockResponse);
+            expect(mockedAxios.get).toHaveBeenCalledWith('https://test-host.com/api/tasks/task-with-special-chars-!@#/logs/uuid-with-special-chars-!@#', expect.any(Object));
+        });
+    });
+});
+describe('isApiError type guard', () => {
+    it('should return true for ApiError objects', () => {
+        const apiError = { error: 'Something went wrong' };
+        expect((0, index_1.isApiError)(apiError)).toBe(true);
+    });
+    it('should return false for LogApiResponse objects', () => {
+        const logResponse = {
+            uuid: 'test-uuid',
+            taskName: 'test-task',
+            projectName: 'test-project',
+            logItem: { input: 'test' },
+            createdAt: '2023-12-01T10:00:00Z'
+        };
+        expect((0, index_1.isApiError)(logResponse)).toBe(false);
+    });
+    it('should return false for null or undefined', () => {
+        expect((0, index_1.isApiError)(null)).toBeFalsy();
+        expect((0, index_1.isApiError)(undefined)).toBeFalsy();
+    });
+    it('should return false for objects without error property', () => {
+        expect((0, index_1.isApiError)({ success: true })).toBe(false);
+        expect((0, index_1.isApiError)({ data: 'some data' })).toBe(false);
+    });
+});

package/dist/test/index.test.d.ts

@@ -0,0 +1 @@
+export {};