@forgehive/hive-sdk 0.0.1 → 0.0.3

package/src/index.ts

@@ -3,6 +3,32 @@ import debug from 'debug'
 
 const log = debug('hive-sdk')
 
+// Metadata interface
+export interface Metadata {
+  [key: string]: string
+}
+
+// Log item interface for sendLog method - flexible to accept task execution records
+export interface LogItemInput {
+  input: unknown
+  output?: unknown
+  error?: unknown
+  boundaries?: unknown // Allow any boundary structure (task records have different format)
+  metadata?: Metadata
+}
+
+// Backward compatibility alias
+export type LogItem = LogItemInput
+
+// Configuration interface for HiveLogClient
+export interface HiveLogClientConfig {
+  projectName: string
+  apiKey?: string
+  apiSecret?: string
+  host?: string
+  metadata?: Metadata
+}
+
 // API Response Types
 export interface LogApiResponse {
   uuid: string
@@ -13,6 +39,7 @@ export interface LogApiResponse {
     output?: unknown
     error?: unknown
     boundaries?: Record<string, Array<{ input: unknown; output: unknown, error: unknown }>>
+    metadata?: Metadata
   }
   replayFrom?: string
   createdAt: string
@@ -43,27 +70,29 @@ export class HiveLogClient {
   private apiSecret: string | null
   private host: string | null
   private projectName: string
+  private baseMetadata: Metadata
   private isInitialized: boolean
 
-  constructor(projectName: string) {
-    const apiKey = process.env.HIVE_API_KEY
-    const apiSecret = process.env.HIVE_API_SECRET
-    const host = process.env.HIVE_HOST
+  constructor(config: HiveLogClientConfig) {
+    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'
 
-    this.projectName = projectName
+    this.projectName = config.projectName
+    this.baseMetadata = config.metadata || {}
 
-    if (!apiKey || !apiSecret || !host) {
+    if (!apiKey || !apiSecret) {
       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)
+      log('HiveLogClient in silent mode for project "%s" - missing API credentials (get them at https://www.forgehive.cloud)', config.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)
+      log('HiveLogClient initialized for project "%s" with host "%s"', config.projectName, host)
     }
   }
 
@@ -71,7 +100,24 @@ export class HiveLogClient {
     return this.isInitialized
   }
 
-  async sendLog(taskName: string, logItem: unknown): Promise<'success' | 'error' | 'silent'> {
+  private mergeMetadata<T extends { input: unknown; metadata?: Metadata }>(logItem: T, sendLogMetadata?: Metadata): Metadata {
+    // Start with base metadata from client
+    let finalMetadata = { ...this.baseMetadata }
+
+    // Merge with logItem metadata if it exists
+    if (logItem.metadata) {
+      finalMetadata = { ...finalMetadata, ...logItem.metadata }
+    }
+
+    // Merge with sendLog metadata (highest priority)
+    if (sendLogMetadata) {
+      finalMetadata = { ...finalMetadata, ...sendLogMetadata }
+    }
+
+    return finalMetadata
+  }
+
+  async sendLog<T extends { input: unknown; metadata?: Metadata }>(taskName: string, logItem: T, metadata?: Metadata): Promise<'success' | 'error' | 'silent'> {
     if (!this.isInitialized) {
       log('Silent mode: Skipping sendLog for task "%s" - client not initialized', taskName)
       return 'silent'
@@ -83,10 +129,19 @@ export class HiveLogClient {
 
       const authToken = `${this.apiKey}:${this.apiSecret}`
 
+      // Merge metadata with priority: sendLog > logItem > client
+      const finalMetadata = this.mergeMetadata(logItem, metadata)
+
+      // Create enhanced logItem with merged metadata
+      const enhancedLogItem = {
+        ...logItem,
+        metadata: finalMetadata
+      }
+
       await axios.post(logsUrl, {
         projectName: this.projectName,
         taskName,
-        logItem: JSON.stringify(logItem)
+        logItem: JSON.stringify(enhancedLogItem)
       }, {
         headers: {
           Authorization: `Bearer ${authToken}`,
@@ -106,7 +161,7 @@ export class HiveLogClient {
   async getLog(taskName: string, uuid: string): Promise<LogApiResult | null> {
     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')
+      throw new Error('Missing Hive API credentials or host, get them at https://www.forgehive.cloud')
     }
 
     try {
@@ -134,7 +189,7 @@ export class HiveLogClient {
   async setQuality(taskName: string, uuid: string, quality: Quality): Promise<boolean> {
     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')
+      throw new Error('Missing Hive API credentials or host, get them at https://www.forgehive.cloud')
     }
 
     try {
@@ -162,7 +217,91 @@ export class HiveLogClient {
   }
 }
 
-export const createHiveLogClient = (projectName: string): HiveLogClient => {
-  log('Creating HiveLogClient for project "%s"', projectName)
-  return new HiveLogClient(projectName)
+export const createHiveLogClient = (config: HiveLogClientConfig): HiveLogClient => {
+  log('Creating HiveLogClient for project "%s"', config.projectName)
+  return new HiveLogClient(config)
+}
+
+// Configuration interface for HiveClient
+export interface HiveClientConfig {
+  projectUuid: string
+  apiKey?: string
+  apiSecret?: string
+  host?: string
+}
+
+// Response types for invoke method
+export interface InvokeResponse {
+  responsePayload: unknown
+}
+
+export interface InvokeError {
+  error: string
+}
+
+export type InvokeResult = InvokeResponse | InvokeError
+
+// Type guard to check if invoke response is an error
+export function isInvokeError(response: unknown): response is InvokeError {
+  return response !== null && typeof response === 'object' && 'error' in response
+}
+
+export class HiveClient {
+  private apiKey: string
+  private apiSecret: string
+  private host: string
+  private projectUuid: string
+
+  constructor(config: HiveClientConfig) {
+    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://forgehive.dev'
+
+    if (!apiKey || !apiSecret) {
+      throw new Error('Missing Hive API credentials. Please provide apiKey and apiSecret, or set HIVE_API_KEY and HIVE_API_SECRET environment variables. Get them at https://forgehive.dev')
+    }
+
+    this.projectUuid = config.projectUuid
+    this.host = host
+    this.apiKey = apiKey
+    this.apiSecret = apiSecret
+
+    log('HiveClient initialized for project "%s" with host "%s"', config.projectUuid, host)
+  }
+
+  async invoke(taskName: string, payload: unknown): Promise<InvokeResult | null> {
+    try {
+      const invokeUrl = `${this.host}/api/project/${this.projectUuid}/task/${taskName}/invoke`
+      log('Invoking task "%s" at %s', taskName, invokeUrl)
+
+      const authToken = `${this.apiKey}:${this.apiSecret}`
+
+      const response = await axios.post(invokeUrl, {
+        payload
+      }, {
+        headers: {
+          Authorization: `Bearer ${authToken}`,
+          'Content-Type': 'application/json'
+        }
+      })
+
+      log('Success: Invoked task "%s"', taskName)
+      return response.data as InvokeResult
+    } catch (e) {
+      const error = e as Error
+      log('Error: Failed to invoke task "%s": %s', taskName, error.message)
+
+      // Check if it's an axios error with response data
+      if (axios.isAxiosError(error) && error.response?.data) {
+        return error.response.data as InvokeError
+      }
+
+      return { error: error.message }
+    }
+  }
+}
+
+export const createHiveClient = (config: HiveClientConfig): HiveClient => {
+  log('Creating HiveClient for project "%s"', config.projectUuid)
+  return new HiveClient(config)
 }

package/src/test/getLog.test.ts

@@ -6,29 +6,23 @@ jest.mock('axios')
 const mockedAxios = axios as jest.Mocked<typeof axios>
 
 describe('HiveLogClient getLog', () => {
-  const originalEnv = process.env
   let client: HiveLogClient
 
-  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'
+  const testConfig = {
+    projectName: 'test-project',
+    apiKey: 'test-api-key',
+    apiSecret: 'test-api-secret',
+    host: 'https://test-host.com'
+  }
 
-    // Create client instance
-    client = new HiveLogClient('test-project')
+  beforeEach(() => {
+    // Create client instance with config
+    client = new HiveLogClient(testConfig)
 
     // Clear all mocks
     jest.clearAllMocks()
   })
 
-  afterAll(() => {
-    process.env = originalEnv
-  })
-
   describe('successful getLog', () => {
     it('should fetch log successfully and return LogApiResponse', async () => {
       const mockLogResponse: LogApiResponse = {

package/src/test/index.test.ts

@@ -18,7 +18,7 @@ describe('Hive SDK', () => {
       process.env.HIVE_API_SECRET = 'test-secret'
       process.env.HIVE_HOST = 'https://test.com'
 
-      expect(() => new HiveLogClient('test-project')).not.toThrow()
+      expect(() => new HiveLogClient({ projectName: 'test-project' })).not.toThrow()
     })
 
     it('should create client in silent mode when HIVE_API_SECRET is missing', () => {
@@ -26,7 +26,7 @@ describe('Hive SDK', () => {
       delete process.env.HIVE_API_SECRET
       process.env.HIVE_HOST = 'https://test.com'
 
-      expect(() => new HiveLogClient('test-project')).not.toThrow()
+      expect(() => new HiveLogClient({ projectName: 'test-project' })).not.toThrow()
     })
 
     it('should create client in silent mode when HIVE_HOST is missing', () => {
@@ -34,7 +34,7 @@ describe('Hive SDK', () => {
       process.env.HIVE_API_SECRET = 'test-secret'
       delete process.env.HIVE_HOST
 
-      expect(() => new HiveLogClient('test-project')).not.toThrow()
+      expect(() => new HiveLogClient({ projectName: 'test-project' })).not.toThrow()
     })
 
     it('should create client in silent mode when all environment variables are missing', () => {
@@ -42,7 +42,7 @@ describe('Hive SDK', () => {
       delete process.env.HIVE_API_SECRET
       delete process.env.HIVE_HOST
 
-      expect(() => new HiveLogClient('test-project')).not.toThrow()
+      expect(() => new HiveLogClient({ projectName: 'test-project' })).not.toThrow()
     })
 
     it('should create client successfully when all environment variables are present', () => {
@@ -50,7 +50,7 @@ describe('Hive SDK', () => {
       process.env.HIVE_API_SECRET = 'test-secret'
       process.env.HIVE_HOST = 'https://test.com'
 
-      expect(() => new HiveLogClient('test-project')).not.toThrow()
+      expect(() => new HiveLogClient({ projectName: 'test-project' })).not.toThrow()
     })
   })
 
@@ -60,7 +60,7 @@ describe('Hive SDK', () => {
       delete process.env.HIVE_API_SECRET
       delete process.env.HIVE_HOST
 
-      const client = new HiveLogClient('test-project')
+      const client = new HiveLogClient({ projectName: 'test-project' })
       expect(client.isActive()).toBe(false)
     })
 
@@ -69,7 +69,7 @@ describe('Hive SDK', () => {
       process.env.HIVE_API_SECRET = 'test-secret'
       process.env.HIVE_HOST = 'https://test.com'
 
-      const client = new HiveLogClient('test-project')
+      const client = new HiveLogClient({ projectName: 'test-project' })
       expect(client.isActive()).toBe(true)
     })
   })
@@ -80,7 +80,7 @@ describe('Hive SDK', () => {
       process.env.HIVE_API_SECRET = 'test-secret'
       process.env.HIVE_HOST = 'https://test.com'
 
-      const client = createHiveLogClient('test-project')
+      const client = createHiveLogClient({ projectName: 'test-project' })
 
       expect(client).toBeInstanceOf(HiveLogClient)
     })
@@ -90,7 +90,7 @@ describe('Hive SDK', () => {
       delete process.env.HIVE_API_SECRET
       delete process.env.HIVE_HOST
 
-      expect(() => createHiveLogClient('test-project')).not.toThrow()
+      expect(() => createHiveLogClient({ projectName: 'test-project' })).not.toThrow()
     })
   })
 
@@ -102,24 +102,24 @@ describe('Hive SDK', () => {
       delete process.env.HIVE_API_SECRET
       delete process.env.HIVE_HOST
 
-      silentClient = new HiveLogClient('silent-project')
+      silentClient = new HiveLogClient({ projectName: 'silent-project' })
     })
 
     it('should return "silent" for sendLog in silent mode', async () => {
-      const result = await silentClient.sendLog('test-task', { data: 'test' })
+      const result = await silentClient.sendLog('test-task', { input: 'test' })
       expect(result).toBe('silent')
     })
 
     it('should throw error for getLog in silent mode', async () => {
       await expect(silentClient.getLog('test-task', 'test-uuid')).rejects.toThrow(
-        'Missing Hive API credentials or host, get them at https://forgehive.dev'
+        'Missing Hive API credentials or host, get them at https://www.forgehive.cloud'
       )
     })
 
     it('should throw error for setQuality in silent mode', async () => {
       const quality = { score: 8, reason: 'test', suggestions: 'test' }
       await expect(silentClient.setQuality('test-task', 'test-uuid', quality)).rejects.toThrow(
-        'Missing Hive API credentials or host, get them at https://forgehive.dev'
+        'Missing Hive API credentials or host, get them at https://www.forgehive.cloud'
       )
     })
   })