@applica-software-guru/persona-chat-sdk 0.1.102

package/src/tools.ts

@@ -0,0 +1,211 @@
+export type ToolParameterType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+
+export interface ToolParameter {
+  type: ToolParameterType;
+  description: string;
+  required?: boolean;
+  properties?: Record<string, ToolParameter>;
+  items?: ToolParameter;
+}
+
+export interface ToolSchema {
+  type: 'local';
+  name: string;
+  description: string;
+  config: {
+    timeout: number;
+    parameters: {
+      type: 'object';
+      title: string;
+      required: string[];
+      properties: Record<string, ToolParameter>;
+    };
+    output: {
+      type: 'object';
+      title: string;
+      properties: Record<string, ToolParameter>;
+    };
+  };
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  title?: string;
+  timeout?: number;
+  parameters: Record<string, ToolParameter>;
+  output: Record<string, ToolParameter>;
+  implementation: (...args: any[]) => any;
+}
+
+/**
+ * Create a tool parameter definition
+ */
+export function createParameter(
+  type: ToolParameterType,
+  description: string,
+  options?: {
+    required?: boolean;
+    properties?: Record<string, ToolParameter>;
+    items?: ToolParameter;
+  },
+): ToolParameter {
+  return {
+    type,
+    description,
+    ...options,
+  };
+}
+
+/**
+ * Generate a tool schema from a tool definition
+ */
+export function generateToolSchema(definition: ToolDefinition): ToolSchema {
+  const requiredParams = Object.entries(definition.parameters)
+    .filter(([_, param]) => param.required)
+    .map(([name]) => name);
+
+  return {
+    type: 'local',
+    name: definition.name,
+    description: definition.description,
+    config: {
+      timeout: definition.timeout || 60,
+      parameters: {
+        type: 'object',
+        title: definition.title || `${definition.name} parameters`,
+        required: requiredParams,
+        properties: definition.parameters,
+      },
+      output: {
+        type: 'object',
+        title: `${definition.name} output`,
+        properties: definition.output,
+      },
+    },
+  };
+}
+
+export type ToolInstance = { schema: ToolSchema; implementation: (...args: any[]) => any };
+
+/**
+ * Create a complete tool definition with schema and implementation
+ */
+export function createTool(definition: ToolDefinition): ToolInstance {
+  return {
+    schema: generateToolSchema(definition),
+    implementation: definition.implementation,
+  };
+}
+
+/**
+ * Extract function signature and generate schema from a JavaScript function
+ * This is a utility to help convert existing functions to tool schemas
+ */
+export function createToolFromFunction(
+  name: string,
+  description: string,
+  fn: (...args: any[]) => any,
+  parameterTypes: Record<string, ToolParameter>,
+  outputTypes: Record<string, ToolParameter>,
+  options?: {
+    title?: string;
+    timeout?: number;
+  },
+): ToolInstance {
+  const definition: ToolDefinition = {
+    name,
+    description,
+    title: options?.title,
+    timeout: options?.timeout,
+    parameters: parameterTypes,
+    output: outputTypes,
+    implementation: fn,
+  };
+
+  return createTool(definition);
+}
+
+// Example usage for the sum function you provided:
+export const sumTool = createToolFromFunction(
+  'sum',
+  'Sum two numbers',
+  function sum(a: number, b: number) {
+    const result = a + b;
+    return { result };
+  },
+  {
+    a: createParameter('number', 'First number to sum', { required: true }),
+    b: createParameter('number', 'Second number to sum', { required: true }),
+  },
+  {
+    result: createParameter('number', 'Sum of two numbers'),
+  },
+);
+
+// Example for the navigate_to function as shown in the user's request:
+export const navigateToToolExample = createTool({
+  name: 'navigate_to',
+  description: 'Allow agent to redirect user to specific sub page like /foo or #/foo or anything like that',
+  title: 'Sum two numbers', // As per the user's example
+  timeout: 60,
+  parameters: {
+    a: createParameter('number', 'First number to sum'),
+    b: createParameter('number', 'Seconth number to sum'), // Keeping the typo as in the original
+  },
+  output: {
+    result: createParameter('number', 'Sum of two numbers'),
+  },
+  implementation: function navigateTo(a: number, b: number) {
+    // This is just an example - you would implement actual navigation logic here
+    const result = a + b;
+    return { result };
+  },
+});
+
+// Helper function to create multiple tools at once
+export function createToolRegistry(tools: ToolDefinition[]): {
+  schemas: ToolSchema[];
+  implementations: Record<string, (...args: any[]) => any>;
+} {
+  const schemas: ToolSchema[] = [];
+  const implementations: Record<string, (...args: any[]) => any> = {};
+
+  tools.forEach((tool) => {
+    const { schema, implementation } = createTool(tool);
+    schemas.push(schema);
+    implementations[tool.name] = implementation;
+  });
+
+  return { schemas, implementations };
+}
+
+// Utility to validate tool parameters at runtime
+export function validateToolParameters(parameters: Record<string, any>, schema: ToolSchema): boolean {
+  const { required, properties } = schema.config.parameters;
+
+  // Check required parameters
+  for (const requiredParam of required) {
+    if (!(requiredParam in parameters)) {
+      throw new Error(`Missing required parameter: ${requiredParam}`);
+    }
+  }
+
+  // Type checking (basic)
+  for (const [paramName, paramValue] of Object.entries(parameters)) {
+    const paramSchema = properties[paramName];
+    if (paramSchema) {
+      if (paramSchema.type === 'number' && typeof paramValue !== 'number') {
+        throw new Error(`Parameter ${paramName} should be a number`);
+      }
+      if (paramSchema.type === 'string' && typeof paramValue !== 'string') {
+        throw new Error(`Parameter ${paramName} should be a string`);
+      }
+      if (paramSchema.type === 'boolean' && typeof paramValue !== 'boolean') {
+        throw new Error(`Parameter ${paramName} should be a boolean`);
+      }
+    }
+  }
+
+  return true;
+}

package/src/types.ts

@@ -0,0 +1,284 @@
+import { PersonaTools } from 'src/protocol';
+import { ReactNode } from 'react';
+import type { ToolInstance } from './tools';
+import type { PersonaLogger } from './logging';
+import type { SessionStorage } from './storage';
+
+export type { PersonaLogger, SessionStorage };
+
+export type ReadonlyJSONObject = {
+  readonly [key: string]: string | number | boolean | null | ReadonlyJSONObject | ReadonlyArray<ReadonlyJSONObject>;
+};
+
+export type FunctionCall = {
+  id?: string;
+  name: string;
+  args: ReadonlyJSONObject;
+};
+
+export type FunctionResponse = {
+  name: string;
+  result: unknown;
+  function_call_id: string;
+};
+
+export type PersonaFile = {
+  name: string;
+  url?: string;
+  base64?: string;
+  contentType: string;
+};
+
+export type PersonaSession = {
+  id: string;
+  code: string;
+  projectId: string;
+  agentId: string;
+  currentAgentId: string;
+  userId: string;
+  status: 'active' | 'finished';
+  type: 'realtime' | 'async';
+  createdAt: string;
+  finishedAt: string | null;
+};
+
+export type PersonaProjectSubscription = {
+  id: string;
+  projectId?: string | null;
+  owner?: string | null;
+  planType: 'free' | 'baby' | 'junior' | 'pro' | 'mentor';
+  status: 'creating' | 'active' | 'inactive' | 'cancelled';
+  startDate?: string | null;
+  planCredits: number;
+  extraCredits: number;
+  keepCreditsOnRenew: boolean;
+  endDate?: string | null;
+  createdAt?: string | null;
+  updatedAt?: string | null;
+  stripeCustomerId?: string | null;
+  stripeSubscriptionId?: string | null;
+};
+
+export type PersonaAgentContext = {
+  data: Record<string, unknown>;
+  files?: PersonaFile[];
+  session?: PersonaSession;
+};
+
+export type PersonaTransaction = {
+  id: string;
+  projectId: string;
+  sessionId: string;
+  status: 'pending' | 'completed' | 'failed';
+  error: string | null;
+  functionCall: FunctionCall | null;
+  context: PersonaAgentContext;
+};
+
+export type PersonaReasoning = {
+  thought: string;
+  imageUrl?: string;
+};
+
+export type PersonaImage = {
+  content: string;
+  contentType: string;
+};
+
+export type PersonaSourceChunk = {
+  start: number;
+  end: number;
+};
+
+export type PersonaSource = {
+  type: 'web' | 'document';
+  url?: string;
+  documentId?: string;
+  pageId?: string;
+  pageNumber?: number;
+  chunks?: PersonaSourceChunk[];
+  mostRelevant?: boolean;
+};
+
+export type PersonaCommand = {
+  command: 'get_mcp_assets' | 'set_initial_context' | 'set_local_tools';
+  arguments: Record<string, unknown>;
+};
+
+export type PersonaRequest = PersonaMessage | Array<PersonaMessage> | string;
+
+export type PersonaPacketPayload = PersonaRequest | PersonaCommand | PersonaReasoning | PersonaTransaction;
+
+export type PersonaPacket = {
+  type: 'request' | 'message' | 'command' | 'reasoning' | 'mcp_assets' | 'transaction';
+  payload?: PersonaPacketPayload;
+};
+
+export type PersonaMessage = {
+  id?: string | null;
+  protocol?: string;
+  thought?: string;
+  text: string;
+  image?: PersonaImage;
+  type: 'reasoning' | 'text' | 'transaction' | 'command';
+  role: 'user' | 'assistant' | 'function';
+  file?: PersonaFile;
+  sources?: PersonaSource[];
+  sessionId?: string;
+  finishReason?: 'stop' | 'function_call';
+  functionCalls?: FunctionCall[];
+  functionResponse?: FunctionResponse;
+  status?: { type: 'running' | 'complete' | 'incomplete' };
+  // ThreadMessageLike compatible fields
+  createdAt?: Date;
+  metadata?: {
+    custom?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+};
+
+export type ModelResponse = {
+  messages: PersonaMessage[];
+};
+
+export type PersonaResponse = {
+  sessionId: string;
+  response: ModelResponse;
+};
+
+export type PersonaBaseConfig = {
+  logger?: PersonaLogger;
+};
+
+export type PersonaWebRTCConfig = PersonaBaseConfig & {
+  webrtcUrl: string;
+  iceServers?: RTCIceServer[];
+  onDataMessage?: (msg: MessageEvent) => void;
+};
+
+export type Session = string | null | undefined;
+
+export type TransformMessages = (messages: PersonaMessage[]) => PersonaMessage[];
+
+export type ThreadData = {
+  threadId: string;
+  title?: string;
+  status: 'regular' | 'archived';
+};
+
+export type MessageListenerCallback = (message: PersonaPacket) => void;
+export type StatusChangeCallback = (status: ProtocolStatus) => void;
+
+export type ProtocolStatus = 'disconnected' | 'connecting' | 'connected';
+
+export type PersonaProtocolBaseConfig = {
+  logger?: PersonaLogger;
+  apiKey: string;
+  agentId: string;
+  userId?: string;
+};
+
+export interface PersonaProtocol {
+  status: ProtocolStatus;
+  autostart: boolean;
+
+  getName: () => string;
+  getPriority: () => number;
+  connect: (session?: Session) => Promise<Session>;
+  disconnect: () => Promise<void>;
+
+  onTransaction: (transaction: PersonaTransaction) => void;
+
+  setSession: (session: Session) => Promise<void>;
+
+  sendPacket: (packet: PersonaPacket) => Promise<void>;
+  setAgentContext: (context: PersonaAgentContext) => Promise<void>;
+  clearListeners: () => void;
+  addStatusChangeListener: (callback: StatusChangeCallback) => void;
+  addPacketListener: (callback: MessageListenerCallback) => void;
+}
+
+export type PersonaConfig = PersonaBaseConfig &
+  PersonaProtocolBaseConfig & {
+    /**
+     * In 'dev' mode the endpoint is set to localhost:8000,
+     * use it only for development purposes.
+     */
+    dev?: boolean;
+    /**
+     * The base URL of the API.
+     * @default 'persona.applica.guru/api'
+     */
+    baseUrl?: string;
+    session?: Session;
+    children: ReactNode;
+    context?: PersonaAgentContext;
+    protocols:
+      | PersonaProtocol[]
+      | {
+          rest?: PersonaProtocolBaseConfig | boolean;
+          webrtc?: PersonaProtocolBaseConfig | boolean;
+          websocket?: PersonaProtocolBaseConfig | boolean;
+        };
+
+    /**
+     * Tools can be provided as an object (legacy) or as an array of { schema, implementation } (recommended)
+     */
+    tools?: PersonaTools | ToolInstance[];
+
+    /**
+     * Optional message transform function that processes messages before they are displayed
+     */
+    transformMessages?: TransformMessages;
+
+    /**
+     * Enable thread management support
+     */
+    threads?: boolean;
+
+    /**
+     * Session storage implementation
+     * If not provided, defaults to PersonaSessionStorage
+     */
+    sessionStorage?: SessionStorage;
+
+    /**
+     * Initial thread list (if thread management is enabled)
+     */
+    initialThreads?: ThreadData[];
+
+    /**
+     * Callback when a new thread is created
+     */
+    onThreadCreate?: (threadId: string) => void;
+
+    /**
+     * Callback when switching to a thread
+     */
+    onThreadSwitch?: (threadId: string) => void;
+
+    /**
+     * Callback when a thread is renamed
+     */
+    onThreadRename?: (threadId: string, newTitle: string) => void;
+
+    /**
+     * Callback when a thread is archived
+     */
+    onThreadArchive?: (threadId: string) => void;
+
+    /**
+     * Callback when a thread is unarchived
+     */
+    onThreadUnarchive?: (threadId: string) => void;
+
+    /**
+     * Callback when a thread is deleted
+     */
+    onThreadDelete?: (threadId: string) => void;
+
+    /**
+     * Enable file attachments (images, PDFs, text files) in the composer
+     */
+    enableAttachments?: boolean;
+  };

package/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "baseUrl": ".",
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "noEmit": false,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "outDir": "dist",
+    "paths": {
+      "@/*": ["playground/src/*"],
+      "@applica-software-guru/persona-chat-sdk": ["src/index.ts"]
+    },
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ESNext",
+    "typeRoots": ["node_modules/@types", "src/assets.d.ts", "src/index.d.ts", "src/types.d.ts"],
+    "useDefineForClassFields": true
+  },
+  "include": ["src", "playground/src"],
+  "references": [
+    {
+      "path": "./jsconfig.node.json"
+    }
+  ]
+}

package/tsconfig.node.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "composite": true,
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES6"
+  },
+  "include": ["vite.config.ts", "package.json", "playground/src", "src/**/*"]
+}

package/vite.config.ts

@@ -0,0 +1,74 @@
+import react from '@vitejs/plugin-react';
+import * as packageJson from './package.json';
+import { resolve } from 'path';
+import { ConfigEnv, defineConfig, UserConfig } from 'vite';
+import { default as dts } from 'vite-plugin-dts';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig((configEnv: ConfigEnv) => {
+  const { mode } = configEnv;
+  const isDevelopment = mode === 'development';
+  const config: UserConfig = {
+    build: {
+      sourcemap: true,
+      lib: {
+        entry: resolve('src', 'index.ts'),
+        name: 'personaChatSDK',
+        formats: ['es', 'umd', 'cjs', 'iife'],
+        fileName: (format: string) => `bundle.${format}.js`,
+      },
+      rollupOptions: {
+        external: [
+          ...Object.keys(packageJson.peerDependencies),
+          ...Object.keys(packageJson.dependencies || {}),
+          /^react\//,
+          /^react-dom\//,
+          /^@radix-ui\//,
+        ],
+        input: resolve(__dirname, 'src', 'index.ts'),
+        output: {
+          globals: {
+            'react-dom': 'ReactDOM',
+            react: 'React',
+            'react/jsx-runtime': 'React',
+            'react/jsx-dev-runtime': 'React',
+            '@assistant-ui/react': 'AssistantUI',
+            '@radix-ui/react-dialog': 'RadixDialog',
+            '@radix-ui/react-slot': 'RadixSlot',
+            'rehype-raw': 'rehypeRaw',
+            zustand: 'zustand',
+          },
+        },
+      },
+    },
+    resolve: {
+      dedupe: Object.keys(packageJson.peerDependencies || {}),
+      alias: {
+        '@applica-software-guru/persona-chat-sdk': resolve(__dirname, 'src'),
+        '@': resolve(__dirname, 'playground/src'),
+        '@/*': resolve(__dirname, 'playground/src/*'),
+        '*': resolve(__dirname, 'src/*'),
+      },
+    },
+    plugins: [
+      dts({
+        include: ['./src/**/*.{js,jsx,ts,tsx}'],
+      }),
+      react(),
+    ],
+    define: {
+      'process.env': {
+        NODE_ENV: 'production',
+      },
+    },
+    optimizeDeps: {
+      include: Object.keys(packageJson.peerDependencies || {}),
+    },
+  };
+  if (isDevelopment) {
+    config.plugins = [react(), tailwindcss()];
+    config.root = resolve(__dirname, 'playground');
+  }
+
+  return config;
+});