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

npm install @applica-software-guru/persona-sdk

Quick Start

import { PersonaSdk } from '@applica-software-guru/persona-sdk';

const sdk = new PersonaSdk(
  'https://persona.applica.guru/api',
  'https://persona.applica.guru/workflows'
);

// 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 takes the base URL of persona-core and (optionally) the base URL of the workflows service. 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

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:

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:

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

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

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

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

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

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

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

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

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

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. It uses a separate base URL and can be instantiated directly or via PersonaSdk.

import { BillingClient } from '@applica-software-guru/persona-sdk';

// Standalone usage
const billing = new BillingClient('https://persona.applica.guru/billing', 'your-api-key');

// Or via PersonaSdk
const billing = sdk.billing('your-api-key');

// Customer management
const customer = await billing.createCustomer({
  owner: 'user-123',
  name: 'Acme Corp',
  email: '[email protected]',
});
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 });

Error Handling

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 | | 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

MIT