{"_id":"@cubicler/cubicclientkit","_rev":"3-7dfb99e1cf685f54c1460b7f8d031f4f","name":"@cubicler/cubicclientkit","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.0":{"name":"@cubicler/cubicclientkit","version":"1.0.0","keywords":["cubicler","ai","client","sdk","typescript","agents","orchestrator"],"author":{"name":"Cubicler"},"license":"MIT","_id":"@cubicler/cubicclientkit@1.0.0","maintainers":[{"name":"hainayanda","email":"hainayanda@gmail.com"}],"homepage":"https://github.com/Cubicler/CubicClientKit#readme","bugs":{"url":"https://github.com/Cubicler/CubicClientKit/issues"},"dist":{"shasum":"9421e6dd2e9db5cd03f9bdcbd88c4b114e36887f","tarball":"https://registry.npmjs.org/@cubicler/cubicclientkit/-/cubicclientkit-1.0.0.tgz","fileCount":9,"integrity":"sha512-LYZcM3Ad9KfrD+2+jfuoFsqBeAt7Q4E0SlXnESfN44uc2U8+uVns8vKt7/jo0qhFJoPnNLDZ1pt56BTWAjshpA==","signatures":[{"sig":"MEQCIAumFfFWQyRiptkdz5dLOGl7dfT6hEknEkNWS/Rg3WxsAiBGVzRcmWNt7Zynj8cV7dFLVkALpQFbybiWqEIRi/Zo2g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46725},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"gitHead":"cace68761ff99803799d7bed5b84a0d38b7757c5","scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts","test":"vitest","build":"tsup","test:watch":"vitest --watch","type-check":"tsc --noEmit","test:coverage":"vitest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"hainayanda","email":"hainayanda@gmail.com"},"repository":{"url":"git+https://github.com/Cubicler/CubicClientKit.git","type":"git"},"_npmVersion":"11.4.2","description":"A TypeScript client SDK for the Cubicler ecosystem","directories":{},"_nodeVersion":"24.4.0","dependencies":{"axios":"^1.6.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^8.54.0","vitest":"^3.2.4","typescript":"^5.3.0","@types/node":"^20.10.0","@vitest/coverage-v8":"^3.2.4","@typescript-eslint/parser":"^6.21.0","@typescript-eslint/eslint-plugin":"^6.21.0"},"_npmOperationalInternal":{"tmp":"tmp/cubicclientkit_1.0.0_1753503368787_0.13312375182354907","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@cubicler/cubicclientkit","version":"1.0.1","keywords":["cubicler","ai","client","sdk","typescript","agents","orchestrator"],"author":{"name":"Cubicler"},"license":"MIT","_id":"@cubicler/cubicclientkit@1.0.1","maintainers":[{"name":"hainayanda","email":"hainayanda@gmail.com"}],"homepage":"https://github.com/Cubicler/CubicClientKit#readme","bugs":{"url":"https://github.com/Cubicler/CubicClientKit/issues"},"dist":{"shasum":"5f4ce0178b6949b659e77492ebbcd08f76e05677","tarball":"https://registry.npmjs.org/@cubicler/cubicclientkit/-/cubicclientkit-1.0.1.tgz","fileCount":9,"integrity":"sha512-c5AINFu+b8dc+Q1wsNuBb6L4YOfdVPCYvNqh8Wv2e9m5ohhhrbcp+U0s//gHQ3bgIqoR4DF5IFTvmHXxCttEPw==","signatures":[{"sig":"MEUCIQCEV/EOD5VL2Ar//uHj89+y8wT42CbUwAIiVwkKLBFUsgIgXHY4hoQG5/qRQpQRzjoPuTjjrMoDvuH0I89E4PIZI44=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47046},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=16.0.0"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"b6ef9628f5aae99c6bb57c11358a5894650e2e56","scripts":{"dev":"tsup --watch","lint":"eslint .","test":"vitest","build":"tsup","lint:fix":"eslint . --fix","test:watch":"vitest --watch","type-check":"tsc --noEmit","test:coverage":"vitest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"hainayanda","email":"hainayanda@gmail.com"},"repository":{"url":"git+https://github.com/Cubicler/CubicClientKit.git","type":"git"},"_npmVersion":"11.4.2","description":"A TypeScript client SDK for the Cubicler ecosystem","directories":{},"_nodeVersion":"24.4.0","dependencies":{"axios":"^1.6.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^8.54.0","vitest":"^3.2.4","@eslint/js":"^9.32.0","typescript":"^5.3.0","@types/node":"^20.10.0","@vitest/coverage-v8":"^3.2.4","@typescript-eslint/parser":"^8.38.0","@typescript-eslint/eslint-plugin":"^8.38.0"},"_npmOperationalInternal":{"tmp":"tmp/cubicclientkit_1.0.1_1753600674966_0.6460086635583142","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@cubicler/cubicclientkit","version":"2.0.0","type":"module","description":"A TypeScript client SDK for the Cubicler ecosystem","main":"dist/index.cjs","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest","test:watch":"vitest --watch","test:coverage":"vitest --coverage","type-check":"tsc --noEmit","lint":"eslint .","lint:fix":"eslint . --fix","prepublishOnly":"npm run build"},"keywords":["cubicler","ai","client","sdk","typescript","agents","orchestrator"],"author":{"name":"Cubicler"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Cubicler/CubicClientKit.git"},"homepage":"https://github.com/Cubicler/CubicClientKit#readme","bugs":{"url":"https://github.com/Cubicler/CubicClientKit/issues"},"publishConfig":{"access":"public"},"devDependencies":{"@eslint/js":"^9.32.0","@types/node":"^20.10.0","@typescript-eslint/eslint-plugin":"^8.38.0","@typescript-eslint/parser":"^8.38.0","@vitest/coverage-v8":"^3.2.4","eslint":"^8.54.0","tsup":"^8.0.0","typescript":"^5.3.0","vitest":"^3.2.4"},"dependencies":{"axios":"^1.6.0"},"engines":{"node":">=16.0.0"},"_id":"@cubicler/cubicclientkit@2.0.0","gitHead":"b6ef9628f5aae99c6bb57c11358a5894650e2e56","_nodeVersion":"24.4.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-tSx7Xp/mf3hbPDHaBDYl561XDTHRKmPosytr4mYMax7oyMdLOlTaB4NOeCr4sKt1ONWmjnXhYhbtVVcVAaZCfw==","shasum":"3e219a8f198ac2d6c869bc2435d24e8763f43957","tarball":"https://registry.npmjs.org/@cubicler/cubicclientkit/-/cubicclientkit-2.0.0.tgz","fileCount":9,"unpackedSize":51515,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFGldn8IG46efCHJcCv/CiLCLUjwiSQVwPrCS5vLBa3qAiAYP8pH5jNyC9PYjxRzOmNJs3avLQUVOoMpiwhN3WgdmQ=="}]},"_npmUser":{"name":"hainayanda","email":"hainayanda@gmail.com"},"directories":{},"maintainers":[{"name":"hainayanda","email":"hainayanda@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cubicclientkit_2.0.0_1753840510496_0.5644866338997145"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-26T04:16:08.585Z","modified":"2025-07-30T01:55:10.858Z","1.0.0":"2025-07-26T04:16:09.013Z","1.0.1":"2025-07-27T07:17:55.145Z","2.0.0":"2025-07-30T01:55:10.672Z"},"bugs":{"url":"https://github.com/Cubicler/CubicClientKit/issues"},"author":{"name":"Cubicler"},"license":"MIT","homepage":"https://github.com/Cubicler/CubicClientKit#readme","keywords":["cubicler","ai","client","sdk","typescript","agents","orchestrator"],"repository":{"type":"git","url":"git+https://github.com/Cubicler/CubicClientKit.git"},"description":"A TypeScript client SDK for the Cubicler ecosystem","maintainers":[{"name":"hainayanda","email":"hainayanda@gmail.com"}],"readme":"# CubicClientKit\n\nA TypeScript client SDK that provides a simple bridge for frontend applications to interact with the Cubicler ecosystem.\n\n## Overview\n\nCubicClientKit is a lightweight npm library that allows frontend apps to call AI agents via the Cubicler orchestrator. The SDK focuses on simplicity and type safety, letting users handle their own conversation management and business logic.\n\n## Features\n\n- 🚀 **Simple Bridge**: Direct mapping to Cubicler REST API endpoints\n- 🔒 **Type Safety**: Full TypeScript coverage without complexity  \n- 🎯 **No Opinions**: Let users handle conversation management, error handling, and business logic\n- 🌐 **Browser Compatible**: Works in both Node.js and browser environments\n- ⚡ **Lightweight**: Minimal dependencies with focus on core functionality\n\n## Installation\n\n```bash\nnpm install @cubicler/cubicclientkit\n```\n\n## Quick Start\n\n```typescript\nimport { CubicClient } from '@cubicler/cubicclientkit';\n\n// Create client instance\nconst client = new CubicClient({\n  baseUrl: 'http://localhost:1503'\n});\n\n// Call the default agent\nconst response = await client.call({ \n  sender: { id: 'user_123', name: 'John' }, \n  type: 'text',\n  content: 'Hello, can you help me?' \n});\nconsole.log(response); // Agent's response message\n\n// Call a specific agent\nconst weatherResponse = await client.callAgent('weather-agent', { \n  sender: { id: 'user_123', name: 'John' }, \n  type: 'text',\n  content: 'What is the weather today?' \n});\nconsole.log(weatherResponse);\n\n// Get available agents\nconst agents = await client.getAgents();\nconsole.log('Available agents:', agents);\n\n// Check system health\nconst health = await client.getHealth();\nconsole.log('System status:', health.status);\n```\n\n## API Reference\n\n### Constructor\n\n```typescript\nnew CubicClient(options: CubicClientOptions)\n```\n\n**Options:**\n\n- `baseUrl` (string, required): Base URL of the Cubicler API (e.g., '<http://localhost:1503>')\n- `timeout` (number, optional): Request timeout in milliseconds (default: 90000)\n- `retry` (number, optional): Number of retries for failed requests\n\n### Methods\n\n#### `call(messages: Message[] | Message): Promise<string>`\n\nCall the default AI agent.\n\n**Parameters:**\n\n- `messages`: Array of message objects or a single message object\n\n**Returns:** Promise that resolves to the agent's response message\n\n#### `callAgent(agentName: string, messages: Message[] | Message): Promise<string>`\n\nCall a specific AI agent.\n\n**Parameters:**\n\n- `agentName`: Name of the agent to call\n- `messages`: Array of message objects or a single message object\n\n**Returns:** Promise that resolves to the agent's response message\n\n#### `getAgents(): Promise<string[]>`\n\nGet list of available agents.\n\n**Returns:** Promise that resolves to an array of agent names\n\n#### `getHealth(): Promise<HealthStatus>`\n\nCheck system health status.\n\n**Returns:** Promise that resolves to the health status object\n\n## Types\n\n### Message\n\n```typescript\ninterface Message {\n  sender: {\n    id: string;      // Unique identifier (e.g., \"user_123\", \"telegram_456\")\n    name?: string;   // Optional display name\n  };\n  type: \"text\";      // Message type (currently only \"text\" supported)\n  content: string;   // The actual message content\n  timestamp?: string; // Optional ISO 8601 timestamp\n}\n```\n\n### CubicClientOptions\n\n```typescript\ninterface CubicClientOptions {\n  baseUrl: string;\n  timeout?: number;\n  retry?: number;\n}\n```\n\n### HealthStatus\n\n```typescript\ninterface HealthStatus {\n  status: 'healthy' | 'unhealthy';\n  timestamp: string;\n  services: {\n    prompt?: ServiceStatus;\n    agents?: ServiceStatus;\n    providers?: ServiceStatus;\n    spec?: ServiceStatus;\n  };\n}\n\ninterface ServiceStatus {\n  status: 'healthy' | 'unhealthy';\n  error?: string;\n  count?: number;\n  agents?: string[];\n  providers?: string[];\n}\n```\n\n## Examples\n\n### Creating a Client\n\n```typescript\nimport { CubicClient } from '@cubicler/cubicclientkit';\n// Or import specific types if needed\nimport { CubicClient, type Message, type HealthStatus } from '@cubicler/cubicclientkit';\n\n// Basic client setup\nconst client = new CubicClient({\n  baseUrl: 'http://localhost:1503'\n});\n\n// Client with custom timeout and retry\nconst clientWithOptions = new CubicClient({\n  baseUrl: 'http://localhost:1503',\n  timeout: 10000,  // 10 seconds\n  retry: 3         // Retry up to 3 times\n});\n```\n\n### Calling the Default Agent\n\n```typescript\n// Single message (Message object)\nconst response = await client.call({ \n  sender: { id: 'user_123', name: 'John' }, \n  type: 'text',\n  content: 'Hello, can you help me?' \n});\nconsole.log(response); // Agent's response message\n\n// Multiple messages (conversation history)\nconst messages = [\n  { \n    sender: { id: 'user_123', name: 'John' }, \n    type: 'text',\n    content: 'Hello' \n  },\n  { \n    sender: { id: 'assistant_1', name: 'Assistant' }, \n    type: 'text',\n    content: 'Hi! How can I help?' \n  },\n  { \n    sender: { id: 'user_123', name: 'John' }, \n    type: 'text',\n    content: 'What is the weather like?' \n  }\n];\n\nconst response = await client.call(messages);\nconsole.log(response); // Agent's response message\n```\n\n### Calling a Specific Agent\n\n```typescript\n// Single message to specific agent\nconst response = await client.callAgent('weather-agent', { \n  sender: { id: 'user_123', name: 'John' }, \n  type: 'text',\n  content: 'What is the weather in New York?' \n});\nconsole.log(response);\n\n// Multiple messages to specific agent\nconst messages = [\n  { \n    sender: { id: 'user_123', name: 'John' }, \n    type: 'text',\n    content: 'I need help with coding' \n  },\n  { \n    sender: { id: 'coding-assistant', name: 'Code Helper' }, \n    type: 'text',\n    content: 'I can help! What language?' \n  },\n  { \n    sender: { id: 'user_123', name: 'John' }, \n    type: 'text',\n    content: 'TypeScript please' \n  }\n];\n\nconst response = await client.callAgent('coding-assistant', messages);\nconsole.log(response);\n```\n\n### Getting Available Agents\n\n```typescript\nconst agents = await client.getAgents();\nconsole.log('Available agents:', agents);\n// Output: ['default', 'weather-agent', 'coding-assistant', ...]\n```\n\n### Checking System Health\n\n```typescript\nconst health = await client.getHealth();\nconsole.log('System status:', health.status);\nconsole.log('Timestamp:', health.timestamp);\nconsole.log('Services:', health.services);\n\n// Example health response:\n// {\n//   status: 'healthy',\n//   timestamp: '2024-01-01T12:00:00Z',\n//   services: {\n//     prompt: { status: 'healthy' },\n//     agents: { status: 'healthy', count: 5, agents: ['agent1', 'agent2'] },\n//     providers: { status: 'healthy', count: 2 },\n//     spec: { status: 'healthy' }\n//   }\n// }\n```\n\n### Complete Example\n\n```typescript\nimport { CubicClient } from '@cubicler/cubicclientkit';\n\nasync function main() {\n  const client = new CubicClient({\n    baseUrl: 'http://localhost:1503',\n    timeout: 15000, // 15 seconds (default is 90 seconds)\n    retry: 2\n  });\n\n  try {\n    // Check system health\n    const health = await client.getHealth();\n    if (health.status !== 'healthy') {\n      console.warn('System is not fully healthy:', health);\n    }\n\n    // Get available agents\n    const agents = await client.getAgents();\n    console.log('Available agents:', agents);\n\n    // Call default agent\n    const defaultResponse = await client.call({ \n      sender: { id: 'user_123', name: 'John' }, \n      type: 'text',\n      content: 'Hello! How are you?' \n    });\n    console.log('Default agent response:', defaultResponse);\n\n    // Call specific agent if available\n    if (agents.includes('weather-agent')) {\n      const weatherResponse = await client.callAgent(\n        'weather-agent',\n        { \n          sender: { id: 'user_123', name: 'John' }, \n          type: 'text',\n          content: 'What is the weather forecast for tomorrow?' \n        }\n      );\n      console.log('Weather agent response:', weatherResponse);\n    }\n\n  } catch (error) {\n    console.error('Error occurred:', error);\n  }\n}\n\nmain();\n```\n\n## Error Handling\n\nThe SDK lets errors bubble up to your application for maximum flexibility:\n\n```typescript\ntry {\n  const response = await client.call({ \n    sender: { id: 'user_123', name: 'John' }, \n    type: 'text',\n    content: 'Hello!' \n  });\n  console.log(response);\n} catch (error) {\n  if (error.response) {\n    // HTTP error response\n    console.error('API Error:', error.response.status, error.response.data);\n  } else if (error.request) {\n    // Network error\n    console.error('Network Error:', error.message);\n  } else {\n    // Other error\n    console.error('Error:', error.message);\n  }\n}\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Type check\nnpm run type-check\n\n# Lint code\nnpm run lint\n\n# Lint and fix code\nnpm run lint:fix\n```\n\n## Browser Compatibility\n\nCubicClientKit works in modern browsers and Node.js environments (Node.js 16+). It uses ES2020 features and includes proper type definitions for TypeScript projects.\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.\n\n## Support\n\nFor questions and support, please open an issue in the GitHub repository.\n","readmeFilename":"README.md"}