@andesphereai/core

Core utilities and API client for AndyChat - embeddable AI chatbot library.

Overview

This package contains shared functionality used by all AndyChat implementations:

• API Client - Functions to communicate with AndyChat backend
• Design Tokens - Colors, typography, spacing constants
• Utilities - Helper functions for sessions, markdown parsing, etc.
• Styles Helper - CSS generation and theming functions

Installation

npm install @andesphereai/core

API Reference

API Functions

fetchChatbotConfig(embedId)

Fetches chatbot configuration from the API.

• embedId (string): The chatbot embed ID
• Returns: Promise - The chatbot configuration with defaults applied

sendMessage(embedId, sessionId, message)

Sends a user message to the API and returns bot response.

• embedId (string): The chatbot embed ID
• sessionId (string): The current session ID
• message (string): The user's message
• Returns: Promise - The bot's response text

submitUserInfo(embedId, sessionId, userInfo)

Submits user information (name and email) to the server.

• embedId (string): The chatbot embed ID
• sessionId (string): The current session ID
• userInfo (object): User information {name, email}
• Returns: Promise - Server response

setApiBaseUrl(url) / getApiBaseUrl()

Set or get the API base URL for backend communication.

Utility Functions

generateSessionId()

Generates a unique session ID using crypto.randomUUID() with fallback.

• Returns: string - A unique session ID

parseMarkdown(text)

Parses markdown text to HTML with support for:

• Bold text (text or text)
• Italic text (text or text)
• Links (text)
• Headings (# ## ### etc.)
• Lists (numbered and bullet)
• Returns: string - Parsed HTML

sanitizeUrl(url)

Sanitizes URLs to prevent XSS attacks, allowing http/https/mailto/tel protocols.

• Returns: string - Sanitized URL or '#' fallback

createGreetingMessage(config)

Creates a greeting message from chatbot configuration.

• config (ChatbotConfig): The chatbot configuration
• Returns: string|null - Formatted greeting message

getEmbedId()

Gets the embed ID from the global window.ANDY_CHATBOT_ID variable.

• Returns: string - The chatbot embed ID

Design Tokens

Comprehensive design system with consistent styling values:

Colors

import { colors } from '@andesphereai/core'
// colors.primary, colors.gray100, colors.userMessage, etc.

Typography

import { typography } from '@andesphereai/core'
// typography.fontFamily.primary, typography.fontSize.base, etc.

Spacing, Border Radius, Shadows, Z-Index, Animation

import { spacing, borderRadius, shadows, zIndex, animation } from '@andesphereai/core'

Chat-Specific Tokens

import { chat } from '@andesphereai/core'
// chat.bubbleSize, chat.windowWidth, chat.messageMaxWidth, etc.

Style Helpers

generateCssVariables()

Generates CSS variables string from design tokens for use in shadow DOM.

• Returns: string - CSS variables block with :host selector

getBaseCss()

Generates base CSS rules using design token variables.

• Returns: string - Base CSS for chatbot components

applyThemeColor(brandColor)

Applies custom brand color to CSS variables.

• brandColor (string): Hex color code
• Returns: string - CSS with theme-specific variables

applyOrientation(orientation)

Generates orientation-specific CSS for left/right positioning.

• orientation (string): 'left' or 'right'
• Returns: string - CSS for positioning

Configuration Objects

DEFAULT_CHATBOT_CONFIG

Default configuration object with all chatbot settings and sensible defaults.

CONFIG

Application configuration constants (form delays, session persistence, etc.).

Usage Example

import { fetchChatbotConfig, sendMessage, generateSessionId, colors, generateCssVariables } from '@andesphereai/core'

// Initialize
const embedId = 'your-embed-id'
const sessionId = generateSessionId()

// Fetch configuration
const config = await fetchChatbotConfig(embedId)

// Send a message
const response = await sendMessage(embedId, sessionId, 'Hello!')

// Use design tokens
const primaryColor = colors.primary
const cssVars = generateCssVariables()

TypeScript Support

The package includes JSDoc type definitions for all functions and configuration objects. For full TypeScript support, the types are documented in the source code.

Architecture

This core package provides the "cookbook and pantry" for AndyChat implementations:

• API Logic: All backend communication
• Design Tokens: Consistent styling system
• Utilities: Common functions for parsing, validation, etc.
• Configuration: Centralized settings management

Both @andesphereai/vanilla and @andesphereai/react use this core package for all business logic while implementing their own UI layers.

License

MIT