@applica-software-guru/persona-sdk 0.0.1-preview6 → 0.1.2

package/package.json

@@ -1,7 +1,8 @@
 {
   "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.0.1-preview6",
+  "version": "0.1.2",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -12,56 +13,25 @@
     "format": "prettier --write ."
   },
   "devDependencies": {
-    "@assistant-ui/react": "0.8.17",
-    "@assistant-ui/react-markdown": "0.8.0",
-    "@radix-ui/react-avatar": "^1.1.3",
-    "@radix-ui/react-tooltip": "^1.1.8",
-    "@tailwindcss/vite": "^4.0.17",
-    "@types/inflection": "^1.13.2",
-    "@types/lodash": "^4.17.15",
     "@types/node": "^20.12.13",
-    "@types/react-dom": "^19.1.1",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "@vitejs/plugin-react": "^4.3.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
     "eslint": "^8.25.0",
     "eslint-config-prettier": "^8.10.0",
-    "eslint-config-react-app": "7.0.1",
-    "eslint-plugin-export": "^0.1.2",
-    "eslint-plugin-filenames": "^1.3.2",
-    "eslint-plugin-import": "^2.26.0",
-    "eslint-plugin-jsx-a11y": "^6.6.1",
     "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-react": "^7.31.10",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-react-refresh": "^0.4.19",
-    "eslint-plugin-sort-exports": "^0.9.1",
-    "husky": "^9.0.11",
-    "jsdom": "^22.1.0",
-    "lodash": "^4.17.21",
-    "lucide-react": "^0.485.0",
     "prettier": "^2.8.8",
-    "react": "^19",
-    "react-dom": "^19",
-    "react-markdown": "^10.0.1",
-    "remark-gfm": "^4.0.1",
-    "tailwind-merge": "^3.0.2",
-    "tailwindcss": "^4.0.17",
     "typescript": "^5.4.5",
     "vite": "^5.2.12",
-    "vite-plugin-compression": "^0.5.1",
-    "vite-plugin-dts": "^2.3.0",
-    "vite-plugin-linter": "^2.0.2",
-    "vitest": "^1.6.0"
-  },
-  "peerDependencies": {
-    "@assistant-ui/react": "0.8.17",
-    "react": "^18 || ^19 || ^19.0.0-rc"
+    "vite-plugin-dts": "^4.5.4"
   },
   "keywords": [
-    "persona-sdk"
+    "persona-sdk",
+    "persona",
+    "ai",
+    "sdk",
+    "chatbot",
+    "agents"
   ],
   "main": "dist/bundle.cjs.js",
   "module": "dist/bundle.es.js",

package/src/agents/agents-api.ts

@@ -0,0 +1,54 @@
+import { HttpApi } from '../http-api';
+import { Paginated } from '../paginated';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import {
+  Agent,
+  AgentCreateRequest,
+  AgentUpdateRequest,
+  SynthesizerVoice,
+  Revision,
+} from './types';
+
+export class AgentsApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  async list(keyword?: string | null, page?: number, size?: number): Promise<Paginated<Agent>> {
+    const params: Record<string, unknown> = { page, size };
+    if (keyword) params.keyword = keyword;
+    return this.httpGet<Paginated<Agent>>('/agents', params);
+  }
+
+  async get(agentId: string): Promise<Agent> {
+    return this.httpGet<Agent>('/agents/' + agentId);
+  }
+
+  async create(request: AgentCreateRequest): Promise<Agent> {
+    return this.httpPost<Agent>('/agents', request);
+  }
+
+  async update(request: AgentUpdateRequest): Promise<Agent> {
+    return this.httpPut<Agent>('/agents/' + request.id, request);
+  }
+
+  async remove(agentId: string): Promise<void> {
+    await this.httpDelete('/agents/' + agentId);
+  }
+
+  async getSynthesizerSupportedVoices(synthesizerName: string): Promise<SynthesizerVoice[]> {
+    return this.httpGet<SynthesizerVoice[]>('/values/synthesizers/' + synthesizerName + '/voices');
+  }
+
+  async listRevisions(agentId: string): Promise<Revision[]> {
+    return this.httpGet<Revision[]>('/agents/' + agentId + '/revisions');
+  }
+
+  async getRevision(agentId: string, revisionId: string): Promise<Revision> {
+    return this.httpGet<Revision>('/agents/' + agentId + '/revisions/' + revisionId);
+  }
+
+  async rollback(agentId: string, revisionId: string): Promise<Agent> {
+    return this.httpPost<Agent>('/agents/' + agentId + '/revisions/' + revisionId + '/rollback', {});
+  }
+}

package/src/agents/types.ts

@@ -0,0 +1,346 @@
+export type AgentProtocol = 'webrtc' | 'twilio' | 'rest' | 'websocket' | 'telegram';
+
+export type KnowledgeType = 'multi_hop' | 'simple';
+
+export type LanguageCode = 'en-US' | 'it-IT' | 'es-ES' | 'fr-FR' | 'de-DE' | 'pt-BR';
+
+export type ModelName =
+  | 'gemini-3-pro'
+  | 'gemini-2.5-pro'
+  | 'gemini-2.5-flash'
+  | 'gemini-2.5-flash-lite'
+  | 'gemini-2.0-flash'
+  | 'gemini-1.5-flash'
+  | 'gemini-1.5-pro'
+  | 'gemini-2.5-pro-exp-03-25'
+  | 'gemini-2.0-flash-001'
+  | 'gemini-2.0-flash-lite'
+  | 'gemini-2.0-flash-lite-001'
+  | 'gemini-1.5-flash-latest'
+  | 'gemini-1.5-flash-001'
+  | 'gemini-1.5-flash-002'
+  | 'gemini-1.5-pro-latest'
+  | 'gemini-1.5-pro-001'
+  | 'gemini-1.5-pro-002'
+  | 'gpt-5.2'
+  | 'gpt-5'
+  | 'gpt-5-mini'
+  | 'gpt-5-nano'
+  | 'gpt-4.1'
+  | 'gpt-4.1-mini'
+  | 'gpt-4.1-nano'
+  | 'gpt-4o'
+  | 'gpt-4o-mini'
+  | 'gpt-4.5'
+  | 'o1'
+  | 'o1-mini'
+  | 'o3-mini'
+  | 'o4-mini'
+  | 'o4-mini-high'
+  | 'gpt-3.5-turbo'
+  | 'gpt-3.5-turbo-16k'
+  | 'accounts/fireworks/models/minimax-m2p5'
+  | 'accounts/fireworks/models/deepseek-v3p2'
+  | 'accounts/fireworks/models/kimi-k2p5'
+  | 'accounts/fireworks/models/glm-5'
+  | 'grok-4-1-fast-reasoning'
+  | 'grok-4-1-fast-non-reasoning'
+  | 'grok-code-fast-1'
+  | 'grok-4-fast-reasoning'
+  | 'grok-4-fast-non-reasoning'
+  | 'grok-4-0709'
+  | 'grok-3-mini'
+  | 'grok-3'
+  | 'grok-2-vision-1212'
+  | 'ollama'
+  | 'openai-compatible';
+
+export type SynthesizerName = 'gcloud' | 'elevenlabs' | 'gtts' | 'openai';
+
+export type TranscriberName = 'gcloud' | 'deepgram' | 'vosk';
+
+export type StmType = 'simple' | 'summary';
+
+export type ToolType = 'remote' | 'local';
+
+export type CollaborationMode = 'delegate_and_return' | 'persistent_transfer' | 'consult_then_respond';
+
+export type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
+
+export type ModelProvider = 'google' | 'openai' | 'grok' | 'fireworks' | 'ollama' | 'openai_compatible';
+
+export type AgentType = 'agent';
+
+export interface VariableSource {
+  type?: string;
+  tool?: string;
+  args?: Record<string, unknown>;
+  property?: string;
+  mcpServer?: string;
+  resourceUri?: string;
+}
+
+export interface Variable {
+  name?: string;
+  source?: VariableSource;
+  defaultValue?: unknown;
+}
+
+export interface ModelConfiguration {
+  modelName?: ModelName;
+  temperature?: number;
+  reasoningEffort?: ReasoningEffort;
+  url?: string;
+  ollamaModelName?: string;
+  openaiCompatibleModelName?: string;
+  openaiCompatibleApiKey?: string;
+}
+
+export interface SynthesizerVoice {
+  id?: string;
+  name?: string;
+  languageCodes?: string[];
+  gender?: string;
+}
+
+export interface SynthesizerConfiguration {
+  enabled?: boolean;
+  synthesizerName?: SynthesizerName;
+  languageCode?: LanguageCode;
+  voice?: string;
+  sampleRateHertz?: number;
+  speed?: number;
+  similarityBoost?: number;
+  stability?: number;
+  style?: number;
+  voiceInstructions?: string;
+}
+
+export interface TranscriberConfiguration {
+  enabled?: boolean;
+  transcriberName?: TranscriberName;
+  languageCode?: LanguageCode;
+  sampleRateHertz?: number;
+}
+
+export interface KnowledgeConfiguration {
+  enabled?: boolean;
+  knowledgeType?: KnowledgeType;
+  namespace?: string[];
+  numberOfEntries?: number;
+  args?: Record<string, unknown>;
+  knowledgeBaseId?: string;
+}
+
+export interface CollaborationConfiguration {
+  enabled?: boolean;
+  collaborators?: Collaborator[];
+  mode?: CollaborationMode;
+  maxNumberOfIterations?: number;
+}
+
+export interface Collaborator {
+  name?: string;
+  agent?: string;
+  scope?: string;
+}
+
+export interface OrchestrationAgent {
+  name?: string;
+  agent?: string;
+  scope?: string;
+}
+
+export interface OrchestrationConfiguration {
+  enabled?: boolean;
+  agents?: OrchestrationAgent[];
+  maxParallelCalls?: number;
+}
+
+export interface NetworkConfiguration {
+  allowedWebsites?: string[];
+  allowedIps?: string[];
+}
+
+export interface WakeupConfiguration {
+  enabled?: boolean;
+  wakeupWords?: string[];
+  sleepWords?: string[];
+  sleepInEachRequest?: boolean;
+  sleepDelaySeconds?: number;
+}
+
+export interface TelegramConfiguration {
+  enabled?: boolean;
+  botToken?: string;
+  enabledUsers?: string[];
+}
+
+export interface TwilioConfiguration {
+  phoneNumber?: string;
+}
+
+export interface WhatsAppConfiguration {
+  phoneNumberId?: string;
+  enabledUsers?: string[];
+}
+
+export interface SkillResource {
+  path?: string;
+  content?: string;
+  contentType?: string;
+}
+
+export interface SkillConfiguration {
+  name?: string;
+  description?: string;
+  instructions?: string;
+  allowedTools?: string[];
+  metadata?: Record<string, unknown>;
+  resources?: SkillResource[];
+}
+
+export interface McpServerConfiguration {
+  type?: string;
+  name?: string;
+  transport?: Transport;
+  enabledTools?: string[];
+  disabledTools?: string[];
+}
+
+export interface FlagConfiguration {
+  type?: string;
+  flag?: string;
+}
+
+export type FeatureConfiguration = McpServerConfiguration | FlagConfiguration | SkillConfiguration;
+
+export interface HttpTransport {
+  url?: string;
+  enablePersonaAuth?: boolean;
+}
+
+export interface StdioTransport {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+}
+
+export type Transport = HttpTransport | StdioTransport;
+
+export interface Feature {
+  id?: string;
+  templateId?: string;
+  credentialsId?: string;
+}
+
+export interface ToolLocalConfig {
+  parameters?: Record<string, unknown>;
+  output?: Record<string, unknown>;
+}
+
+export interface ToolRemoteConfig {
+  serviceUrl?: string;
+  secret?: string;
+  timeout?: number;
+}
+
+export type ToolConfig = ToolLocalConfig | ToolRemoteConfig;
+
+export interface ToolDefinition {
+  name?: string;
+  description?: string;
+  parameters?: Record<string, unknown>;
+  output?: Record<string, unknown>;
+}
+
+export interface Tool {
+  type?: ToolType;
+  name?: string;
+  description?: string;
+  config?: ToolConfig;
+}
+
+export interface ToolkitConfiguration {
+  tools?: Tool[];
+}
+
+export interface StmConfiguration {
+  type?: StmType;
+  maxMessages?: number;
+  includeToolCalls?: boolean;
+  model?: ModelConfiguration;
+  maxNumberOfWords?: number;
+}
+
+export interface Revision {
+  id?: string;
+  entityId?: string;
+  projectId?: string;
+  revisionNumber?: number;
+  createdAt?: string;
+  snapshot?: Record<string, unknown>;
+}
+
+export interface Agent {
+  id?: string;
+  projectId?: string;
+  apiKey?: string;
+  code?: string;
+  name?: string;
+  description?: string;
+  type?: AgentType;
+  synthesizer?: SynthesizerConfiguration;
+  transcriber?: TranscriberConfiguration;
+  model?: ModelConfiguration;
+  systemInstructions?: string;
+  variables?: Variable[];
+  enabledProtocols?: AgentProtocol[];
+  twilio?: TwilioConfiguration;
+  languageCode?: LanguageCode;
+  initialMessage?: string;
+  knowledge?: KnowledgeConfiguration;
+  wakeup?: WakeupConfiguration;
+  telegram?: TelegramConfiguration;
+  whatsapp?: WhatsAppConfiguration;
+  collaboration?: CollaborationConfiguration;
+  orchestration?: OrchestrationConfiguration;
+  network?: NetworkConfiguration;
+  features?: Feature[];
+  toolkit?: ToolkitConfiguration;
+  shortTermMemory?: StmConfiguration;
+  responseSchema?: Record<string, unknown>;
+  verboseErrors?: boolean;
+}
+
+export interface AgentCreateRequest {
+  projectId?: string;
+  code?: string;
+  name?: string;
+  description?: string;
+  type?: AgentType;
+  synthesizer?: SynthesizerConfiguration;
+  transcriber?: TranscriberConfiguration;
+  model?: ModelConfiguration;
+  systemInstructions?: string;
+  variables?: Variable[];
+  enabledProtocols?: AgentProtocol[];
+  twilio?: TwilioConfiguration;
+  languageCode?: LanguageCode;
+  initialMessage?: string;
+  knowledge?: KnowledgeConfiguration;
+  wakeup?: WakeupConfiguration;
+  telegram?: TelegramConfiguration;
+  whatsapp?: WhatsAppConfiguration;
+  collaboration?: CollaborationConfiguration;
+  orchestration?: OrchestrationConfiguration;
+  network?: NetworkConfiguration;
+  features?: Feature[];
+  toolkit?: ToolkitConfiguration;
+  shortTermMemory?: StmConfiguration;
+  responseSchema?: Record<string, unknown>;
+  verboseErrors?: boolean;
+}
+
+export interface AgentUpdateRequest extends Agent {}

package/src/auth/api-key-auth.ts

@@ -0,0 +1,13 @@
+import { AuthenticationProvider } from './authentication-provider';
+
+export class ApiKeyAuthenticationProvider implements AuthenticationProvider {
+  constructor(private readonly apiKey: string) {}
+
+  applyHeaders(headers: Headers): void {
+    headers.set('x-persona-apikey', this.apiKey);
+  }
+
+  getCredentials(): string {
+    return this.apiKey;
+  }
+}

package/src/auth/authentication-provider.ts

@@ -0,0 +1,4 @@
+export interface AuthenticationProvider {
+  applyHeaders(headers: Headers): void;
+  getCredentials(): string;
+}

package/src/auth/bearer-token-auth.ts

@@ -0,0 +1,13 @@
+import { AuthenticationProvider } from './authentication-provider';
+
+export class BearerTokenAuthenticationProvider implements AuthenticationProvider {
+  constructor(private readonly token: string) {}
+
+  applyHeaders(headers: Headers): void {
+    headers.set('Authorization', `Bearer ${this.token}`);
+  }
+
+  getCredentials(): string {
+    return this.token;
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,3 @@
+export type { AuthenticationProvider } from './authentication-provider';
+export { ApiKeyAuthenticationProvider } from './api-key-auth';
+export { BearerTokenAuthenticationProvider } from './bearer-token-auth';

package/src/credentials/credentials-api.ts

@@ -0,0 +1,40 @@
+import { HttpApi } from '../http-api';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import {
+  Credentials,
+  AuthorizeRequest,
+  AuthorizeResponse,
+  OAuth2CallbackResponse,
+} from './types';
+
+export class CredentialsApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  async authorize(provider: string, request: AuthorizeRequest): Promise<AuthorizeResponse> {
+    return this.httpPost<AuthorizeResponse>('/credentials/' + provider + '/authorize', request);
+  }
+
+  async handleOAuth2Callback(provider: string, code: string, state: string, scope?: string): Promise<OAuth2CallbackResponse> {
+    const params: Record<string, unknown> = { code, state };
+    if (scope) params.scope = scope;
+    return this.httpGet<OAuth2CallbackResponse>('/credentials/' + provider + '/oauth2/callback', params);
+  }
+
+  async list(): Promise<Credentials[]> {
+    return this.httpGet<Credentials[]>('/credentials');
+  }
+
+  async getByProvider(provider: string): Promise<Credentials[]> {
+    return this.httpGet<Credentials[]>('/credentials/' + provider);
+  }
+
+  async getById(credentialsId: string): Promise<Credentials> {
+    return this.httpGet<Credentials>('/credentials/all/' + credentialsId);
+  }
+
+  async remove(credentialsId: string): Promise<void> {
+    await this.httpDelete('/credentials/all/' + credentialsId);
+  }
+}

package/src/credentials/types.ts

@@ -0,0 +1,67 @@
+export interface Credentials {
+  id?: string;
+  name?: string;
+  projectId?: string;
+  provider?: string;
+  obtainedAt?: string;
+  validUntil?: string;
+  data?: unknown;
+  clientId?: string;
+  clientSecret?: string;
+  apiKey?: string;
+  apiSecret?: string;
+  token?: string;
+  successUrl?: string;
+  active?: boolean;
+  server?: string;
+  port?: number;
+  useSsl?: boolean;
+  username?: string;
+  password?: string;
+}
+
+export interface AuthorizeRequest {
+  name?: string;
+  provider?: string;
+  clientId?: string;
+  clientSecret?: string;
+  scope?: string;
+  apiKey?: string;
+  apiSecret?: string;
+  token?: string;
+  successUrl?: string;
+  server?: string;
+  port?: number;
+  useSsl?: boolean;
+  username?: string;
+  password?: string;
+}
+
+export interface OAuth2State {
+  id?: string;
+  credentialsName?: string;
+  projectId?: string;
+  provider?: string;
+  status?: string;
+  code?: string;
+  scope?: string;
+  clientId?: string;
+  clientSecret?: string;
+  apiKey?: string;
+  apiSecret?: string;
+  token?: string;
+  successUrl?: string;
+}
+
+export interface AuthorizeResponse {
+  credentials?: Credentials;
+  state?: OAuth2State;
+  redirectUrl?: string;
+}
+
+export interface OAuth2CallbackResponse {
+  id?: string;
+  successUrl?: string;
+  success?: boolean;
+  error?: string;
+}

package/src/exceptions.ts

@@ -0,0 +1,10 @@
+export class ApiException extends Error {
+  public readonly statusCode: number;
+  public readonly body: string;
+
+  constructor(statusCode: number, body: string) {
+    super(`API Error: ${statusCode} - ${body}`);
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+}

package/src/features/feature-templates-api.ts

@@ -0,0 +1,41 @@
+import { HttpApi } from '../http-api';
+import { Paginated } from '../paginated';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { FeatureTemplate, McpToolsResponse } from './types';
+import { McpServerConfiguration } from '../agents/types';
+
+export class FeatureTemplatesApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  async list(keyword?: string | null, page?: number, size?: number): Promise<Paginated<FeatureTemplate>> {
+    const params: Record<string, unknown> = { page, size };
+    if (keyword) params.keyword = keyword;
+    return this.httpGet<Paginated<FeatureTemplate>>('/features/templates', params);
+  }
+
+  async get(templateId: string): Promise<FeatureTemplate> {
+    return this.httpGet<FeatureTemplate>('/features/templates/' + templateId);
+  }
+
+  async create(template: FeatureTemplate): Promise<FeatureTemplate> {
+    return this.httpPost<FeatureTemplate>('/features/templates', template);
+  }
+
+  async update(templateId: string, template: FeatureTemplate): Promise<FeatureTemplate> {
+    return this.httpPut<FeatureTemplate>('/features/templates/' + templateId, template);
+  }
+
+  async patch(templateId: string, template: FeatureTemplate): Promise<FeatureTemplate> {
+    return this.httpPatch<FeatureTemplate>('/features/templates/' + templateId, template);
+  }
+
+  async remove(templateId: string): Promise<void> {
+    await this.httpDelete('/features/templates/' + templateId);
+  }
+
+  async getMcpAvailableTools(configuration: McpServerConfiguration): Promise<McpToolsResponse> {
+    return this.httpPost<McpToolsResponse>('/features/templates/mcp/available-tools', configuration);
+  }
+}

package/src/features/features-api.ts

@@ -0,0 +1,16 @@
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { FeatureTemplatesApi } from './feature-templates-api';
+
+export class FeaturesApi {
+  private readonly baseUrl: string;
+  private readonly auth: string | AuthenticationProvider;
+
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    this.baseUrl = baseUrl;
+    this.auth = auth;
+  }
+
+  templates(): FeatureTemplatesApi {
+    return new FeatureTemplatesApi(this.baseUrl, this.auth);
+  }
+}