iii-sdk 0.0.2-alpha

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "iii-sdk",
+  "version": "0.0.2-alpha",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "author": "III",
+  "license": "Apache-2.0",
+  "type": "module",
+  "description": "III SDK for Node.js",
+  "keywords": [
+    "iii",
+    "sdk"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./stream": {
+      "types": "./dist/stream.d.ts",
+      "import": "./dist/stream.mjs",
+      "require": "./dist/stream.cjs"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry.d.ts",
+      "import": "./dist/telemetry.mjs",
+      "require": "./dist/telemetry.cjs"
+    }
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.57.0",
+    "@opentelemetry/core": "^1.30.0",
+    "@opentelemetry/instrumentation": "^0.57.0",
+    "@opentelemetry/otlp-transformer": "^0.57.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/sdk-logs": "^0.57.0",
+    "@opentelemetry/sdk-metrics": "^1.30.0",
+    "@opentelemetry/sdk-trace-base": "^1.30.0",
+    "@opentelemetry/sdk-trace-node": "^1.30.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/tests/healthcheck.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import type { ApiRequest, ApiResponse } from '../src'
+import { skipIfServerUnavailable } from './setup'
+import { execute, httpRequest, iii } from './utils'
+
+describe.skipIf(skipIfServerUnavailable())('Healthcheck Endpoint', () => {
+  it('should register a healthcheck function and trigger', async () => {
+    const functionId = 'test.healthcheck'
+
+    iii.registerFunction({ id: functionId }, async (_req: ApiRequest): Promise<ApiResponse> => {
+      return {
+        status_code: 200,
+        body: {
+          status: 'healthy',
+          timestamp: new Date().toISOString(),
+          service: 'iii-sdk-test',
+        },
+      }
+    })
+
+    await execute(async () => {
+      const response = await httpRequest('GET', '/health')
+      expect(response.status).toBe(404)
+    })
+
+    const trigger = iii.registerTrigger({
+      trigger_type: 'api',
+      function_id: functionId,
+      config: {
+        api_path: 'health',
+        http_method: 'GET',
+        description: 'Healthcheck endpoint',
+      },
+    })
+
+    await execute(async () => {
+      const response = await httpRequest('GET', '/health')
+
+      expect(response.status).toBe(200)
+      expect(response.data).toHaveProperty('status', 'healthy')
+      expect(response.data).toHaveProperty('service', 'iii-sdk-test')
+      expect(response.data).toHaveProperty('timestamp')
+    })
+
+    trigger.unregister()
+
+    // there's an issue with unregistering
+    // await execute(async () => {
+    //   const response = await httpRequest('GET', '/health')
+    //   expect(response.status).toBe(404)
+    // })
+  })
+})

package/tests/setup.ts

@@ -0,0 +1,48 @@
+import { afterAll, beforeAll } from 'vitest'
+import { checkServerAvailability, iii } from './utils'
+
+const isCI = Boolean(process.env.CI)
+const hasExplicitServerUrl = Boolean(process.env.III_BRIDGE_URL || process.env.III_HTTP_URL)
+
+let serverAvailable = false
+
+beforeAll(async () => {
+  if (isCI && !hasExplicitServerUrl) {
+    console.warn('Running in CI without explicit server URL. Skipping integration tests.')
+    console.warn('To run tests in CI, set III_BRIDGE_URL and III_HTTP_URL environment variables,')
+    console.warn('or ensure the III Engine server is started before running tests.')
+    serverAvailable = false
+    return
+  }
+
+  console.log(
+    `Checking server availability at: ${process.env.III_HTTP_URL ?? 'http://localhost:3111'}`,
+  )
+  serverAvailable = await checkServerAvailability()
+
+  if (!serverAvailable) {
+    console.warn('III Engine server is not available. Skipping integration tests.')
+    console.warn(`Expected server at: ${process.env.III_HTTP_URL ?? 'http://localhost:3111'}`)
+    console.warn('To run tests locally, start the III Engine server first.')
+  } else {
+    console.log('III Engine server is available. Running integration tests.')
+  }
+})
+
+afterAll(async () => {
+  try {
+    const sdk = iii as { shutdown?: () => Promise<void> }
+    if (sdk.shutdown) {
+      await sdk.shutdown()
+    }
+  } catch (error) {
+    console.error('Error shutting down SDK:', error)
+  }
+})
+
+export function skipIfServerUnavailable(): boolean {
+  if (isCI && !hasExplicitServerUrl) {
+    return true
+  }
+  return false
+}

package/tests/state.test.ts

@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { skipIfServerUnavailable } from './setup'
+import { iii } from './utils'
+import type { StateSetResult } from './types'
+
+type TestData = {
+  name?: string
+  value: number
+  updated?: boolean
+}
+
+describe.skipIf(skipIfServerUnavailable())('State Operations', () => {
+  const testGroupId = 'test-group'
+  const testItemId = 'test-item'
+
+  beforeEach(async () => {
+    await iii
+      .call('state.delete', { group_id: testGroupId, item_id: testItemId })
+      .catch(() => void 0)
+  })
+
+  describe('state.set', () => {
+    it('should set a new state item', async () => {
+      const testData = {
+        name: 'Test Item',
+        value: 42,
+        metadata: { created: new Date().toISOString() },
+      }
+
+      const result = await iii.call('state.set', {
+        group_id: testGroupId,
+        item_id: testItemId,
+        data: testData,
+      })
+
+      expect(result).toBeDefined()
+      expect(result).toEqual({ old_value: null, new_value: testData })
+    })
+
+    it('should overwrite an existing state item', async () => {
+      const initialData: TestData = { value: 1 }
+      const updatedData: TestData = { value: 2, updated: true }
+
+      await iii.call('state.set', {
+        group_id: testGroupId,
+        item_id: testItemId,
+        data: initialData,
+      })
+
+      const result: StateSetResult = await iii.call('state.set', {
+        group_id: testGroupId,
+        item_id: testItemId,
+        data: updatedData,
+      })
+
+      expect(result.old_value).toEqual(initialData)
+      expect(result.new_value).toEqual(updatedData)
+    })
+  })
+
+  describe('state.get', () => {
+    it('should get an existing state item', async () => {
+      const testData: TestData = { name: 'Test', value: 100 }
+
+      await iii.call('state.set', {
+        group_id: testGroupId,
+        item_id: testItemId,
+        data: testData,
+      })
+
+      const result: TestData = await iii.call('state.get', {
+        group_id: testGroupId,
+        item_id: testItemId,
+      })
+
+      expect(result).toBeDefined()
+      expect(result).toEqual(testData)
+    })
+
+    it('should return null for non-existent item', async () => {
+      const result = await iii.call('state.get', {
+        group_id: testGroupId,
+        item_id: 'non-existent-item',
+      })
+
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('state.delete', () => {
+    it('should delete an existing state item', async () => {
+      await iii.call('state.set', {
+        group_id: testGroupId,
+        item_id: testItemId,
+        data: { test: true },
+      })
+
+      await iii.call('state.delete', {
+        group_id: testGroupId,
+        item_id: testItemId,
+      })
+
+      const result = await iii.call('state.get', {
+        group_id: testGroupId,
+        item_id: testItemId,
+      })
+
+      expect(result).toBeUndefined()
+    })
+
+    it('should handle deleting non-existent item gracefully', async () => {
+      await expect(
+        iii.call('state.delete', {
+          group_id: testGroupId,
+          item_id: 'non-existent',
+        }),
+      ).resolves.not.toThrow()
+    })
+  })
+
+  describe('state.list', () => {
+    it('should get all items in a group', async () => {
+      type TestDataWithId = TestData & { id: string }
+
+      const groupId = `state-${Date.now()}`
+      const items: TestDataWithId[] = [
+        { id: 'state-item1', value: 1 },
+        { id: 'state-item2', value: 2 },
+        { id: 'state-item3', value: 3 },
+      ]
+
+      // Set multiple items
+      for (const item of items) {
+        await iii.call('state.set', {
+          group_id: groupId,
+          item_id: item.id,
+          data: item,
+        })
+      }
+
+      const result: TestDataWithId[] = await iii.call('state.list', { group_id: groupId })
+      const sort = (a: TestDataWithId, b: TestDataWithId) => a.id.localeCompare(b.id)
+
+      expect(Array.isArray(result)).toBe(true)
+      expect(result.length).toBeGreaterThanOrEqual(items.length)
+      expect(result.sort(sort)).toEqual(items.sort(sort))
+    })
+  })
+})

package/tests/stream.test.ts

@@ -0,0 +1,217 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { skipIfServerUnavailable } from './setup'
+import { iii, sleep } from './utils'
+import type { StreamSetInput, StreamSetResult } from '../src/stream'
+
+type TestData = {
+  name?: string
+  value: number
+  updated?: boolean
+}
+
+describe.skipIf(skipIfServerUnavailable())('Stream Operations', () => {
+  const testStreamName = 'test-stream'
+  const testGroupId = 'test-group'
+  const testItemId = 'test-item'
+
+  beforeEach(async () => {
+    await iii
+      .call('stream.delete', {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: testItemId,
+      })
+      .catch(() => void 0)
+  })
+
+  describe('stream.set', () => {
+    it('should set a new stream item', async () => {
+      const testData = {
+        name: 'Test Item',
+        value: 42,
+        metadata: { created: new Date().toISOString() },
+      }
+
+      const result = await iii.call<StreamSetInput, StreamSetResult<TestData>>('stream.set', {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: testItemId,
+        data: testData,
+      })
+
+      expect(result).toBeDefined()
+      expect(result).toEqual({ old_value: null, new_value: testData })
+    })
+
+    it('should overwrite an existing stream item', async () => {
+      const initialData: TestData = { value: 1 }
+      const updatedData: TestData = { value: 2, updated: true }
+
+      await iii.call('stream.set', {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: testItemId,
+        data: initialData,
+      })
+
+      const result: StreamSetResult<any> = await iii.call('stream.set', {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: testItemId,
+        data: updatedData,
+      })
+
+      expect(result.old_value).toEqual(initialData)
+      expect(result.new_value).toEqual(updatedData)
+    })
+  })
+
+  describe('stream.get', () => {
+    it('should get an existing stream item', async () => {
+      const testData: TestData = { name: 'Test', value: 100 }
+
+      await iii.call('stream.set', {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: testItemId,
+        data: testData,
+      })
+
+      const result: TestData = await iii.call('stream.get', {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: testItemId,
+      })
+
+      expect(result).toBeDefined()
+      expect(result).toEqual(testData)
+    })
+
+    it('should return null for non-existent item', async () => {
+      const result = await iii.call('stream.get', {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: 'non-existent-item',
+      })
+
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('stream.delete', () => {
+    it('should delete an existing stream item', async () => {
+      await iii.call('stream.set', {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: testItemId,
+        data: { test: true },
+      })
+
+      await iii.call('stream.delete', {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: testItemId,
+      })
+
+      const result = await iii.call('stream.get', {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: testItemId,
+      })
+
+      expect(result).toBeUndefined()
+    })
+
+    it('should handle deleting non-existent item gracefully', async () => {
+      await expect(
+        iii.call('stream.delete', {
+          stream_name: testStreamName,
+          group_id: testGroupId,
+          item_id: 'non-existent',
+        }),
+      ).resolves.not.toThrow()
+    })
+  })
+
+  describe('stream.list', () => {
+    it('should get all items in a group', async () => {
+      type TestDataWithId = TestData & { id: string }
+
+      const groupId = `stream-${Date.now()}`
+      const items: TestDataWithId[] = [
+        { id: 'stream-item1', value: 1 },
+        { id: 'stream-item2', value: 2 },
+        { id: 'stream-item3', value: 3 },
+      ]
+
+      // Set multiple items
+      for (const item of items) {
+        await iii.call('stream.set', {
+          stream_name: testStreamName,
+          group_id: groupId,
+          item_id: item.id,
+          data: item,
+        })
+      }
+
+      const result: TestDataWithId[] = await iii.call('stream.list', {
+        stream_name: testStreamName,
+        group_id: groupId,
+      })
+      const sort = (a: TestDataWithId, b: TestDataWithId) => a.id.localeCompare(b.id)
+
+      expect(Array.isArray(result)).toBe(true)
+      expect(result.length).toBeGreaterThanOrEqual(items.length)
+      expect(result.sort(sort)).toEqual(items.sort(sort))
+    })
+  })
+
+  describe('stream custom operations', () => {
+    it('should perform a custom operation on a stream item', async () => {
+      const testStreamName = `test-stream-${Date.now()}`
+      const state: Map<string, TestData> = new Map()
+
+      iii.createStream(testStreamName, {
+        get: async input => state.get(`${input.group_id}::${input.item_id}`),
+        set: async input => {
+          const key = `${input.group_id}::${input.item_id}`
+          const oldValue = state.get(key)
+          state.set(key, input.data)
+
+          return { old_value: oldValue, new_value: input.data }
+        },
+        delete: async input => {
+          const oldValue = state.get(`${input.group_id}::${input.item_id}`)
+          state.delete(`${input.group_id}::${input.item_id}`)
+          return { old_value: oldValue }
+        },
+        list: async input => {
+          return Array.from(state.keys())
+            .filter(key => key.startsWith(`${input.group_id}::`))
+            .map(key => state.get(key))
+        },
+        listGroups: async () => Array.from(state.keys()),
+        update: async () => {
+          throw new Error('Not implemented')
+        },
+      })
+
+      await sleep(1_000)
+
+      const testData: TestData = { name: 'Test', value: 100 }
+      const getArgs = {
+        stream_name: testStreamName,
+        group_id: testGroupId,
+        item_id: testItemId,
+      }
+
+      await iii.call('stream.set', { ...getArgs, data: testData })
+
+      expect(state.get(`${testGroupId}::${testItemId}`)).toEqual(testData)
+
+      await expect(iii.call('stream.get', getArgs)).resolves.toEqual(testData)
+      await iii.call('stream.delete', getArgs)
+      await expect(iii.call('stream.get', getArgs)).resolves.toEqual(undefined)
+    })
+  })
+})

package/tests/types.ts

@@ -0,0 +1,54 @@
+import type { UpdateOp, StreamSetResult } from '../src/stream'
+
+export interface StateSetResult {
+  // biome-ignore lint/suspicious/noExplicitAny: any is fine here
+  old_value?: any
+  // biome-ignore lint/suspicious/noExplicitAny: any is fine here
+  new_value?: any
+}
+
+export type { StreamSetResult }
+
+export interface StateSetInput {
+  group_id: string
+  item_id: string
+  // biome-ignore lint/suspicious/noExplicitAny: any is fine here
+  data: any
+}
+
+export interface StateGetInput {
+  group_id: string
+  item_id: string
+}
+
+export interface StateDeleteInput {
+  group_id: string
+  item_id: string
+}
+
+export interface StateUpdateInput {
+  group_id: string
+  item_id: string
+  ops: UpdateOp[]
+}
+
+export interface StateGetGroupInput {
+  group_id: string
+}
+
+export enum StateEventType {
+  Created = 'state:created',
+  Updated = 'state:updated',
+  Deleted = 'state:deleted',
+}
+
+export interface StateEventData {
+  type: string
+  event_type: StateEventType
+  group_id: string
+  item_id: string
+  // biome-ignore lint/suspicious/noExplicitAny: any is fine here
+  old_value?: any
+  // biome-ignore lint/suspicious/noExplicitAny: any is fine here
+  new_value?: any
+}

package/tests/utils.ts

@@ -0,0 +1,83 @@
+// import { iii } from 'iii-sdk'
+import { init } from '../src/index'
+
+const ENGINE_WS_URL = process.env.III_BRIDGE_URL ?? 'ws://localhost:49134'
+const ENGINE_HTTP_URL = process.env.III_HTTP_URL ?? 'http://localhost:3111'
+const RETRY_LIMIT = 100
+const DELAY_MS = 100
+
+export const engineWsUrl = ENGINE_WS_URL
+export const engineHttpUrl = ENGINE_HTTP_URL
+
+export const iii = init(engineWsUrl, {
+  reconnectionConfig: {
+    maxRetries: 3,
+    initialDelayMs: 100,
+    maxDelayMs: 1000,
+  },
+})
+
+export async function checkServerAvailability(): Promise<boolean> {
+  try {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), 2000)
+
+    try {
+      const response = await fetch(ENGINE_HTTP_URL, {
+        method: 'GET',
+        signal: controller.signal,
+      })
+      clearTimeout(timeoutId)
+      return response.status < 500
+    } catch {
+      clearTimeout(timeoutId)
+      return false
+    }
+  } catch {
+    return false
+  }
+}
+
+export async function httpRequest(
+  method: string,
+  path: string,
+  // biome-ignore lint/suspicious/noExplicitAny: any is fine here
+  body?: any,
+  // biome-ignore lint/suspicious/noExplicitAny: any is fine here
+): Promise<{ status: number; data: any }> {
+  const url = `${engineHttpUrl}${path}`
+  const options: RequestInit = { method, headers: { 'Content-Type': 'application/json' } }
+
+  if (body) {
+    options.body = JSON.stringify(body)
+  }
+
+  const response = await fetch(url, options)
+  const data = await response.json().catch(() => ({}))
+
+  return { status: response.status, data }
+}
+
+export function sleep(duration: number): Promise<void> {
+  return new Promise(resolve => {
+    setTimeout(() => resolve(), duration)
+  })
+}
+
+export async function execute<T>(operation: () => Promise<T>): Promise<T> {
+  let currentAttempt = 0
+
+  while (true) {
+    try {
+      return await operation()
+    } catch (err) {
+      currentAttempt++
+
+      if (currentAttempt >= RETRY_LIMIT) {
+        throw err
+      }
+
+      await sleep(DELAY_MS)
+    }
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    testTimeout: 30000,
+    hookTimeout: 30000,
+    setupFiles: ['./tests/setup.ts'],
+  },
+})