keap-client

Note: This library is currently under active development.

A modern TypeScript client for the Keap/Infusionsoft REST API. This library provides a simple, type-safe interface to interact with Keap's API, making it easier to integrate Keap functionality into your applications.

Features

• 🚀 TypeScript First - Full type safety and IntelliSense support
• 🔄 Auto-retry - Configurable retry logic for failed requests
• ⏱️ Timeout Control - Customizable request timeouts
• 📦 Modular Design - Clean, organized API surface
• 🔒 Secure - Built-in API key authentication
• 📖 Well Documented - Comprehensive JSDoc comments

Installation

npm install keap-client

yarn add keap-client

pnpm add keap-client

Quick Start

import { KeapClient } from 'keap-client';

// Initialize the client
const keap = new KeapClient({
  apiKey: 'your-api-key-here', // Required: Get this from your Keap app
  requestTimeout: 5000,        // Optional: Request timeout in milliseconds (default: 10000)
  retries: 3                   // Optional: Number of retry attempts (default: 0)
});

// Fetch a contact
const contact = await keap.Contact.getContact(123);
console.log(contact.email);

// Update contact information
await contact.update({ 
  email_opted_in: true,
  given_name: 'John',
  family_name: 'Doe' 
});

// Apply tags to contact
await contact.applyTags(['customer', 'newsletter-subscriber']);

API Reference

Client Configuration

interface KeapClientOptions {
  apiKey: string;          // Your Keap API key (required)
  requestTimeout?: number; // Request timeout in milliseconds (optional)
  retries?: number;        // Number of retry attempts (optional)
}

Available Models

✅ Implemented

• Account Info - Retrieve account information
• Contact - Manage contacts and their data
• E-Commerce - Handle e-commerce related operations
• Email - Manage email communications
• File - File upload and management
• Opportunity - Sales opportunity tracking
• Product - Product catalog management
• Tags - Contact tagging system
• Users - User management

🚧 Coming Soon

• Affiliate
• Appointment
• Campaign
• Company
• Email Address
• Locale
• Merchant
• Note
• REST Hooks
• Setting
• Task
• User Info

Usage Examples

Working with Contacts

// Get a specific contact
const contact = await keap.Contact.getContact(123);

// Create a new contact
const newContact = await keap.Contact.createContact({
  given_name: 'Jane',
  family_name: 'Smith',
  email_addresses: [{
    email: '[email protected]',
    field: 'EMAIL1'
  }]
});

// List contacts with pagination
const contacts = await keap.Contact.listContacts({
  limit: 50,
  offset: 0
});

// Search contacts
const searchResults = await keap.Contact.listContacts({
  email: '[email protected]'
});

Working with Products

// Get all products
const products = await keap.Product.listProducts();

// Get a specific product
const product = await keap.Product.getProduct(456);

// Create a new product
const newProduct = await keap.Product.createProduct({
  product_name: 'My Product',
  product_price: 99.99,
  product_short_desc: 'A great product'
});

Working with Tags

// List all tags
const tags = await keap.Tags.listTags();

// Create a new tag
const tag = await keap.Tags.createTag({
  name: 'VIP Customer',
  description: 'High-value customers'
});

// Apply tags to a contact
await keap.Contact.getContact(123).then(contact => 
  contact.applyTags(['vip-customer', 'newsletter'])
);

Error Handling

The client includes built-in error handling and retry logic:

try {
  const contact = await keap.Contact.getContact(123);
} catch (error) {
  console.error('Failed to fetch contact:', error.message);
  // Handle the error appropriately
}

Authentication

You'll need a Keap API key to use this library. You can obtain one by:

1. Logging into your Keap account
2. Going to Admin → Settings → Application Settings
3. Click on "API" in the left sidebar
4. Generate a new API key

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Keap API Documentation
• 🐛 Report Issues
• 💬 Discussions

Changelog

See CHANGELOG.md for a detailed list of changes and versions.

Developed by Marcos Reuquen Diaz