Package Exports

@warriorteam/getfly-crm-sdk
@warriorteam/getfly-crm-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@warriorteam/getfly-crm-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: 'contact@acme.com',
  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: support@getflycrm.com
📖 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

@warriorteam/getfly-crm-sdk