Plugins

Extend Circuitry's capabilities with plugins that connect to external services and APIs.

What are Plugins?

Plugins are pre-built integrations that add new node types to your workflow editor. They enable:

• External API Integration: Connect to services like Slack, Gmail, Stripe
• Database Operations: Query and update databases
• File Operations: Process files and documents
• Custom Business Logic: Implement organization-specific functionality

Using Plugins

Available Plugins

Plugins are loaded dynamically and appear in your sidebar. Current categories:

• Communication: Slack, Email, SMS
• Productivity: Google Docs, Notion, Airtable
• Development: GitHub, GitLab, Jira
• Marketing: Mailchimp, HubSpot
• Finance: Stripe, PayPal
• Storage: AWS S3, Google Drive

Installing Plugins

1. Browse Available Plugins in the sidebar
2. Drag Plugin Node onto the canvas
3. Configure Connection if authentication required
4. Set Parameters for the specific action

Plugin Configuration

Each plugin node requires configuration:

Connection Setup

Many plugins require authentication:

1. Click on the plugin node
2. Select "Configure Connection"
3. Enter required credentials:
   • API Keys
   • OAuth tokens
   • Webhook URLs
4. Test the connection
5. Save for reuse across workflows

Action Configuration

After connection setup:

1. Select Action: Choose from available operations
2. Map Inputs: Connect data from previous nodes
3. Set Parameters: Configure action-specific settings
4. Handle Outputs: Process returned data

Plugin Examples

Slack Integration

Send messages to Slack channels:

// Plugin Configuration
{
  "plugin": "slack",
  "action": "send_message",
  "parameters": {
    "channel": "#notifications",
    "text": "{{input.message}}",
    "attachments": []
  }
}

Google Sheets

Read and write spreadsheet data:

// Read from sheet
{
  "plugin": "google-sheets",
  "action": "read_range",
  "parameters": {
    "spreadsheetId": "{{config.sheetId}}",
    "range": "A1:D10"
  }
}

// Write to sheet
{
  "plugin": "google-sheets",
  "action": "update_range",
  "parameters": {
    "spreadsheetId": "{{config.sheetId}}",
    "range": "A1",
    "values": "{{input.data}}"
  }
}

GitHub

Automate repository operations:

{
  "plugin": "github",
  "action": "create_issue",
  "parameters": {
    "owner": "{{config.owner}}",
    "repo": "{{config.repo}}",
    "title": "{{input.title}}",
    "body": "{{input.description}}",
    "labels": ["bug", "automated"]
  }
}

Connection Management

Security Best Practices

1. Never hardcode credentials in workflows
2. Use environment variables for sensitive data
3. Rotate API keys regularly
4. Limit scope to minimum required permissions
5. Monitor usage for unusual activity

Connection Types

API Key Authentication

Simple key-based authentication:

{
  "type": "api_key",
  "credentials": {
    "apiKey": "your-api-key-here"
  }
}

OAuth 2.0

For services requiring OAuth:

{
  "type": "oauth2",
  "credentials": {
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "accessToken": "current-access-token",
    "refreshToken": "refresh-token"
  }
}

Webhook

For receiving external events:

{
  "type": "webhook",
  "config": {
    "url": "https://circuitry.app/webhooks/your-id",
    "secret": "webhook-secret"
  }
}

Creating Custom Plugins

Plugin Structure

Basic plugin definition:

{
  "id": "my-plugin",
  "name": "My Custom Plugin",
  "description": "Description of what it does",
  "version": "1.0.0",
  "author": "Your Name",
  "icon": "icon-name",
  "actions": [
    {
      "id": "action-1",
      "name": "Action Name",
      "description": "What this action does",
      "parameters": [
        {
          "id": "param1",
          "name": "Parameter 1",
          "type": "string",
          "required": true,
          "description": "Parameter description"
        }
      ]
    }
  ],
  "connectionType": "api_key",
  "connectionFields": [
    {
      "id": "apiKey",
      "name": "API Key",
      "type": "password",
      "required": true
    }
  ]
}

Implementation

Plugins are implemented as JavaScript modules:

export async function execute(action, parameters, connection) {
  switch (action) {
    case 'action-1':
      return await performAction1(parameters, connection);
    default:
      throw new Error(`Unknown action: ${action}`);
  }
}

async function performAction1(params, conn) {
  // Implementation logic
  const response = await fetch(API_URL, {
    headers: {
      'Authorization': `Bearer ${conn.apiKey}`
    },
    body: JSON.stringify(params)
  });
  
  return await response.json();
}

Plugin Development

Development Workflow

1. Create Plugin Definition in /plugins directory
2. Implement Actions in JavaScript/TypeScript
3. Test Locally using development server
4. Submit for Review to plugin marketplace
5. Deploy for community use

Testing Plugins

Test your plugin thoroughly:

// Test file
import { execute } from './my-plugin';

describe('My Plugin', () => {
  test('action-1 works correctly', async () => {
    const result = await execute('action-1', {
      param1: 'test'
    }, {
      apiKey: 'test-key'
    });
    
    expect(result).toBeDefined();
  });
});

Best Practices

Performance

1. Cache responses when appropriate
2. Batch operations to reduce API calls
3. Handle rate limits gracefully
4. Implement retries with exponential backoff
5. Stream large datasets instead of loading all at once

Error Handling

Always handle errors gracefully:

try {
  const result = await pluginAction();
  return { success: true, data: result };
} catch (error) {
  return {
    success: false,
    error: {
      message: error.message,
      code: error.code,
      details: error.response?.data
    }
  };
}

Documentation

Document your plugin thoroughly:

1. Clear descriptions for all actions
2. Parameter documentation with examples
3. Error codes and troubleshooting
4. Usage examples and tutorials
5. API limits and pricing information

Troubleshooting

Common Issues

1. Authentication Failed: Check API keys and permissions
2. Rate Limit Exceeded: Implement backoff and retry logic
3. Invalid Parameters: Validate input data format
4. Network Errors: Check connectivity and firewall rules
5. Version Mismatch: Update plugin to latest version

Debug Mode

Enable debug logging for plugins:

{
  "debug": true,
  "logLevel": "verbose"
}

Next Steps

• Available Plugins Catalog
• Creating Your First Plugin
• Plugin API Reference
• Plugin Security Guidelines