@applica-software-guru/persona-sdk 0.1.96 → 0.1.101

package/.eslintrc.cjs

@@ -1,11 +1,12 @@
 module.exports = {
   root: true,
-  env: { browser: true, es2020: true },
-  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'plugin:react-hooks/recommended'],
-  ignorePatterns: ['dist', '.eslintrc.cjs'],
+  env: { node: true, browser: true, es2022: true },
   parser: '@typescript-eslint/parser',
-  plugins: ['react-refresh'],
+  parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+  plugins: ['@typescript-eslint', 'prettier'],
+  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'prettier'],
   rules: {
-    'react-refresh/only-export-components': ['none', { allowConstantExport: true }],
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
   },
 };

package/.nvmrc

@@ -1 +1 @@
-22
+22

package/.prettierignore

@@ -1,5 +1,3 @@
-# Ignore artifacts:
-build
-
-# Ignore all HTML files:
-**/*.html
+node_modules/
+dist/
+*.md

package/.prettierrc

@@ -1,8 +1,6 @@
 {
-  "bracketSpacing": true,
-  "printWidth": 140,
+  "semi": true,
   "singleQuote": true,
-  "tabWidth": 2,
-  "trailingComma": "all",
-  "useTabs": false
+  "trailingComma": "es5",
+  "printWidth": 120
 }

package/README.md

@@ -1,33 +1,373 @@
-# Persona SDK ⚙️
+# 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)
-[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](#)
-[![Documentation](https://img.shields.io/badge/docs-available-blue)](docs/README.md)
 
-Persona SDK is the official SDK for the Persona API. It provides a simple and efficient way to integrate the Persona API into your applications using [assistant-ui](https://www.assistant-ui.com/).
+Official TypeScript SDK for the Persona API. Manage agents, sessions, projects, knowledge bases, workflows, triggers, missions and more from any JavaScript/TypeScript application.
 
----
+## Install
 
-## Table of Contents
+```bash
+npm install @applica-software-guru/persona-sdk
+```
 
-- [Features](docs/features.md)
-- [Installation](docs/installation.md)
-- [Usage](docs/usage.md)
-- [Messages and Storage](docs/messages.md)
-- [Protocols Overview](docs/protocols.md)
-- [API Reference](docs/api-reference.md)
-- [Transactions and Tools](docs/transactions.md)
-- [Customization](docs/customization.md)
-- [Contributing](docs/contributing.md)
+## Quick Start
 
----
+```typescript
+import { PersonaSdk } from '@applica-software-guru/persona-sdk';
 
-## Support
+const sdk = new PersonaSdk(
+  'https://persona.applica.guru/api',       // persona-core base URL
+  'https://persona.applica.guru/workflows', // workflows service base URL
+  'https://persona.applica.guru/billing'    // billing service base URL (optional)
+);
 
-For questions or support, contact us at [info@applica.guru](mailto:info@applica.guru).
+// Authenticate with a project API key
+const agents = await sdk.agents('prs_your_project_api_key').list(null, 1, 20);
+console.log(`Total agents: ${agents.total}`);
+```
 
----
+The `PersonaSdk` constructor accepts:
+1. **`baseUrl`** — persona-core API base URL (required)
+2. **`workflowsBaseUrl`** — workflows service base URL (required)
+3. **`billingBaseUrl`** — billing service base URL (optional, defaults to `https://persona.applica.guru/billing`)
+
+Each resource is exposed as a factory method that requires authentication credentials.
+
+## Authentication
+
+The SDK supports two authentication methods. Pass either a string (API key) or
+an `AuthenticationProvider` instance to any resource factory.
+
+### API Key
+
+The simplest method — pass the API key string directly. The SDK wraps it in an
+`ApiKeyAuthenticationProvider` and sends it as the `x-persona-apikey` header.
+
+Accepts:
+
+- **Master key** — full admin access (server-to-server only)
+- **Project API key** (`prs_...`) — scoped to a single project
+- **Agent API key** (`prs_ag_...`) — scoped to a single agent
+
+```typescript
+const projects = await sdk.projects('prs_your_project_api_key').getMine();
+```
+
+### IAM Bearer Token
+
+For applications that authenticate end users via IAM, pass a
+`BearerTokenAuthenticationProvider` with a valid JWT:
+
+```typescript
+import { BearerTokenAuthenticationProvider } from '@applica-software-guru/persona-sdk';
+
+const auth = new BearerTokenAuthenticationProvider(iamJwtToken);
+const projects = await sdk.projects(auth).getMine();
+```
+
+The token is sent as the `Authorization: Bearer <token>` header. The server
+validates it via the IAM service and resolves the user's project automatically.
+Use this method when building user-facing apps (e.g. control panels) where the
+user logs in through IAM.
+
+### Custom provider
+
+Implement your own provider via the `AuthenticationProvider` interface:
+
+```typescript
+import { AuthenticationProvider } from '@applica-software-guru/persona-sdk';
+
+class MyProvider implements AuthenticationProvider {
+  applyHeaders(headers: Headers): void {
+    headers.set('x-custom-header', 'value');
+  }
+
+  getCredentials(): string {
+    return 'my-credentials';
+  }
+}
+```
+
+## Usage Examples
+
+### Agents
+
+```typescript
+const agentsApi = sdk.agents('your-api-key');
+
+// List agents (with optional server-side filters)
+const { items, total } = await agentsApi.list('search-term', 1, 20);
+
+// Filter by project
+const projectAgents = await agentsApi.list(null, 1, 20, { projectId: 'my-project-id' });
+
+// 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');
+
+// Generate system instructions with AI (project-scoped architect)
+const instructions = await agentsApi.generateSystemInstructions(
+  'Create a customer support agent that handles billing inquiries',
+  'optional-session-id', // for multi-turn refinement
+);
+
+// Get the project's architect agent configuration
+const architect = await agentsApi.getArchitect();
+```
+
+### 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);
+```
+
+### Billing
+
+The `BillingClient` manages customers, subscriptions, credits and invoices.
+When using `PersonaSdk`, the billing base URL is configured in the constructor
+and `billing()` follows the same authentication pattern as all other APIs.
+
+```typescript
+// Via PersonaSdk (recommended) — uses billingBaseUrl from constructor
+const billing = sdk.billing('your-api-key');
+const billing = sdk.billing(new BearerTokenAuthenticationProvider(token));
+
+// Standalone usage with explicit base URL
+import { BillingClient } from '@applica-software-guru/persona-sdk';
+const billing = new BillingClient('https://persona.applica.guru/billing', 'your-api-key');
+
+// Customer management
+const customer = await billing.createCustomer({
+  owner: 'user-123',
+  name: 'Acme Corp',
+  email: 'billing@acme.com',
+});
+const existing = await billing.getCustomer('user-123');
+await billing.updateCustomer('user-123', { name: 'Acme Inc.' });
+await billing.deleteCustomer('user-123');
+
+// Subscription management
+const subscription = await billing.createSubscription({ owner: 'user-123' });
+const current = await billing.getSubscription('user-123');
+await billing.cancelSubscription('user-123');
+
+// Plan changes
+await billing.beginUpgrade('user-123', { toPlanType: 'pro' });
+await billing.downgrade('user-123', { toPlanType: 'starter' });
+await billing.mentorize('user-123', { endDate: '2026-12-31' });
+
+// Credits
+await billing.addCredits('user-123', 100);
+await billing.useCredits('user-123', 10, ['chat', 'voice'], 'reference-id');
+const credits = await billing.getCredits('user-123');
+const valid = await billing.isValid('user-123');
+
+// Invoices
+const invoices = await billing.listInvoices('user-123', '2026-01-01', '2026-12-31');
+
+// Project-level billing
+const projectSub = await billing.getProjectSubscription('project-id');
+await billing.changeProjectSubscriptionPlan('project-id', { toPlanType: 'pro' });
+await billing.addProjectSubscriptionCredits('project-id', { credits: 50 });
+```
+
+## Server-side Filtering
+
+All paginated `list` methods accept an optional `extraParams` argument as the
+last parameter. These key-value pairs are appended to the query string, enabling
+server-side filters such as `projectId`:
+
+```typescript
+// Filter agents by project
+const agents = await sdk.agents(auth).list(null, 1, 20, { projectId: 'abc123' });
+
+// Combine keyword search with project filter
+const results = await sdk.knowledgeBases(auth).list('my-kb', 1, 20, { projectId: 'abc123' });
+```
+
+Supported on: `AgentsApi`, `KnowledgeBasesApi`, `WorkflowsApi`, `TriggersApi`,
+`FeatureTemplatesApi`, `ServicePricesApi`.
+
+## 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`, `generateSystemInstructions`, `getArchitect` |
+| **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` |
+| **BillingClient** | `createCustomer`, `updateCustomer`, `getCustomer`, `saveCustomer`, `deleteCustomer`, `createSubscription`, `getSubscription`, `cancelSubscription`, `beginUpgrade`, `downgrade`, `mentorize`, `addCredits`, `useCredits`, `getCredits`, `isValid`, `listInvoices`, `getProjectSubscription`, `changeProjectSubscriptionPlan`, `addProjectSubscriptionCredits` |
+
+## 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
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+MIT

package/bitbucket-pipelines.yml

@@ -1,4 +1,4 @@
-image: node:20
+image: node:22
 
 pipelines:
   branches:
@@ -7,13 +7,14 @@ pipelines:
           name: Deploy
           deployment: Production
           script:
-            - export VERSION=0.1
-            - npm --no-git-tag-version version "$VERSION.$BITBUCKET_BUILD_NUMBER" -m "Upgrade to new version"
+            - export VERSION_PREFIX=0.1
+            - export PACKAGE_VERSION=$(npm view @applica-software-guru/persona-sdk versions --json | node -e "const versions = JSON.parse(require('fs').readFileSync(0, 'utf8')); const prefix = process.env.VERSION_PREFIX + '.'; const patches = versions.filter(v => v.startsWith(prefix) && !v.includes('-')).map(v => Number(v.slice(prefix.length))).filter(Number.isFinite); console.log(process.env.VERSION_PREFIX + '.' + (Math.max(...patches, 0) + 1));")
+            - npm --no-git-tag-version version "$PACKAGE_VERSION" -m "Upgrade to new version"
             - npm install
             - npm run build
             - pipe: atlassian/npm-publish:0.3.2
               variables:
                 NPM_TOKEN: $NPM_TOKEN
                 EXTRA_ARGS: '--access public'
-            - git tag -a "$VERSION.$BITBUCKET_BUILD_NUMBER" -m "Version $VERSION.$BITBUCKET_BUILD_NUMBER"
-            - git push origin "$VERSION.$BITBUCKET_BUILD_NUMBER"
+            - git tag -a "$PACKAGE_VERSION" -m "Version $PACKAGE_VERSION"
+            - git push origin "$PACKAGE_VERSION"