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',       // persona-core base URL
  'https://persona.applica.guru/workflows', // workflows service base URL
  'https://persona.applica.guru/billing'    // billing service base URL (optional)
);

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

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

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. When using PersonaSdk, the billing base URL is configured in the constructor and billing() follows the same authentication pattern as all other APIs.

// 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: '[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 });

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:

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

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

MIT