make typescript sdk extended v2.1.6

a complete typescript sdk for interacting with the make.com api. this enhanced version addresses all critical issues identified in community feedback and provides a production-ready development experience with comprehensive api support, validation, testing utilities, and best practices enforcement.

AI-Powered Make.com App Development

use case: build make.com apps with ai agents

this sdk is designed for ai-assisted make.com app development. use claude code, github copilot, cursor, or other ai agents to automatically build complete make.com integrations from api documentation.

step 1: install ai agent

install your preferred ai coding assistant:

• claude code (recommended): official anthropic cli
• github copilot: integrated with vscode/jetbrains
• cursor: ai-first code editor
• other agents: any ai assistant that can read documentation and write code

step 2: use the ai development prompt

provide this prompt to your ai agent:

you are a make.com app developer with access to comprehensive knowledge about make.com apps in the docs/ folders of this npm package: https://www.npmjs.com/package/@aixyte/makehq-sdk-extended

your task is to use this package to build a complete make.com app.

api documentation: [paste your api docs here - can be yaml file, swagger url, copy-paste from website, or file path]

make.com credentials:
- api key: [your api key]
- zone: [we/eu1/etc]  
- org id: [your org id]

rules:
1. install and read the docs/ folder from the npm package first
2. always plan out details and steps before coding
3. read the knowledge in docs/ before starting development
4. plan precisely how to develop the make.com app
5. create components in order: app base → connections → rpcs → modules
6. use the working sdk methods (createWithoutVersion, updateSectionWithoutVersion)
7. create a docs/feedback.md file with logs, issues, and learnings
8. follow all best practices from the documentation

start by analyzing the api documentation and creating a detailed development plan.

step 3: automated app development

the ai agent will:

1. analyze api documentation - understand endpoints, authentication, parameters
2. read sdk documentation - access 22 comprehensive guides in docs/ folder
3. create development plan - detailed steps for app structure and implementation
4. build app components:
   • app metadata and base configuration
   • authentication connections (api key, oauth, etc)
   • rpc modules for dynamic data (dropdowns, validation)
   • action/trigger/search modules for core functionality
5. handle known issues - use working connection methods, avoid common pitfalls
6. test and deploy - upload to make.com platform with proper error handling
7. document learnings - create feedback.md with issues and solutions

what gets built automatically

• complete app structure - proper folder organization and file naming
• authentication system - secure api key or oauth implementation
• dynamic data sources - rpcs for dropdowns and real-time data
• core modules - actions, triggers, searches based on api capabilities
• error handling - comprehensive error responses and validation
• production-ready code - follows make.com best practices and validation rules
• documentation - detailed feedback and learnings for future development

example output

my-api-app/
├── metadata.json              # app configuration
├── base.imljson              # global settings
├── connections/              # authentication
│   └── api-key/
│       ├── metadata.json
│       ├── parameters.imljson
│       └── api.imljson
├── rpcs/                     # dynamic data
│   ├── get-projects/
│   └── get-statuses/
├── modules/                  # core functionality
│   ├── create-task/
│   ├── update-task/
│   ├── search-tasks/
│   └── new-task-trigger/
└── docs/
    └── feedback.md           # development log and learnings

benefits of ai-assisted development

• speed: complete apps built in minutes instead of hours
• accuracy: follows make.com best practices automatically
• consistency: standardized structure and error handling
• learning: detailed documentation of process and issues
• maintenance: easy to modify and extend generated apps

v2.1.9 - comprehensive test coverage added

added complete test suite with 37 tests covering all major sdk apps functionality. includes full coverage of crud operations, metadata management, publishing workflows, and critical bug regression tests. all tests passing with 100% success rate ensuring production-ready reliability.

🚀 What's New in v2.0

Major Architecture Improvements

• ✅ Complete SDK Constructor Class - Proper initialization with MakeHQSDK
• ✅ Authentication & API Layer - Built-in API key management, rate limiting, retry logic
• ✅ Enhanced Error Handling - Comprehensive error types with detailed messages

Complete API Coverage

• ✅ Apps API - create, update, delete, list, test, publish, validate
• ✅ Connections API - create, update, delete, list, test, validate
• ✅ Modules API - create, update, delete, list, test, validate, link
• ✅ Functions API - create, update, delete, test, validate, code management
• ✅ RPCs API - create, update, delete, test, validate
• ✅ Section Management - Complete upload/download for all component types

Production-Ready Features

• ✅ Production Validation System - Prevents example data in production
• ✅ Service Templates - Pre-built configs for OpenAI, Stripe, GitHub
• ✅ Testing Utilities - Built-in testing for connections, modules, functions
• ✅ TypeScript Support - Complete type definitions and strict typing
• ✅ Rate Limiting - Automatic request throttling and retry logic
• ✅ Debug Mode - Comprehensive logging for troubleshooting

Installation

via npm (node.js)

npm install @aixyte/makehq-sdk-extended@^2.1.9
npm install -g @aixyte/makehq-sdk-extended@^2.1.9

Via JSR (Deno)

deno add jsr:@make/sdk-extended

Basic Usage

SDK in Code (New v2.0 API)

import { MakeHQSDK } from '@aixyte/makehq-sdk-extended';

// Initialize the SDK with comprehensive options
const sdk = new MakeHQSDK({
    apiKey: 'your-api-key',
    region: 'eu1', // or 'eu2', 'us1', 'us2'
    debug: true, // Enable debugging
    rateLimit: {
        requests: 100,
        per: 60000 // 100 requests per minute
    },
    retry: {
        attempts: 3,
        delay: 1000,
        exponentialBackoff: true
    }
});

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

// Create a new SDK app
const newApp = await sdk.apps.create({
    name: 'my-awesome-app',
    label: 'My Awesome App',
    description: 'An amazing Make app',
    theme: '#4f8df5',
    language: 'en',
    audience: 'global'
});

// Create connection from template
const openaiConnection = sdk.createConnectionFromTemplate('openai');
const connection = await sdk.connections.create('my-app', 1, openaiConnection);

// Test the connection
const testResult = await sdk.connections.testConnection('my-app', 1, connection.appConnection.name, {
    apiKey: 'your-openai-api-key'
});

// Create a module
const newModule = await sdk.modules.create('my-app', 1, {
    name: 'chat-completion',
    label: 'Create Chat Completion',
    description: 'Generate AI responses using OpenAI',
    typeId: 4, // Action
    moduleInitMode: 'example'
});

// Link module to connection
await sdk.modules.linkToConnection('my-app', 1, 'chat-completion', connection.appConnection.name);

// Test the module
const moduleTest = await sdk.modules.test('my-app', 1, 'chat-completion', {
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: 'Hello!' }]
});

🔧 Production Validation & Templates (NEW!)

The SDK now includes comprehensive validation and service templates to ensure production-ready Make.com apps:

Validation Features

import { 
    Make, 
    validateConnectionConfig, 
    createConnectionFromTemplate,
    SERVICE_TEMPLATES 
} from '@aixyte/makehq-sdk-extended';

const make = new Make('your-api-key', 'eu2.make.com');

// ❌ This will fail validation (catches common mistakes)
const badConfig = {
    type: 'api-key', // Wrong! Should be 'apikey'
    label: 'API Key', // Too generic
    api: { url: 'https://api.example.com/whoami' } // Forbidden example domain
};

const result = make.sdkAppConnections.validateConfig(badConfig);
console.log(result.valid); // false
console.log(result.errors); // Detailed error messages

// ✅ Use service templates for production-ready configs
const openaiConnection = createConnectionFromTemplate('openai');
// Returns: { type: 'apikey', label: 'OpenAI API Key', api: { url: 'https://api.openai.com/v1/models' }, ... }

const validResult = make.sdkAppConnections.validateConfig(openaiConnection);
console.log(validResult.valid); // true

Service Templates

Pre-built configurations for popular services:

• OpenAI: Chat completion, embeddings, models
• Stripe: Customer management, payments, subscriptions
• GitHub: Issues, repositories, pull requests
• Slack: Messaging, channels, users

Critical Rules Enforced

• ✅ No Example Domains: Blocks example.com, api.example.com
• ✅ No Placeholder Values: Detects YOUR_SERVICE, testParam, /whoami
• ✅ Correct Connection Types: Only allows valid types (apikey, oauth, etc.)
• ✅ Real API Endpoints: Validates against actual service documentation
• ✅ Service-Specific Patterns: Enforces proper error formats and headers

🔧 Debugging & Troubleshooting

Enable Debug Mode

import { Make } from '@aixyte/makehq-sdk-extended';

const make = new Make('your-api-key', 'eu2.make.com');
make.enableDebug(); // Shows detailed API requests/responses

// Now all API calls will log debug information
const connection = await make.sdkAppConnections.create(appName, appVersion, data);

Common Issues & Solutions

Connection Type Mapping Issues

// ❌ Problem: "apikey" becomes "basic"
make.enableDebug(); // Enable to see actual API responses

// Test different connection types
const result = await make.sdkAppConnections.create(appName, appVersion, {
    name: "test-connection",
    type: "apikey", // Will show if this gets converted
    label: "API Key Connection"
});

Section Upload Failures

// ❌ Problem: updateSection returns "Not found"
// ✅ Solution: Use enhanced helper methods
await make.sdkAppConnections.updateParameters(appName, appVersion, connectionName, [
    { name: "apiKey", type: "password", label: "API Key", required: true }
]);

await make.sdkAppConnections.updateApiConfig(appName, appVersion, connectionName, {
    url: "https://api.openai.com/v1/models",
    method: "GET"
});

Module-Connection Linking

// ❌ Problem: changeConnectionOrWebhook fails
// ✅ Solution: Use enhanced linking method
await make.sdkAppModules.linkToConnection(appName, appVersion, moduleName, connectionName);

Icon Upload Issues

// Validate icon before upload
const validation = make.sdkApps.validateIcon(iconBuffer);
if (!validation.valid) {
    console.log('Icon errors:', validation.errors);
}

// Enhanced upload with multiple format attempts
await make.sdkApps.updateIcon(appName, appVersion, iconBuffer, {
    format: 'png',
    validate: true
});

Method Signature Consistency

All SDK app components now use consistent signatures:

// ✅ All methods now include appVersion parameter
await make.sdkAppConnections.create(appName, appVersion, connectionData);
await make.sdkAppModules.create(appName, appVersion, moduleData);
await make.sdkAppRPCs.create(appName, appVersion, rpcData);

CLI Tool Usage

# Configure API credentials
make-cli config set api-key YOUR_API_KEY
make-cli config set zone eu1.make.com

# List your SDK apps
make-cli apps list

# Get app details
make-cli apps get my-app 1

# Upload a complete app from directory
make-cli apps upload ./my-app-directory my-app 1

# Create a new app
make-cli apps create my-new-app "My New App" "Description" "#4f8df5"

# List scenarios
make-cli scenarios list TEAM_ID

# Get help
make-cli help

🛠️ Enhanced Features

Fixed Module Creation

• Correct parameter: Uses moduleInitMode: 'example' (discovered from VS Code extension)
• Proper type mapping: Handles all module types (actions, triggers, searches, etc.)
• Error handling: Graceful failure with clear error messages

Fixed Connection Architecture

• Separate creation: Connections created independently, not embedded in base
• Type mapping: Automatically maps 'api-key' → 'apikey' and other variations
• Format handling: Converts array scopes to proper object format

Fixed Data Formats

• Samples: Converts arrays to {samples: array} format automatically
• Scopes: Converts arrays to empty objects for API key connections
• Proper validation: Handles edge cases in data structure

Complete Upload Process

The CLI now follows the correct upload architecture:

1. Create app with required audience parameter
2. Upload base section (without connections)
3. Create connections separately with proper type mapping
4. Create modules individually with correct moduleInitMode
5. Upload module sections (api, parameters, samples, etc.)
6. Create and upload RPCs with their sections
7. Create and upload functions with code
8. Upload README and documentation

Project Structure

make-cli-extended-sdk/
├── src/                       # Source code
│   ├── endpoints/             # API endpoint implementations
│   │   ├── sdk-apps.ts        # SDK Apps API (50+ endpoints)
│   │   ├── sdk-app-modules.ts # SDK App Modules API
│   │   ├── sdk-app-rpcs.ts    # SDK App RPCs API
│   │   ├── sdk-app-functions.ts # SDK App Functions API
│   │   ├── sdk-app-connections.ts # SDK App Connections API
│   │   ├── sdk-app-webhooks.ts # SDK App Webhooks API
│   │   └── ...                # Standard Make APIs
│   ├── cli.ts                 # CLI tool implementation
│   ├── index.ts               # Main SDK entry point
│   ├── make.ts                # Core Make client
│   ├── types.ts               # Common type definitions
│   ├── types-sdk-apps.ts      # SDK Apps type definitions
│   └── utils.ts               # Utility functions
├── test/                      # Comprehensive test suite
├── dist/                      # Compiled output
├── install-global.sh          # Global installation script
├── uninstall-global.sh        # Global uninstallation script
└── README.md                  # This file

Testing

Unit Tests

npm test

Integration Tests

# Set up your .env file first
npm run test:integration

Environment Setup

Create a .env file in the root directory:

MAKE_API_KEY="your-api-key"
MAKE_ZONE="eu1.make.com"
MAKE_TEAM="123456"
MAKE_ORGANIZATION="789012"

Note: Provide zone without https:// prefix (e.g., eu1.make.com).

Building

npm run build        # Builds both ESM and CJS versions
npm run build:docs   # Generate API documentation

🔧 CLI Installation Scripts

Global Installation

./install-global.sh

Global Uninstallation

./uninstall-global.sh

📚 API Coverage

SDK Apps APIs (New in Extended Version)

• Apps: Create, read, update, delete, clone, export, import
• Modules: Create, manage, upload sections with proper init modes
• RPCs: Create, configure, upload parameters and samples
• Functions: Create, upload code, manage serverless functions
• Connections: Create with type mapping, upload API definitions
• Webhooks: Configure webhook endpoints and handlers
• Reviews: Submit for review, manage approval process
• Icons: Upload and manage app icons
• Documentation: Manage README and API docs

Standard Make APIs (All Supported)

• Scenarios: List, create, activate, deactivate, run
• Teams: Manage team access and permissions
• Data Stores: CRUD operations on data storage
• Connections: Manage external service connections
• Hooks: Configure webhooks and triggers
• Users: User management and authentication
• Organizations: Organizational settings and billing

🐛 Bug Fixes & Improvements

This extended SDK fixes critical issues found in the original implementation:

• ✅ Module Init Mode: Fixed undocumented moduleInitMode parameter
• ✅ ES Module Support: Proper imports throughout the codebase
• ✅ Connection Architecture: Connections created separately from base config
• ✅ Data Format Handling: Automatic conversion of arrays to proper objects
• ✅ Type Safety: Enhanced TypeScript definitions for all APIs
• ✅ Error Handling: Comprehensive error messages and graceful failures
• ✅ CLI Functionality: Working command-line interface for app management

🤝 Contributing

This SDK was developed through extensive reverse-engineering of the Make.com VS Code extension and comprehensive testing of the API endpoints. Contributions are welcome!

📖 Documentation

Comprehensive Make App Development Guides

This package includes complete documentation for building Make.com apps:

• 00-LLM-DEVELOPMENT-RULES.md - Critical rules for LLM developers building Make apps
• 01-OVERVIEW.md - Documentation overview and navigation
• 02-FOLDER-STRUCTURE.md - Standard Make app folder structure
• 03-ESSENTIAL-FILES.md - Required files for every Make app
• 04-BASE-CONFIG.md - Global app configuration patterns
• 05-METADATA-CONFIG.md - App metadata and settings
• 06-CONNECTION-TYPES.md - Authentication patterns (OAuth, API Key, etc.)
• 07-MODULE-PATTERNS.md - Action, trigger, and search module patterns
• 08-PARAMETER-TYPES.md - Input/output parameter definitions
• 15-API-PATTERNS.md - API integration patterns and techniques
• 19-LLM-DEVELOPMENT-GUIDE.md - Complete guide for LLM-assisted development
• 20-COMMON-PATTERNS.md - Reusable code snippets and patterns
• 21-TROUBLESHOOTING.md - Common issues and solutions

Detailed API documentation is available after building:

npm run build:docs

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Based on the original @makehq/sdk with extensive enhancements
• API insights gained from Make.com's VS Code apps-sdk extension
• Community feedback and testing from Make.com developers

Need help? Check the issues page or refer to the comprehensive test suite for usage examples.