AI Sales Agent SDK

Framework-agnostic conversational commerce engine for building AI-powered sales chatbots

AI Sales Agent SDK is a production-ready JavaScript SDK that enables developers to integrate intelligent conversational commerce capabilities into any e-commerce platform, POS system, or custom application.

✨ Features

• 🛍️ Conversational Commerce Engine - Browse, cart, checkout via natural language
• 🔌 Adapter Pattern - Plug into any backend (WooCommerce, Shopify, Odoo, custom APIs)
• 🤖 LLM Provider Interface - Ollama provider included; OpenAI/Claude adapters are planned; custom models supported
• 🎯 Intent Detection - Automatically understands user intent and extracts entities
• 💾 Flexible Session Storage - In-memory (dev) or Redis (production)
• 🛡️ Production-Ready - Rate limiting, error handling, structured logging built-in
• 🚀 Framework-Agnostic - No Express/Fastify/Koa dependency
• 📦 Zero Config - Works out of the box with SQLite reference implementation

📦 Installation

Option 1: Clone from GitHub

git clone https://github.com/mmad2021/ai-sales-agent-sdk.git
cd ai-sales-agent-sdk
npm install

Option 2: Add to your project

npm install ai-sales-agent-sdk

🚀 Quick Start

Run the Example

npm run example:basic

This runs a complete demo showing:

• Product browsing
• Adding items to cart
• Viewing cart
• Checkout flow

Basic Usage

import {
  AISalesAgent,
  OllamaProvider,
  MemorySessionStore,
  SQLiteProductAdapter,
  SQLiteOrderAdapter,
  SQLiteCustomerAdapter,
  SQLitePaymentAdapter,
  SQLiteClient
} from './src/index.js';

// 1. Setup database (SQLite example)
const dbClient = new SQLiteClient({ dbPath: ':memory:' });
await dbClient.getDB();

// 2. Configure adapters
const adapters = {
  products: new SQLiteProductAdapter({ client: dbClient }),
  orders: new SQLiteOrderAdapter({ client: dbClient }),
  customers: new SQLiteCustomerAdapter({ client: dbClient }),
  payments: new SQLitePaymentAdapter({ client: dbClient })
};

// 3. Choose LLM provider
const llm = new OllamaProvider({
  baseUrl: 'http://localhost:11434',
  model: 'qwen2.5-coder:14b'
});

// 4. Setup session storage
const sessionStore = new MemorySessionStore();

// 5. Create agent
const agent = new AISalesAgent({
  llm,
  sessionStore,
  adapters
});

// 6. Process messages
const response = await agent.chat('user123', 'Show me black t-shirts under $30');

console.log(response.text);  // Natural language response
console.log(response.data);  // Structured data (products, cart, etc.)

🏗️ Architecture

Core Components

| Component | Purpose | |-----------|---------| | Agent | Main orchestrator - coordinates all operations | | IntentDetector | Analyzes messages, extracts intent + entities | | ResponseGenerator | Creates natural language responses | | ActionExecutor | Executes business actions (add_to_cart, checkout) | | ContextManager | Manages conversation context and state |

Adapters

Implement these interfaces to connect your backend:

// Product operations
class ProductAdapter {
  async searchProducts(query, filters) { /* ... */ }
  async getProduct(productId) { /* ... */ }
  async checkAvailability(productId, quantity) { /* ... */ }
}

// Order management
class OrderAdapter {
  async createOrder(orderData) { /* ... */ }
  async getOrder(orderId) { /* ... */ }
  async getCustomerOrders(customerId) { /* ... */ }
}

// Customer data
class CustomerAdapter {
  async getCustomer(customerId) { /* ... */ }
  async getOrCreateCustomer(identifier) { /* ... */ }
}

// Payment processing
class PaymentAdapter {
  async createPayment(paymentData) { /* ... */ }
  async verifyPayment(paymentId) { /* ... */ }
  async processReceipt(orderId, receiptUrl, verification) { /* ... */ }
}

Reference implementations included:

• ✅ SQLite adapters (use as-is or as reference)
• 🔜 WooCommerce adapters (coming soon)
• 🔜 Shopify adapters (coming soon)

LLM Providers

Current support:

// Local models (Ollama)
const llm = new OllamaProvider({ 
  baseUrl: 'http://localhost:11434',
  model: 'qwen2.5-coder:14b' 
});

// OpenAI (planned - currently throws not implemented)
const llm = new OpenAIProvider({ 
  apiKey: 'sk-...',
  model: 'gpt-4' 
});

// Claude (planned - currently throws not implemented)
const llm = new ClaudeProvider({ 
  apiKey: 'sk-ant-...',
  model: 'claude-3-sonnet' 
});

// Or implement your own
class CustomLLMProvider extends LLMProvider {
  async complete(prompt) { /* ... */ }
  async completeJSON(prompt) { /* ... */ }
}

📚 Detailed Usage

1. Using with WooCommerce (custom adapter)

import axios from 'axios';
import { ProductAdapter } from './src/adapters/base/index.js';

class WooCommerceProductAdapter extends ProductAdapter {
  constructor({ siteUrl, consumerKey, consumerSecret }) {
    super();
    this.api = axios.create({
      baseURL: `${siteUrl}/wp-json/wc/v3`,
      auth: { username: consumerKey, password: consumerSecret }
    });
  }

  async searchProducts(query, filters = {}) {
    const params = {};
    if (filters.category) params.category = filters.category;
    if (filters.maxPrice) params.max_price = filters.maxPrice;
    if (query) params.search = query;

    const response = await this.api.get('/products', { params });
    return response.data.map(p => ({
      id: p.id,
      name: p.name,
      description: p.description,
      price: parseFloat(p.price),
      stock: p.stock_quantity,
      category: p.categories[0]?.name,
      image: p.images[0]?.src
    }));
  }

  async getProduct(id) {
    const response = await this.api.get(`/products/${id}`);
    const p = response.data;
    return {
      id: p.id,
      name: p.name,
      price: parseFloat(p.price),
      stock: p.stock_quantity
    };
  }

  async checkAvailability(productId, quantity) {
    const product = await this.getProduct(productId);
    const stock = product.stock || 0;
    return { available: stock >= quantity, stock };
  }
}

// Use it
const products = new WooCommerceProductAdapter({
  siteUrl: 'https://your-store.com',
  consumerKey: 'ck_...',
  consumerSecret: 'cs_...'
});

const agent = new AISalesAgent({ llm, adapters: { products }, /* ... */ });

2. Using with Redis Sessions (production)

import { RedisSessionStore } from './src/session/index.js';

const sessionStore = new RedisSessionStore({
  url: 'redis://localhost:6379',
  prefix: 'sales-agent:session:',
  defaultTTL: 3600
});

const agent = new AISalesAgent({
  sessionStore,
  // ... other config
});

3. Using Middleware

import { RateLimiter, Logger, ErrorHandler } from './src/middleware/index.js';

// Rate limiting (10 requests per minute per user)
const rateLimiter = new RateLimiter({ 
  maxRequests: 10, 
  windowMs: 60000 
});

// Structured logging
const logger = new Logger({ level: 'info' });

// Error recovery
const errorHandler = new ErrorHandler({ 
  onError: async (error, ctx) => {
    console.error('Agent error:', error.message, { sessionId: ctx.sessionId });
  }
});

// Apply to agent
const agent = new AISalesAgent({
  middleware: [rateLimiter, logger, errorHandler],
  // ... other config
});

4. Handling Responses

const response = await agent.chat('user123', 'Add black t-shirt to cart');

console.log(response);
// {
//   text: "I've added the black t-shirt to your cart.",
//   intent: 'add_to_cart',
//   confidence: 0.93,
//   entities: { product_type: 't-shirt', color: 'black' },
//   actions: {
//     addedToCart: true,
//     removedFromCart: false,
//     proceedToCheckout: false
//   }
//   data: { ... },
//   session: { cart: { items: [...] }, customer: null, context: {} }
// }

🎯 Use Cases

E-commerce Chatbots

• WhatsApp Shopping for online stores
• Telegram product catalog bot
• Web chat widget for product discovery

Point of Sale (POS)

• In-store kiosk with voice/chat interface
• Mobile sales assistant app
• Inventory lookup tool

Custom Integrations

• Internal sales tools
• B2B order management
• Multi-channel commerce (web + messaging apps)

Rapid Prototyping

• Build conversational commerce MVP in hours
• Test AI sales flows before full integration
• Demo to stakeholders

📁 Project Structure

ai-sales-agent-sdk/
├── src/
│   ├── core/                    # Core engine
│   │   ├── Agent.js             # Main orchestrator
│   │   ├── IntentDetector.js    # Intent classification
│   │   ├── ResponseGenerator.js # Natural language generation
│   │   ├── ActionExecutor.js    # Business logic executor
│   │   └── ContextManager.js    # Conversation context
│   │
│   ├── adapters/
│   │   ├── base/                # Base interfaces
│   │   │   ├── ProductAdapter.js
│   │   │   ├── OrderAdapter.js
│   │   │   ├── CustomerAdapter.js
│   │   │   └── PaymentAdapter.js
│   │   └── implementations/     # SQLite reference
│   │       ├── SQLiteProductAdapter.js
│   │       ├── SQLiteOrderAdapter.js
│   │       ├── SQLiteCustomerAdapter.js
│   │       ├── SQLitePaymentAdapter.js
│   │       └── SQLiteClient.js
│   │
│   ├── llm/
│   │   ├── base/
│   │   │   └── LLMProvider.js   # Base LLM interface
│   │   └── providers/
│   │       ├── OllamaProvider.js
│   │       ├── OpenAIProvider.js
│   │       └── ClaudeProvider.js
│   │
│   ├── session/
│   │   ├── SessionStore.js      # Base interface
│   │   ├── MemorySessionStore.js
│   │   └── RedisSessionStore.js
│   │
│   └── middleware/
│       ├── RateLimiter.js
│       ├── Logger.js
│       └── ErrorHandler.js
│
├── examples/
│   └── 01-basic-usage/
│       └── index.js             # Working demo
│
├── package.json
├── LICENSE
└── README.md

🔧 Configuration

Agent Options

const agent = new AISalesAgent({
  // Required
  llm: new OllamaProvider({ /* ... */ }),
  sessionStore: new MemorySessionStore(),
  adapters: {
    products: new SQLiteProductAdapter(/* ... */),
    orders: new SQLiteOrderAdapter(/* ... */),
    customers: new SQLiteCustomerAdapter(/* ... */),
    payments: new SQLitePaymentAdapter(/* ... */)
  },

  // Optional
  middleware: [rateLimiter, logger, errorHandler],
  
  // Configuration options
  config: {
    conversation: {
      maxHistoryLength: 20,
      sessionTTL: 3600,
      greetingMessage: 'Welcome!'
    },
    llm: {
      temperature: 0.7,
      maxTokens: 500,
      systemPrompt: 'You are a helpful sales assistant.'
    },
    business: {
      name: 'Store',
      description: 'Online store',
      currency: 'USD'
    },

    // Payment receipt verification (vision LLM)
    payments: {
      autoApproveThreshold: 0.85,
      autoRejectThreshold: 0.35,
      visionPrompt: 'Assess whether this image is a valid payment receipt for the provided order details.'
    }
  }
});

5. Image Upload Receipt Verification (Vision LLM)

const response = await agent.chat(
  'session-user-001',
  'I uploaded my payment receipt',
  {
    orderId: 1,
    receiptUrl: '/absolute/path/to/receipt.jpg'
    // you can also pass imageUrl instead of receiptUrl
  }
);

console.log(response.data);
// {
//   orderId: 1,
//   receiptUrl: '/absolute/path/to/receipt.jpg',
//   decision: 'approved' | 'rejected' | 'pending',
//   confidence: 0.91,
//   paymentStatus: 'paid' | 'verification_rejected' | 'pending_verification',
//   verified: true | false,
//   reason: '...'
// }

Intent submit_payment_receipt is now supported and the SDK runs:

1. Image analysis with llm.analyzeImage(...)
2. Confidence scoring (0..1)
3. Automatic decision via thresholds (approved / rejected / pending)
4. Payment status update in orders + audit record in payment_verifications

🧪 Testing

# Current baseline checks
npm run check
npm test
npm run example:basic

# Optional: watch mode for local test development
npm run test:watch

🛠️ Development

Running Examples Locally

# Basic usage example
npm run example:basic

Building Custom Adapters

1. Extend the base adapter class
2. Implement required methods
3. Handle errors appropriately
4. Return data in expected format

See src/adapters/implementations/ for reference implementations.

📋 Requirements

• Node.js: >= 18.0.0
• Dependencies:
  • redis (^4.6.12) - only if using RedisSessionStore
  • sql.js (^1.14.0) - only if using SQLite adapters

🗺️ Roadmap

Phase 1: Core SDK ✅ (Complete)

• [x] Core conversational engine
• [x] Adapter pattern
• [x] LLM provider interface + Ollama implementation
• [x] Session management
• [x] Middleware stack
• [x] SQLite reference implementations
• [x] Basic example

Phase 2: Enhancements (In Progress)

• [ ] Vision support (image product search)
• [ ] Sentiment analysis
• [ ] Multi-language support
• [ ] Conversation summarization

Phase 3: Real-World Integrations

• [ ] WooCommerce adapters
• [ ] Shopify adapters
• [ ] Odoo ERP adapters
• [ ] WhatsApp Business API connector
• [ ] Telegram Bot API connector

Phase 4: Testing & Documentation

• [ ] Unit tests (Jest)
• [ ] Integration tests
• [ ] API documentation (JSDoc)
• [ ] Tutorial videos

Phase 5: Distribution

• [ ] Publish to npm
• [ ] CDN version
• [ ] Docker images

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🙏 Credits

Architecture: Adapter pattern, Dependency Injection, Interface Segregation
Implementation: Automated extraction with GPT-5.3 Codex
Original Project: ai-sales-agent

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

🌟 Star History

If you find this project useful, please consider giving it a star! ⭐

Built with ❤️ for the conversational commerce community