@applica-software-guru/persona-sdk 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,248 @@
+# Persona SDK
+
+[![npm version](https://img.shields.io/npm/v/@applica-software-guru/persona-sdk)](https://www.npmjs.com/package/@applica-software-guru/persona-sdk)
+
+Official TypeScript SDK for the Persona API. Manage agents, sessions, projects, knowledge bases, workflows, triggers, missions and more from any JavaScript/TypeScript application.
+
+## Install
+
+```bash
+npm install @applica-software-guru/persona-sdk
+```
+
+## Quick Start
+
+```typescript
+import { PersonaSdk } from '@applica-software-guru/persona-sdk';
+
+const sdk = new PersonaSdk(
+  'https://persona.applica.guru/api',
+  'https://persona.applica.guru/workflows'
+);
+
+// Authenticate with API key
+const agents = await sdk.agents('your-api-key').list(null, 1, 20);
+```
+
+## Authentication
+
+The SDK supports two authentication methods:
+
+### API Key (default)
+
+```typescript
+const projects = await sdk.projects('your-api-key').getMine();
+```
+
+### Bearer Token (IAM)
+
+```typescript
+import { BearerTokenAuthenticationProvider } from '@applica-software-guru/persona-sdk';
+
+const auth = new BearerTokenAuthenticationProvider('your-iam-token');
+const projects = await sdk.projects(auth).getMine();
+```
+
+## Usage Examples
+
+### Agents
+
+```typescript
+const agentsApi = sdk.agents('your-api-key');
+
+// List agents
+const { items, total } = await agentsApi.list('search-term', 1, 20);
+
+// Get a single agent
+const agent = await agentsApi.get('agent-id');
+
+// Create an agent
+const agent = await agentsApi.create({
+  name: 'My Agent',
+  description: 'A helpful assistant',
+  systemInstructions: 'You are a helpful assistant.',
+});
+
+// Update an agent
+const updated = await agentsApi.update({
+  id: 'agent-id',
+  name: 'Updated Name',
+});
+
+// Delete an agent
+await agentsApi.remove('agent-id');
+```
+
+### Sessions
+
+```typescript
+const sessionsApi = sdk.sessions('your-api-key');
+
+// List sessions
+const sessions = await sessionsApi.list(null, null, null, null, 1, 20);
+
+// Generate a message
+const response = await sessionsApi.generateMessage('session-code', {
+  userMessage: 'Hello, how are you?',
+});
+
+// Get session messages
+const messages = await sessionsApi.findMessages('session-code', 1, 50);
+
+// Get usage info
+const usage = await sessionsApi.getUsage('session-id');
+```
+
+### Projects
+
+```typescript
+const projectsApi = sdk.projects('your-api-key');
+
+// Get current project
+const project = await projectsApi.getMine();
+
+// Create a project
+const project = await projectsApi.create({ name: 'My Project' });
+
+// Get subscription info
+const subscription = await projectsApi.getSubscription('project-id');
+```
+
+### Knowledge Bases
+
+```typescript
+const kbApi = sdk.knowledgeBases('your-api-key');
+
+// List knowledge bases
+const knowledgeBases = await kbApi.list(null, 1, 20);
+
+// Create a knowledge base
+const kb = await kbApi.create({ name: 'My Knowledge Base' });
+
+// Upload a document
+const doc = await kbApi.documents(kb.id).upload({
+  name: 'document.pdf',
+  uri: 'https://example.com/document.pdf',
+});
+
+// Search chunks
+const chunks = await kbApi.searchChunks(kb.id, { query: 'search term', limit: 5 });
+```
+
+### Workflows
+
+```typescript
+const workflowsApi = sdk.workflows('your-api-key');
+
+// List workflows
+const workflows = await workflowsApi.list(null, 1, 20);
+
+// Execute a workflow
+const execution = await workflowsApi.executions().run('workflow-id', {
+  userId: 'user-123',
+  initialData: { key: 'value' },
+});
+```
+
+### Credentials
+
+```typescript
+const credentialsApi = sdk.credentials('your-api-key');
+
+// List credentials
+const creds = await credentialsApi.list();
+
+// Authorize OAuth2
+const result = await credentialsApi.authorize('google', {
+  name: 'My Google Account',
+  clientId: '...',
+  clientSecret: '...',
+});
+```
+
+### Triggers
+
+```typescript
+const triggersApi = sdk.triggers('your-api-key');
+
+// List triggers
+const triggers = await triggersApi.list(null, 1, 20);
+
+// Execute a trigger
+const result = await triggersApi.executions().execute('trigger-id', {});
+```
+
+### Features
+
+```typescript
+const featuresApi = sdk.features('your-api-key');
+
+// List feature templates
+const templates = await featuresApi.templates().list(null, 1, 20);
+
+// Get MCP available tools
+const tools = await featuresApi.templates().getMcpAvailableTools({
+  type: 'mcp',
+  name: 'my-server',
+  transport: { url: 'https://mcp.example.com' },
+});
+```
+
+### Missions
+
+```typescript
+const missionsApi = sdk.missions('your-api-key');
+
+// List missions
+const missions = await missionsApi.list(null, null, 1, 20);
+
+// Create and execute
+const mission = await missionsApi.create({ name: 'My Mission' });
+await missionsApi.execute(mission.id);
+```
+
+## Error Handling
+
+```typescript
+import { ApiException } from '@applica-software-guru/persona-sdk';
+
+try {
+  const agent = await sdk.agents('api-key').get('invalid-id');
+} catch (error) {
+  if (error instanceof ApiException) {
+    console.error(`API Error ${error.statusCode}: ${error.body}`);
+  } else {
+    throw error;
+  }
+}
+```
+
+## API Reference
+
+| Resource | Methods |
+|---|---|
+| **ProjectsApi** | `list`, `get`, `getMine`, `create`, `update`, `remove`, `getSubscription`, `changeSubscriptionPlan`, `addSubscriptionCredits` |
+| **AgentsApi** | `list`, `get`, `create`, `update`, `remove`, `getSynthesizerSupportedVoices`, `listRevisions`, `getRevision`, `rollback` |
+| **SessionsApi** | `list`, `get`, `getUsage`, `generateMessage`, `findMessages`, `remove` |
+| **KnowledgeBasesApi** | `list`, `get`, `create`, `update`, `remove`, `documents()`, `searchChunks` |
+| **KnowledgeBaseDocumentsApi** | `list`, `upload`, `get`, `reprocess`, `remove` |
+| **WorkflowsApi** | `list`, `create`, `update`, `remove`, `get`, `executions()`, `listRevisions`, `getRevision`, `rollback` |
+| **WorkflowExecutionsApi** | `list`, `get`, `run`, `queue` |
+| **CredentialsApi** | `authorize`, `handleOAuth2Callback`, `list`, `getByProvider`, `getById`, `remove` |
+| **TriggersApi** | `list`, `create`, `update`, `remove`, `get`, `executions()` |
+| **TriggerExecutionsApi** | `list`, `execute`, `get`, `remove` |
+| **FeaturesApi** | `templates()` |
+| **FeatureTemplatesApi** | `list`, `get`, `create`, `update`, `patch`, `remove`, `getMcpAvailableTools` |
+| **MissionsApi** | `list`, `get`, `create`, `update`, `remove`, `generate`, `execute`, `retry`, `replan`, `sendInstruction`, `stop`, `resume` |
+| **ServicePricesApi** | `list`, `get`, `create`, `update`, `remove` |
+
+## Compatibility
+
+- **Runtime**: Browser (Chrome, Firefox, Safari, Edge), Node.js 18+
+- **Frameworks**: React, Vue, Angular, Svelte, Next.js, Vite, Webpack
+- **Module systems**: ESM, CommonJS
+- **TypeScript**: Full type definitions included
+
+## License
+
+MIT

package/package.json

@@ -2,7 +2,7 @@
   "name": "@applica-software-guru/persona-sdk",
   "description": "Official TypeScript SDK for the Persona API — manage agents, sessions, projects, knowledge bases, workflows, triggers and more.",
   "private": false,
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "scripts": {
     "dev": "vite",