paltext-sdk

PalText SDK

A JavaScript/TypeScript SDK for integrating with the PalText Agent API. This SDK allows businesses to easily add AI-powered chat functionality to their applications, with support for user authentication and custom business actions.

Installation

npm install paltext-sdk

Or if you're using the SDK directly from the repository:

npm install file:../path/to/sdk-core

Features

• AI-powered chat functionality
• User authentication and session management
• Business-specific actions execution
• User profile management
• Human-readable responses
• Authentication requirement handling
• Typed responses for TypeScript projects

Usage

Basic Usage

import PalTextSDK from 'paltext-sdk';

// Initialize the SDK with your API key
const sdk = new PalTextSDK('your-api-key');

// Initialize a session
const sessionId = await sdk.initSession('user123');

// Send a message
const response = await sdk.sendMessage('Hello, how can I help you?');

// Parse the response with human-readable format
const parsedResponse = sdk.parseAgentResponse(response.message);
console.log(parsedResponse.humanReadable);

With User Authentication

import PalTextSDK from 'paltext-sdk';

// Initialize the SDK with your API key
const sdk = new PalTextSDK('your-api-key');

// Initialize a session with authentication
const sessionId = await sdk.initSession('user123', 'auth-token-from-your-system');

// Get user profile
const userProfile = await sdk.getUserProfile();
console.log(`Hello, ${userProfile.name}`);

// Send a message (context is managed by the SDK)
const response = await sdk.sendMessage('Update my shipping address');

// Parse the response
const parsedResponse = sdk.parseAgentResponse(response.message);

// If the response contains an action, execute it
if (parsedResponse.action && parsedResponse.action !== 'none') {
  try {
    const actionResult = await sdk.executeAction(
      parsedResponse.action,
      parsedResponse.parameters
    );
    console.log('Action result:', actionResult);
  } catch (error) {
    // Check if the error is due to authentication requirements
    if (error.message.includes('sign up or log in')) {
      console.log('Authentication required for this action');
    } else {
      console.error('Error executing action:', error);
    }
  }
}

Handling Authentication Requirements

The SDK automatically checks if actions require authentication:

// Parse the response
const parsedResponse = sdk.parseAgentResponse(response.message);

// Check if the user is authenticated
if (!sdk.isAuthenticated()) {
  // If the action requires authentication, the humanReadable response will include a message
  if (parsedResponse.humanReadable.includes('need to sign up or log in')) {
    console.log('Please log in to perform this action');
    // Show login UI or redirect to login page
  }
}

Updating User Profile

// Update user profile (requires authentication)
const updatedProfile = await sdk.updateUserProfile({
  name: 'John Doe',
  preferences: {
    theme: 'dark',
    notifications: true
  }
});

API Reference

Constructor

new PalTextSDK(apiKey: string, options?: { baseUrl?: string })

• apiKey: Your business API key
• options.baseUrl: Optional custom API URL

Methods

initSession

async initSession(userId: string, authToken?: string): Promise<string>

Initializes a user session and returns a session ID.

setAuthToken

setAuthToken(authToken: string): void

Sets the authentication token for the current user.

isAuthenticated

isAuthenticated(): boolean

Returns true if the user has an authentication token.

getBusinessName

getBusinessName(): string

Returns the business name or "this business" if not available.

sendMessage

async sendMessage(message: string, context?: Partial<UserContext>): Promise<ChatResponse>

Sends a message to the chat agent and returns the response.

getUserProfile

async getUserProfile(): Promise<UserProfile>

Gets the user profile information.

getBusinessActions

getBusinessActions(): BusinessAction[]

Gets the list of available business actions.

executeAction

async executeAction(actionId: string, params: Record<string, any>): Promise<any>

Executes a business action with the given parameters. Throws an error if authentication is required but not provided.

updateUserProfile

async updateUserProfile(updates: Partial<UserProfile>): Promise<UserProfile>

Updates the user profile information. Requires authentication.

parseAgentResponse

parseAgentResponse(message: string): { 
  action: string; 
  text: string; 
  parameters?: Record<string, any>; 
  result?: any;
  humanReadable: string;
}

Parses a JSON response from the agent and adds a human-readable version of the response.

Types

UserContext

interface UserContext {
  userId: string;
  userName?: string;
  sessionId: string;
  authToken?: string;
  metadata?: Record<string, any>;
}

UserProfile

interface UserProfile {
  userId: string;
  name?: string;
  email?: string;
  preferences?: Record<string, any>;
  [key: string]: any;
}

BusinessAction

interface BusinessAction {
  id: string;
  name: string;
  description: string;
  endpoint: string;
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
  requiresAuth: boolean;
}

BusinessInfo

interface BusinessInfo {
  id: string;
  name: string;
  description?: string;
  logoUrl?: string;
}

ChatResponse

interface ChatResponse {
  message: string;
  actionResult?: ActionResult;
}

License

MIT