{"_id":"@cubicler/cubickit","name":"@cubicler/cubickit","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@cubicler/cubickit","version":"0.0.1","description":"SDK core for interacting with the Cubicler ecosystem.","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","test":"jest","lint":"eslint .","start":"node dist/index.js","prepublishOnly":"npm run build && npm test","clean":"rm -rf dist"},"keywords":["Cubicler","SDK","TypeScript","AI","Agent","API"],"author":{"name":"hainayanda"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/hainayanda/CubicKit.git"},"bugs":{"url":"https://github.com/hainayanda/CubicKit/issues"},"homepage":"https://github.com/hainayanda/CubicKit#readme","devDependencies":{"@types/jest":"^29.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","jest":"^29.0.0","jest-fetch-mock":"^3.0.3","ts-jest":"^29.4.0","typescript":"^5.0.0"},"dependencies":{"node-fetch":"^3.3.2"},"_id":"@cubicler/cubickit@0.0.1","gitHead":"9ec008310e754b514c129f1edd622d5c88663fe3","_nodeVersion":"24.4.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-qAs9qSa7Hn9vSCzOithTdFM2kWixmFWNh3iRRyJ+KlHF0IdO6R4oFm7BKHcO+uqZ/BA93w9xoMPgQ8ELZPhHfQ==","shasum":"a5ca4f70e36fff6dd3bfd62b02996c54da979fb3","tarball":"https://registry.npmjs.org/@cubicler/cubickit/-/cubickit-0.0.1.tgz","fileCount":19,"unpackedSize":27919,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDzB7JHd/+P1y+l2CiaenrkWU0HqlbbVFnACzqEl4EjnwIgHklxm4NRXFE3if/vIjBLnpsbsQIXsltnZaRfoZf6c00="}]},"_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/cubickit_0.0.1_1752999467973_0.9618741025659281"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-20T08:17:47.911Z","0.0.1":"2025-07-20T08:17:48.228Z","modified":"2025-07-20T08:17:48.535Z"},"maintainers":[{"name":"hainayanda","email":"hainayanda@gmail.com"}],"description":"SDK core for interacting with the Cubicler ecosystem.","homepage":"https://github.com/hainayanda/CubicKit#readme","keywords":["Cubicler","SDK","TypeScript","AI","Agent","API"],"repository":{"type":"git","url":"git+https://github.com/hainayanda/CubicKit.git"},"author":{"name":"hainayanda"},"bugs":{"url":"https://github.com/hainayanda/CubicKit/issues"},"license":"MIT","readme":"# 🧱 CubicKit\n\n**The SDK core for interacting with the Cubicler ecosystem.**\n\nCubicKit is a **developer desk toolkit** for building AI agents that interface with Cubicler's orchestration system. Think of it as the **interface between your AI agent and Cubicler**, handling prompt retrieval, function spec loading, and agent call routing.\n\n## 🚀 Features\n\n- **TypeScript-first** SDK with full type safety\n- **Intelligent caching** with configurable timeouts for prompts and specs\n- **Fallback mechanisms** - uses cached data when network requests fail\n- **Force refresh** capabilities to bypass cache when needed\n- **Lightweight and stateless** - no heavyweight frameworks\n- **Model-agnostic** - works with any AI model or framework\n\n## 📦 Installation\n\n```bash\nnpm install cubic-kit\n```\n\n## 🧰 Basic Usage\n\n```typescript\nimport { CubicKitClient } from 'cubic-kit';\n\n// Create client with default configuration\nconst client = new CubicKitClient({\n    baseUrl: \"https://cubicler.example.com\"\n});\n\n// Load system prompt (cached for 10 minutes by default)\nconst prompt = await client.loadPrompt();\n\n// Load function specifications (cached for 10 minutes by default)\nconst specs = await client.loadSpec();\n\n// Call a function\nconst response = await client.callFunction(\"getMock\", {\n    mock_id: 123,\n    mock_name: \"test\"\n});\n```\n\n## ⚙️ Configuration\n\n```typescript\nimport { CubicKitClient } from 'cubic-kit';\n\nconst client = new CubicKitClient({\n    baseUrl: \"https://cubicler.example.com\",\n    promptCacheTimeout: 300,  // Cache prompt for 5 minutes (in seconds)\n    specCacheTimeout: 600     // Cache spec for 10 minutes (in seconds)\n});\n```\n\n## 🔄 Cache Management\n\n### Force Refresh\n```typescript\n// Force fetch fresh prompt (bypass cache)\nconst freshPrompt = await client.loadPrompt(true);\n\n// Force fetch fresh spec (bypass cache)\nconst freshSpec = await client.loadSpec(true);\n```\n\n### Automatic Fallback\nIf network requests fail, CubicKit automatically falls back to cached data when available:\n\n```typescript\ntry {\n    // Will use cached data if network fails\n    const prompt = await client.loadPrompt();\n} catch (error) {\n    // Only throws if no cached data is available\n    console.error('No cached data available:', error);\n}\n```\n\n## 🔧 API Reference\n\n### `CubicKitClient`\n\n#### Constructor\n\n```typescript\nnew CubicKitClient(config: CubicKitClientConfig)\n```\n\n- `config.baseUrl`: The base URL of your Cubicler instance\n- `config.promptCacheTimeout`: Cache timeout for prompts in seconds (default: 600)\n- `config.specCacheTimeout`: Cache timeout for specs in seconds (default: 600)\n\n#### Methods\n\n##### `loadPrompt(force?: boolean): Promise<string>`\nFetches the system prompt from `GET /prompt`.\n- Returns cached version if valid and `force` is false\n- Falls back to cache if network request fails\n\n##### `loadSpec(force?: boolean): Promise<FunctionSpec[]>`\nFetches function specifications from `GET /spec`.\n- Returns cached version if valid and `force` is false\n- Falls back to cache if network request fails\n\n##### `callFunction(functionName: string, parameters: FunctionCallParameters): Promise<any>`\nCalls a function via `POST /call`.\n- No caching for function calls\n- Returns the JSON response from the server\n\n## 📋 Types\n\n### `FunctionSpec`\n```typescript\ninterface FunctionSpec {\n  name: string;\n  description: string;\n  parameters: {\n    type: 'object';\n    properties: Record<string, ParameterDefinition>;\n    required?: string[];\n  };\n}\n```\n\n### `FunctionCallParameters`\n```typescript\ntype FunctionCallParameters = JSONObject & {\n  payload?: JSONValue;\n};\n```\n\n### `ParameterDefinition`\n```typescript\ninterface ParameterDefinition {\n  type: 'string' | 'number' | 'boolean' | 'array' | 'object';\n  required?: boolean;\n  items?: ParameterDefinition;\n  properties?: Record<string, ParameterDefinition>;\n}\n```\n\n## 🧪 Development\n\n### Running Tests\n```bash\nnpm test\n```\n\n### Building\n```bash\nnpm run build\n```\n\n### Linting\n```bash\nnpm run lint\n```\n\n## 📝 License\n\nMIT\n\n## 🤝 Contributing\n\nContributions are welcome! Please ensure:\n- Clean modularity and composability\n- Readability and DX over cleverness\n- Compatibility with Cubicler's spec and prompt structure\n- Lightweight, stateless, and testable code\n\n---\n\n**Build it like it's going to be used by other engineers every day.**","readmeFilename":"README.md","_rev":"1-5535f15a902c7b4f33a59be5df181b78"}