@chklff/bridge-lovable-sdk v1.0.9

Bridge Lovable SDK

The official Bridge SDK for seamless Make automations in Lovable projects with Supabase integration.

🚀 Quick Start

Installation

npm install @chklff/bridge-lovable-sdk@latest

⚠️ If you have an older version (1.0.6 or below), update to the latest:

npm uninstall @chklff/bridge-lovable-sdk
npm install @chklff/bridge-lovable-sdk@latest

Basic Setup

🔥 RECOMMENDED FOR LOVABLE: Direct configuration (no env files needed)

import { createBridgeClient } from '@chklff/bridge-lovable-sdk';

// ✅ BEST FOR LOVABLE: Direct configuration
const bridge = createBridgeClient({
  supabase: {
    url: 'https://your-project.supabase.co',
    serviceRoleKey: 'your-service-role-key'
  },
  makebridge: {
    secretKey: 'your-bridge-secret',
    keyId: 'your-bridge-key-id',
    zoneUrl: 'https://eu2.make.com',
    organizationId: 1234567
  }
});

// Alternative: Environment variables (for Node.js projects)
const bridge = createBridgeClient();

🎯 Lovable Integration

For Lovable projects, use direct configuration instead of environment variables:

// In your Lovable component or server action
import { createBridgeClient } from '@chklff/bridge-lovable-sdk';

const bridge = createBridgeClient({
  supabase: {
    url: 'https://your-project.supabase.co',
    serviceRoleKey: 'your-service-role-key'  // Add to Supabase Edge Functions secrets
  },
  makebridge: {
    secretKey: 'your-bridge-secret',         // Add to Supabase Edge Functions secrets
    keyId: 'your-bridge-key-id',
    zoneUrl: 'https://eu2.make.com',
    organizationId: 1234567
  }
});

// Now use the bridge client
const templates = await bridge.getTemplates();
const user = await bridge.createUser({ email, name });

Environment Variables (Node.js only)

For traditional Node.js projects, add these to your .env file:

# Supabase Configuration
SUPABASE_URL=your-supabase-url
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Make Bridge Configuration
MAKE_BRIDGE_SECRET_KEY=your-bridge-secret
MAKE_BRIDGE_KEY_ID=your-bridge-key-id
MAKE_BRIDGE_ZONE_URL=https://eu2.make.com
MAKE_BRIDGE_ORGANIZATION_ID=1234567

Database Setup

The SDK requires specific Supabase tables to function properly. Create these tables in your Supabase project:

1. Users Table

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  fname TEXT,
  lname TEXT,
  extname TEXT,
  make_customer_id INTEGER,
  make_organization_id INTEGER,
  make_operations_limit INTEGER,
  make_transfer_limit INTEGER,
  make_consumed_operations INTEGER DEFAULT 0,
  make_consumed_transfer INTEGER DEFAULT 0,
  make_is_paused BOOLEAN DEFAULT false,
  make_synced_at TIMESTAMP WITH TIME ZONE,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT now()
);

-- Create indexes
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_make_customer_id ON users(make_customer_id);

2. Make Templates Table

CREATE TABLE make_templates (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  make_template_id INTEGER NOT NULL,
  public_version_id TEXT NOT NULL,
  name TEXT NOT NULL,
  description TEXT,
  category TEXT,
  trigger_events TEXT[],
  configuration_schema JSONB,
  webhook_config JSONB,
  metadata JSONB,
  is_active BOOLEAN NOT NULL DEFAULT true,
  synced_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT now()
);

-- Create indexes
CREATE INDEX idx_make_templates_public_version_id ON make_templates(public_version_id);
CREATE INDEX idx_make_templates_make_template_id ON make_templates(make_template_id);
CREATE INDEX idx_make_templates_category ON make_templates(category);
CREATE INDEX idx_make_templates_is_active ON make_templates(is_active);

3. User Automations Table

CREATE TABLE user_automations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  template_id UUID NOT NULL REFERENCES make_templates(id) ON DELETE RESTRICT,
  public_version_id TEXT NOT NULL,
  flow_id TEXT NOT NULL,
  scenario_id TEXT,
  wizard_url TEXT,
  status TEXT NOT NULL DEFAULT 'initializing',
  webhook_data TEXT,
  configuration JSONB,
  created_components JSONB,
  completed_at TIMESTAMP WITH TIME ZONE,
  last_synced_at TIMESTAMP WITH TIME ZONE,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT now()
);

-- Create indexes
CREATE INDEX idx_user_automations_user_id ON user_automations(user_id);
CREATE INDEX idx_user_automations_template_id ON user_automations(template_id);
CREATE INDEX idx_user_automations_flow_id ON user_automations(flow_id);
CREATE INDEX idx_user_automations_scenario_id ON user_automations(scenario_id);
CREATE INDEX idx_user_automations_status ON user_automations(status);

4. Automation Logs Table (Optional - for monitoring)

CREATE TABLE automation_logs (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  automation_id UUID REFERENCES user_automations(id) ON DELETE CASCADE,
  execution_id TEXT,
  event_type TEXT,
  event_data JSONB,
  status TEXT NOT NULL,
  input_data JSONB,
  output_data JSONB,
  error_message TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT now()
);

-- Create indexes
CREATE INDEX idx_automation_logs_automation_id ON automation_logs(automation_id);
CREATE INDEX idx_automation_logs_status ON automation_logs(status);
CREATE INDEX idx_automation_logs_event_type ON automation_logs(event_type);

Row Level Security (RLS)

Enable RLS and create policies for your application:

-- Enable RLS
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE make_templates ENABLE ROW LEVEL SECURITY;
ALTER TABLE user_automations ENABLE ROW LEVEL SECURITY;
ALTER TABLE automation_logs ENABLE ROW LEVEL SECURITY;

-- Example policies (customize based on your auth requirements)
CREATE POLICY "Public read access for make_templates" ON make_templates
  FOR SELECT USING (is_active = true);

CREATE POLICY "Users can read their own data" ON users
  FOR SELECT USING (auth.uid() = id);

CREATE POLICY "Users can read their own automations" ON user_automations
  FOR SELECT USING (user_id = auth.uid());

📚 Core Features

User Management

// Create a new user
const user = await bridge.createUser({
  email: 'user@example.com',
  name: 'John Doe',
  firstName: 'John',
  lastName: 'Doe'
});

// Get user by email or ID
const user = await bridge.getUser('user@example.com');

// Delete user (removes from both Supabase and Make Bridge)
const result = await bridge.deleteUser('user@example.com');

Template Management

// Get available automation templates
const templates = await bridge.getTemplates();

// Filter by category
const emailTemplates = await bridge.getTemplates('email');

// Sync templates from Make Bridge
await bridge.syncTemplates();

Automation Initialization

// Initialize automation for a user
const automation = await bridge.initializeAutomation({
  templateId: '2800',
  userId: user.id,
  userName: user.name,
  config: {
    autoActivate: true,
    autoFinalize: true,
    scenarioName: 'My Custom Automation'
  }
});

console.log('Wizard URL:', automation.wizardUrl);
console.log('Flow ID:', automation.flowId);

Triggering Automations

// Trigger an automation with event data
const result = await bridge.triggerAutomation({
  templateId: '2800',
  userId: user.id,
  eventType: 'user_signup',
  eventData: {
    userId: user.id,
    email: user.email,
    signupDate: new Date().toISOString()
  }
});

⚛️ React Integration

Hooks for Lovable Projects

import { 
  useBridgeAutomation, 
  useBridgeTemplates, 
  useBridgeUser 
} from '@chklff/bridge-lovable-sdk';

function AutomationDashboard({ user, bridgeClient }) {
  const {
    automations,
    loading,
    error,
    initializeAutomation,
    triggerAutomation
  } = useBridgeAutomation(bridgeClient, user.id);

  const {
    templates,
    syncTemplates,
    filterByCategory
  } = useBridgeTemplates(bridgeClient);

  const handleCreateAutomation = async (templateId) => {
    await initializeAutomation({
      templateId,
      userName: user.name
    });
  };

  return (
    <div>
      <h2>Your Automations</h2>
      {loading && <p>Loading...</p>}
      {error && <p className="error">{error}</p>}
      
      <div className="templates">
        {templates.map(template => (
          <div key={template.id} className="template-card">
            <h3>{template.name}</h3>
            <p>{template.description}</p>
            <button onClick={() => handleCreateAutomation(template.publicVersionId)}>
              Create Automation
            </button>
          </div>
        ))}
      </div>
      
      <div className="automations">
        {automations.map(automation => (
          <div key={automation.id} className="automation-card">
            <h4>{automation.name}</h4>
            <span className={`status ${automation.status}`}>
              {automation.status}
            </span>
          </div>
        ))}
      </div>
    </div>
  );
}

Template Selector Component

import { useBridgeTemplates } from '@chklff/bridge-lovable-sdk';

function TemplateSelector({ bridgeClient, onSelectTemplate }) {
  const {
    templates,
    loading,
    searchTemplates,
    getTemplatesByCategory
  } = useBridgeTemplates(bridgeClient);

  const [searchQuery, setSearchQuery] = useState('');
  const filteredTemplates = searchTemplates(searchQuery);
  const categorizedTemplates = getTemplatesByCategory();

  return (
    <div className="template-selector">
      <input
        type="text"
        placeholder="Search templates..."
        value={searchQuery}
        onChange={(e) => setSearchQuery(e.target.value)}
      />
      
      {searchQuery ? (
        <div className="search-results">
          {filteredTemplates.map(template => (
            <TemplateCard 
              key={template.id} 
              template={template} 
              onSelect={onSelectTemplate} 
            />
          ))}
        </div>
      ) : (
        <div className="categories">
          {Object.entries(categorizedTemplates).map(([category, templates]) => (
            <div key={category} className="category">
              <h3>{category}</h3>
              {templates.map(template => (
                <TemplateCard 
                  key={template.id} 
                  template={template} 
                  onSelect={onSelectTemplate} 
                />
              ))}
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

🛠️ Advanced Usage

Custom Configuration

import { BridgeSDK } from '@chklff/bridge-lovable-sdk';

const bridge = new BridgeSDK({
  supabase: {
    url: process.env.SUPABASE_URL,
    serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY
  },
  makebridge: {
    secretKey: process.env.MAKE_BRIDGE_SECRET_KEY,
    keyId: process.env.MAKE_BRIDGE_KEY_ID,
    zoneUrl: process.env.MAKE_BRIDGE_ZONE_URL,
    organizationId: Number(process.env.MAKE_BRIDGE_ORGANIZATION_ID)
  }
});

Error Handling

try {
  const automation = await bridge.initializeAutomation({
    templateId: '2800',
    userId: user.id,
    userName: user.name
  });
} catch (error) {
  if (error.message.includes('Template not found')) {
    console.error('Template does not exist');
  } else if (error.message.includes('User not found')) {
    console.error('User needs to be created first');
  } else {
    console.error('Automation failed:', error.message);
  }
}

Analytics and Monitoring

// Get automation analytics
const analytics = await bridge.getAnalytics();
console.log('Total executions:', analytics.totalExecutions);
console.log('Success rate:', analytics.successfulExecutions / analytics.totalExecutions);

// Get analytics for specific template
const templateAnalytics = await bridge.getAnalytics('2800');

// Get analytics for specific user
const userAnalytics = await bridge.getAnalytics(null, user.id);

Webhook Management

// Get user's webhook URLs
const webhooks = await bridge.getUserWebhooks(user.id);
webhooks.forEach(webhook => {
  console.log(`${webhook.name}: ${webhook.url}`);
});

// Check automation flow completion
const completion = await bridge.checkFlowCompletion(flowId, user.id);
if (completion.isComplete) {
  console.log('Automation setup complete!');
}

🎯 TypeScript Support

Full TypeScript support with comprehensive type definitions:

import { 
  BridgeSDK, 
  BridgeConfiguration, 
  AutomationTemplate, 
  BridgeUser 
} from '@chklff/bridge-lovable-sdk';

const config: BridgeConfiguration = {
  supabase: {
    url: process.env.SUPABASE_URL!,
    serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY!
  },
  makebridge: {
    secretKey: process.env.MAKE_BRIDGE_SECRET_KEY!,
    keyId: process.env.MAKE_BRIDGE_KEY_ID!,
    zoneUrl: process.env.MAKE_BRIDGE_ZONE_URL!,
    organizationId: Number(process.env.MAKE_BRIDGE_ORGANIZATION_ID!)
  }
};

const bridge = new BridgeSDK(config);

const user: BridgeUser = await bridge.createUser({
  email: 'user@example.com',
  name: 'John Doe'
});

✅ Testing & Validation

Before using the SDK, run the health check to ensure everything is configured correctly:

# Run comprehensive health check
npx @chklff/bridge-lovable-sdk health-check

# Validate environment variables only
npx @chklff/bridge-lovable-sdk validate-env

This will test:

• ✅ Environment variables
• ✅ Supabase connection and tables
• ✅ Make Bridge API access
• ✅ Template synchronization
• ✅ User creation functionality

Quick Setup Validation

1. Install the latest working version:

   npm install @chklff/bridge-lovable-sdk@latest

2. Set up environment variables (see Database Setup section above)

3. Run health check:

   npx @chklff/bridge-lovable-sdk health-check

4. If health check fails, see TROUBLESHOOTING.md for solutions

Common Issues

• "Template sync fails" → Check Make Bridge credentials and organization ID
• "Database tables not found" → Run the SQL setup scripts in Supabase
• "Environment variables missing" → Create .env file with all required variables
• "Permission denied" → Use Service Role Key, not anon key for Supabase

📚 Full troubleshooting guide: TROUBLESHOOTING.md

🧪 CLI Tools

The SDK includes powerful CLI tools for development and testing:

# Health & Validation
npx @chklff/bridge-lovable-sdk health-check
npx @chklff/bridge-lovable-sdk validate-env

# User Management
npx @chklff/bridge-lovable-sdk create-user test@example.com "Test User"
npx @chklff/bridge-lovable-sdk delete-user test@example.com

# Template Management
npx @chklff/bridge-lovable-sdk sync-enhanced
npx @chklff/bridge-lovable-sdk sync-status
npx @chklff/bridge-lovable-sdk lifecycle-stats

# Automation
npx @chklff/bridge-lovable-sdk init-template 2800 test@example.com

📁 Project Structure

@chklff/bridge-lovable-sdk/
├── src/
│   ├── lib/
│   │   ├── bridge-sdk.js           # Main SDK class
│   │   ├── client-factory.js       # Quick initialization
│   │   ├── integrations/           # Make Bridge & Supabase
│   │   ├── templates/              # Template management
│   │   ├── users/                  # User management
│   │   └── utils/                  # Utilities & validation
│   ├── react/                      # React hooks
│   ├── types/                      # TypeScript definitions
│   └── cli/                        # CLI tools
├── examples/                       # Usage examples
└── docs/                          # Documentation

🔧 Development

# Install dependencies
npm install

# Run CLI in development
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

📖 Examples

Check out the /examples directory for complete integration examples:

• Next.js Integration
• React Component Library
• Server-side Usage
• CLI Automation Scripts

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

🆘 Support

• 🐛 Issues: GitHub Issues
• 📦 npm Package: https://www.npmjs.com/package/@chklff/bridge-lovable-sdk
• 📚 Full Documentation: GitHub Repository

Built with ❤️ for the Lovable community