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

``bash
npm install getfly-crm-sdk


or

yarn add getfly-crm-sdk

or

pnpm add getfly-crm-sdk
`

🚀 Quick Start

`typescript
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

$3

#### Accounts (client.v61.accounts)
- List, create, update, delete accounts
- Advanced filtering by type, status, date range
- Search by name, email, phone
- Custom fields support

`typescript
// 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

`typescript
// 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

`typescript
// 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

`typescript
// 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

`typescript
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

$3

All list methods support powerful filtering:

`typescript
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,
});
`

$3

Getfly CRM supports dynamic custom fields:

`typescript
// 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',
},
});
`

$3

The SDK provides detailed error information:

`typescript
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);
}
}
`

$3

Test your API connection:

`typescript
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

$3

`bash


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
`

$3

`
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