Getfly CRM TypeScript SDK

A powerful, type-safe TypeScript SDK for Getfly CRM API v6.1. This SDK provides a clean, modern interface for interacting with Getfly CRM's REST API.

✨ Features

• 🚀 Full TypeScript Support - 100% type safety with IntelliSense
• 🎯 Strict Mode - Enforced type checking for better reliability
• ✅ Runtime Validation - Zod schemas for request/response validation
• 🔍 Auto-completion - Full IDE support with comprehensive typing
• 🛡️ Error Handling - Detailed error information and proper error types
• 📄 Custom Fields Support - Dynamic custom fields integration
• 🔍 Query Builder - Powerful filtering, sorting, and pagination
• 📦 Modular Design - Organized by API version and modules
• 🧪 Well Tested - Comprehensive unit tests with Jest
• 📖 Complete Documentation - Detailed API documentation and examples

📦 Installation

npm install getfly-crm-sdk
# or
yarn add getfly-crm-sdk
# or
pnpm add getfly-crm-sdk

🚀 Quick Start

import { GetflyClient } from 'getfly-crm-sdk';

// Initialize the client
const client = new GetflyClient({
  subdomain: 'your-company', // your-company.getflycrm.com
  apiKey: 'your-api-key',
  version: '6.1', // optional, defaults to '6.1'
});

// Test connection
const isConnected = await client.testConnection();
console.log('Connected:', isConnected);

// Get all accounts
const accounts = await client.v61.accounts.list({
  fields: ['id', 'account_name', 'email'],
  limit: 20,
});

console.log('Accounts:', accounts);

// Create a new account
const newAccount = await client.v61.accounts.create({
  account_name: 'Acme Corporation',
  account_type: 1, // 1: Customer
  email: '[email protected]',
  phone_office: '+1234567890',
});

console.log('New account:', newAccount);

📚 API Modules

v6.1 API

Accounts (client.v61.accounts)

• List, create, update, delete accounts
• Advanced filtering by type, status, date range
• Search by name, email, phone
• Custom fields support

// Get customers with filtering
const customers = await client.v61.accounts.getByType(1, {
  filtering: {
    'created_at:gte': '2023-01-01',
    'account_status:eq': 1,
  },
  sort: 'account_name',
  direction: 'ASC',
});

// Search accounts by name
const searchResults = await client.v61.accounts.searchByName('Acme');

Products (client.v61.products)

• Complete product management
• Variants and attributes support
• Inventory tracking
• Price range filtering

// Get products by category
const electronics = await client.v61.products.getByCategory('Electronics');

// Get low stock products
const lowStock = await client.v61.products.getLowStock(5);

// Search products by SKU or name
const products = await client.v61.products.search('LAPTOP-001');

Sale Orders (client.v61.saleOrders)

• Order management and tracking
• Payment status management
• Date range filtering
• Customer-specific orders

// Get pending orders
const pendingOrders = await client.v61.saleOrders.getByStatus(1);

// Get orders by customer
const customerOrders = await client.v61.saleOrders.getByAccount(123);

// Get orders in date range
const monthlyOrders = await client.v61.saleOrders.getByDateRange(
  '2023-01-01',
  '2023-01-31'
);

Purchase Orders (client.v61.purchaseOrders)

• Purchase order management
• Approval workflow
• Vendor-specific orders
• Order status tracking

// Get orders pending approval
const pendingApproval = await client.v61.purchaseOrders.getPendingApproval();

// Approve an order
await client.v61.purchaseOrders.approve(456, 789); // order_id, approved_by

// Reject an order with reason
await client.v61.purchaseOrders.reject(457, 'Budget exceeded', 789);

🔧 Configuration Options

const client = new GetflyClient({
  // Required
  subdomain: 'your-company',     // Your Getfly CRM subdomain
  apiKey: 'your-api-key',        // Your API key from Getfly CRM

  // Optional
  version: '6.1',                // API version (defaults to '6.1')
  timeout: 30000,                // Request timeout in ms (defaults to 30000)
  headers: {                     // Additional headers
    'User-Agent': 'MyApp/1.0',
  },
  baseURL: 'https://custom.domain.com', // Custom base URL (overrides subdomain)
});

📝 Advanced Usage

Filtering and Pagination

All list methods support powerful filtering:

const accounts = await client.v61.accounts.list({
  // Select specific fields
  fields: ['id', 'account_name', 'email', 'account_type'],

  // Filter with various operations
  filtering: {
    'account_name:contains': 'corp',     // Contains
    'account_type:eq': 1,                // Equals
    'created_at:gte': '2023-01-01',      // Greater than or equal
    'created_at:lte': '2023-12-31',      // Less than or equal
    'annual_revenue:between': [10000, 50000], // Between values
    'tags:in': ['VIP', 'Premium'],       // In array
  },

  // Sorting
  sort: 'created_at',
  direction: 'DESC',

  // Pagination
  limit: 50,
  offset: 0,
});

Custom Fields

Getfly CRM supports dynamic custom fields:

// Get custom fields schema
const customFieldsSchema = await client.v61.accounts.getCustomFields();

// Create account with custom fields
const account = await client.v61.accounts.create({
  account_name: 'Custom Corp',
  account_type: 1,
  custom_fields: {
    'custom_industry': 'Technology',
    'custom_website_visits': 1250,
    'custom_priority': 'High',
  },
});

Error Handling

The SDK provides detailed error information:

import { GetflyApiError, GetflyValidationError } from 'getfly-crm-sdk';

try {
  const account = await client.v61.accounts.create(invalidData);
} catch (error) {
  if (error instanceof GetflyValidationError) {
    console.error('Validation failed:', error.getErrorSummary());
    error.validationErrors.forEach(err => {
      console.error(`${err.field}: ${err.message}`);
    });
  } else if (error instanceof GetflyApiError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.status);
    console.error('Code:', error.code);
  }
}

Connection Testing

Test your API connection:

const isConnected = await client.testConnection();
if (!isConnected) {
  console.error('Failed to connect to Getfly CRM API');
}

// Get detailed API info
const apiInfo = await client.getApiInfo();
console.log('API Info:', apiInfo);
/*
{
  version: '6.1',
  baseURL: 'https://your-company.getflycrm.com',
  connected: true
}
*/

🧪 Development

Setup

# Clone the repository
git clone https://github.com/getfly-crm/typescript-sdk.git
cd typescript-sdk

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build the project
npm run build

# Check types
npm run typecheck

# Lint code
npm run lint

# Format code
npm run format

Project Structure

src/
├── client/                 # Main client class
├── utils/                  # HTTP client and validation utilities
├── versions/
│   └── v6.1/              # API v6.1 implementation
│       ├── modules/       # API modules (accounts, products, etc.)
│       ├── types/         # TypeScript type definitions
│       └── index.ts       # Version entry point
└── index.ts               # Main entry point

tests/                     # Unit tests
examples/                 # Usage examples
docs/                     # Documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

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

🆘 Support

If you have any questions or need help:

• 📧 Email: [email protected]
• 📖 Documentation: Getfly CRM API Docs
• 🐛 Issues: GitHub Issues

🙏 Acknowledgments

• Getfly CRM for providing the API
• Zod team for the excellent validation library
• TypeScript team for the amazing language