api-patterns

---

name: SmartLead MCP API Development Patterns description: Development patterns for API clients and MCP tools in the SmartLead server author: LeadMagic Team version: 1.0.0

🏗️ SmartLead API Development Patterns & Best Practices

Developer Guide: Master the patterns and practices used throughout the SmartLead MCP Server. This guide will help you write consistent, maintainable code that follows our established conventions.

🎯 Quick Reference

🔥 Most Important Patterns

1. Base Client Extension → All API modules extend BaseSmartLeadClient
2. MCP Tool Registration → Use the standard registration pattern
3. Zod Schema Validation → All inputs validated with Zod
4. Error Handling → Use SmartLeadError for API errors
5. Type Safety → Avoid any, use proper TypeScript types

🏗️ SmartLead API Client Architecture

🛠️ Base Client Pattern

File: src/client/base.ts

The foundation of all API interactions:

export abstract class BaseSmartLeadClient {
  protected config: SmartLeadConfig;
  
  constructor(config: SmartLeadConfig) {
    this.config = config;
  }
  
  // 🔄 Automatic retry with exponential backoff
  protected async withRetry<T>(operation: () => Promise<T>): Promise<T> {
    // Handles transient failures automatically
  }
  
  // 🌐 HTTP methods with proper typing
  protected async get<T>(url: string): Promise<T> { }
  protected async post<T>(url: string, data: unknown): Promise<T> { }
  protected async put<T>(url: string, data: unknown): Promise<T> { }
  protected async delete<T>(url: string): Promise<T> { }
}

Key Features:

• ✅ HTTP request handling with Axios
• ✅ Automatic retry logic with exponential backoff
• ✅ Rate limiting and request queuing
• ✅ Error handling with SmartLeadError class
• ✅ Request/response logging for debugging

🔌 Module Structure Pattern

Example: src/modules/campaigns/client.ts