@cadraos/sdk 0.1.2

package/README.md

@@ -0,0 +1,401 @@
+# @cadraos/sdk
+
+Official SDK for the AI SaaS platform - programmatic access to agents, skills, tools, and artifacts.
+
+## Installation
+
+```bash
+npm install @cadraos/sdk
+# or
+pnpm add @cadraos/sdk
+# or
+yarn add @cadraos/sdk
+```
+
+## Quick Start
+
+```typescript
+import { AISaaSClient } from '@cadraos/sdk';
+
+// Initialize the client
+const client = new AISaaSClient({
+  apiKey: process.env.AISAAS_API_KEY!,
+  orgId: Number(process.env.AISAAS_ORG_ID),
+});
+
+// List available agents
+const { data: agents } = await client.agents.list();
+console.log('Available agents:', agents.map(a => a.name));
+
+// Execute an agent
+const execution = await client.agents.executeSync(agents[0].uuid, {
+  task: 'Summarize the latest news about AI',
+});
+console.log('Result:', execution.output);
+```
+
+## Authentication
+
+The SDK supports three authentication methods:
+
+### API Key (recommended for server-side)
+
+```typescript
+const client = new AISaaSClient({
+  apiKey: 'sk_...',
+  orgId: 123,
+});
+```
+
+### OAuth Token
+
+```typescript
+const client = new AISaaSClient({
+  token: 'eyJ...',
+  orgId: 123,
+});
+```
+
+### Token Provider (for automatic refresh)
+
+```typescript
+const client = new AISaaSClient({
+  tokenProvider: async () => myAuth.getAccessToken(),
+  orgId: 123,
+});
+```
+
+## API Reference
+
+### Agents
+
+```typescript
+// List agents
+const { data: agents, pagination } = await client.agents.list({
+  limit: 10,
+  status: 'active',
+});
+
+// Get agent details
+const agent = await client.agents.get('agent-uuid');
+
+// Execute (async - returns immediately)
+const { executionId, status } = await client.agents.execute('agent-uuid', {
+  task: 'Your task here',
+  context: { key: 'value' },
+});
+
+// Execute (sync - waits for completion)
+const execution = await client.agents.executeSync('agent-uuid', {
+  task: 'Your task here',
+});
+
+// Stream execution (real-time events)
+const stream = await client.agents.stream('agent-uuid', {
+  task: 'Research a topic',
+});
+
+stream.on('log', (log) => console.log(log.title));
+stream.on('toolCall', ({ toolName }) => console.log(`Calling: ${toolName}`));
+stream.on('complete', ({ execution }) => console.log(execution.output));
+
+const result = await stream.wait();
+
+// Get execution result
+const execution = await client.agents.getExecution('execution-uuid');
+
+// Update agent
+const updated = await client.agents.update('agent-uuid', {
+  name: 'New Name',
+  description: 'New description',
+});
+
+// Cancel execution
+await client.agents.cancelExecution('execution-uuid');
+```
+
+### Skills
+
+```typescript
+// List skills
+const { data: skills } = await client.skills.list({
+  category: 'writing',
+  tags: ['seo', 'blog'],
+});
+
+// Get skill with prompt template
+const skill = await client.skills.get('skill-uuid');
+console.log(skill.promptTemplate);
+
+// Get skill tools
+const tools = await client.skills.getTools('skill-uuid');
+
+// Execute skill
+const result = await client.skills.execute('skill-uuid', {
+  variables: {
+    topic: 'AI in healthcare',
+    tone: 'professional',
+  },
+});
+
+// Update skill
+await client.skills.update('skill-uuid', {
+  name: 'Updated Name',
+  tags: ['new-tag'],
+});
+
+// Update prompt template
+await client.skills.updatePrompt('skill-uuid', 'New prompt template...');
+```
+
+### Tools
+
+```typescript
+// List tools
+const { data: tools } = await client.tools.list({
+  category: 'data',
+  isEnabled: true,
+});
+
+// Get tool with schema
+const tool = await client.tools.get('tool-uuid');
+console.log(tool.inputSchema);
+
+// Execute tool
+const result = await client.tools.execute('tool-uuid', {
+  query: 'weather in London',
+  limit: 5,
+});
+
+// Validate input
+const validation = await client.tools.validateInput('tool-uuid', {
+  query: 'test',
+});
+if (!validation.valid) {
+  console.log(validation.errors);
+}
+
+// Update tool
+await client.tools.update('tool-uuid', {
+  name: 'Updated Name',
+});
+
+// Update config
+await client.tools.updateConfig('tool-uuid', {
+  isEnabled: false,
+});
+```
+
+### Artifacts
+
+```typescript
+// List artifacts for an execution
+const { data: artifacts } = await client.artifacts.list('execution-uuid', {
+  type: 'file',
+});
+
+// Get artifact metadata
+const artifact = await client.artifacts.get('artifact-uuid');
+
+// Download artifact
+const content = await client.artifacts.download('artifact-uuid');
+// Node.js: Buffer | Browser: Blob
+
+// Download as stream
+const stream = await client.artifacts.downloadStream('artifact-uuid');
+
+// Get signed URL
+const { url, expiresAt } = await client.artifacts.getSignedUrl('artifact-uuid', {
+  expiresIn: 3600, // 1 hour
+});
+
+// Upload artifact
+const artifact = await client.artifacts.upload('execution-uuid', {
+  name: 'report.pdf',
+  content: fileBuffer,
+  mimeType: 'application/pdf',
+});
+
+// Delete artifact
+await client.artifacts.delete('artifact-uuid');
+```
+
+### Sessions
+
+```typescript
+// Create session
+const session = await client.sessions.create({
+  agentUuid: 'agent-uuid',
+  systemMessage: 'You are a helpful assistant.',
+});
+
+// List sessions
+const { data: sessions } = await client.sessions.list({
+  agentUuid: 'agent-uuid',
+});
+
+// Get session
+const session = await client.sessions.get('session-id');
+
+// Send message (async)
+const { executionId } = await client.sessions.sendMessage('session-id', {
+  message: 'What is the capital of France?',
+});
+
+// Send message (sync)
+const execution = await client.sessions.sendMessageSync('session-id', {
+  message: 'Tell me more about that',
+});
+
+// Stream message
+const stream = await client.sessions.stream('session-id', {
+  message: 'Explain in detail',
+});
+const result = await stream.wait();
+
+// Get history
+const history = await client.sessions.getHistory('session-id');
+history.messages.forEach(msg => {
+  console.log(`${msg.role}: ${msg.content}`);
+});
+
+// Delete session
+await client.sessions.delete('session-id');
+```
+
+## Streaming
+
+The SDK supports real-time streaming for agent executions:
+
+```typescript
+const stream = await client.agents.stream('agent-uuid', {
+  task: 'Research climate change and provide a summary',
+});
+
+// Register event handlers
+stream.on('log', (log) => {
+  console.log(`[${log.type}] ${log.title}`);
+  if (log.content) console.log(log.content);
+});
+
+stream.on('toolCall', ({ toolName, inputs }) => {
+  console.log(`Calling tool: ${toolName}`, inputs);
+});
+
+stream.on('toolResult', ({ toolName, result, durationMs }) => {
+  console.log(`Tool ${toolName} completed in ${durationMs}ms`);
+});
+
+stream.on('complete', ({ execution }) => {
+  console.log('Final output:', execution.output);
+});
+
+stream.on('error', ({ error, errorCode }) => {
+  console.error(`Error [${errorCode}]: ${error}`);
+});
+
+stream.on('connectionChange', ({ connected, usingFallback }) => {
+  if (usingFallback) {
+    console.log('Switched to polling fallback');
+  }
+});
+
+// Wait for completion
+const execution = await stream.wait();
+
+// Or cancel
+stream.cancel();
+```
+
+## Error Handling
+
+The SDK provides typed error classes for different error scenarios:
+
+```typescript
+import {
+  AISaaSError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ValidationError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  NetworkError,
+} from '@cadraos/sdk';
+
+try {
+  await client.agents.get('invalid-uuid');
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.log('Agent not found');
+  } else if (error instanceof AuthenticationError) {
+    console.log('Invalid API key');
+  } else if (error instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
+  } else if (error instanceof ValidationError) {
+    error.errors.forEach(e => {
+      console.log(`${e.field}: ${e.message}`);
+    });
+  } else if (error instanceof AISaaSError) {
+    console.log(`Error [${error.code}]: ${error.message}`);
+    console.log('Request ID:', error.requestId);
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+const client = new AISaaSClient({
+  // Required
+  apiKey: 'sk_...',        // or token/tokenProvider
+  orgId: 123,
+
+  // Optional
+  baseUrl: 'https://api.aisaas.com/v1',  // Custom API URL
+  timeout: 30000,                         // Request timeout (ms)
+  maxRetries: 3,                          // Retry attempts
+  headers: {                              // Custom headers
+    'X-Custom-Header': 'value',
+  },
+});
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import type {
+  Agent,
+  AgentExecution,
+  Skill,
+  Tool,
+  Artifact,
+  Session,
+  StreamController,
+} from '@cadraos/sdk';
+```
+
+## Browser Support
+
+The SDK works in modern browsers for non-streaming operations. Streaming (SSE) is only supported in Node.js in v1.
+
+```typescript
+// Works in browser
+const agents = await client.agents.list();
+const execution = await client.agents.executeSync(uuid, { task: '...' });
+
+// Node.js only (v1)
+const stream = await client.agents.stream(uuid, { task: '...' });
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+
+## License
+
+MIT