@earnbasejs/plugin NPM

EarnBase Plugin SDK

Official SDK for developing plugins for the EarnBase platform.

Installation

# Using npm
npm install @earnbasejs/plugin

# Using yarn 
yarn add @earnbasejs/plugin

Features

🚀 Fast and simple plugin development
🔒 Secure sandbox execution
📦 Hot reload during development
🔄 Message queue integration
📊 Resource monitoring
🛠 CLI development tools
📝 Complete type definitions

Quick Start

Create new plugin:

# Create plugin from template
earnbase create my-plugin

# Navigate to plugin directory
cd my-plugin

# Install dependencies
yarn install

Code your plugin:

import { BasePlugin, PluginMetadata } from '@earnbasejs/plugin';

export class MyPlugin extends BasePlugin {
  // Define plugin metadata
  public static metadata: PluginMetadata = {
    name: 'my-plugin',
    version: '1.0.0',
    description: 'My awesome plugin',
    tasks: [
      {
        name: 'example',
        description: 'Example task',
        inputSchema: [
          {
            name: 'message',
            type: 'string',
            required: true,
            description: 'Message to process'
          }
        ],
        outputSchema: [
          {
            name: 'result',
            type: 'string',
            description: 'Processed result'
          }
        ]
      }
    ],
    resources: {
      cpu: '0.5',
      memory: '512Mi',
      timeout: 300
    }
  };

  // Register tasks
  protected registerTasks(): void {
    this.registerTask('example', {
      name: 'example',
      description: 'Example task',
      async validate(input) {
        return !!input.message;
      },
      async execute(input) {
        // Task implementation
        return { result: `Processed: ${input.message}` };
      }
    });
  }
}

Development:

# Start development server with hot reload
yarn dev

# Build for production
yarn build

# Run tests
yarn test

Detailed Guide

Plugin Structure

my-plugin/
├── src/
│   └── index.ts           # Plugin implementation
├── tests/
│   └── index.test.ts      # Test files
├── package.json           
├── tsconfig.json          
└── README.md

Plugin Lifecycle

Initialization

async onInit(): Promise<void> {
  // Plugin initialization
}

Task Execution

async executeTask(name: string, input: any): Promise<any> {
  // Execute specific task
}

Cleanup

async onStop(): Promise<void> {
  // Cleanup resources
}

Message Queue Integration

// Report progress
await this.context.reportProgress({
  taskName: 'example',
  status: ExecutionStatus.RUNNING,
  progress: 50,
  message: 'Processing...'
});

// Send output
await this.context.sendOutput({
  result: 'success'
});

Resource Management

@Plugin({
  resources: {
    cpu: '0.5',      // CPU limit
    memory: '512Mi', // Memory limit
    timeout: 300     // Execution timeout
  }
})

Error Handling

try {
  await this.processData();
} catch (error) {
  this.logger.error('Processing failed', error);
  throw new PluginError('PROCESSING_FAILED', error.message);
}

CLI Commands

# Create new plugin
earnbase create my-plugin

# Create new plugin using AI
earnbase create:ai

# Development
earnbase dev

# Build
earnbase build

# Deploy
earnbase deploy

Testing

import { PluginTester } from '@earnbasejs/plugin/testing';

describe('MyPlugin', () => {
  let tester: PluginTester<MyPlugin>;

  beforeEach(async () => {
    tester = new PluginTester({
      plugin: MyPlugin,
      context: { /* test context */ }
    });
    await tester.setup();
  });

  it('should process correctly', async () => {
    const result = await tester.execute('example', {
      message: 'test'
    });
    expect(result.result).toBe('Processed: test');
  });
});

Best Practices

Task Design

Each task performs a specific function
Careful input validation
Regular progress reporting
Graceful error handling

Resource Usage

Monitor resource consumption
Clean up resources after use
Set appropriate timeouts
Handle rate limiting

Security

Validate all inputs
Use secure defaults
Follow least privilege principle
Sanitize outputs

Testing

Unit tests for each task
Integration tests
Performance tests
Security tests

Example Plugins

Facebook Plugin:

export class FacebookPlugin extends BasePlugin {
  protected registerTasks(): void {
    this.registerTask('createPost', {
      async execute(input) {
        // Create Facebook post
      }
    });
  }
}

Grass Airdrop Plugin:

export class GrassPlugin extends BasePlugin {
  protected registerTasks(): void {
    this.registerTask('dailyCheckIn', {
      async execute() {
        // Daily check in
      }
    });
  }
}

Task Types

1. Simple Task

Basic task implementation with single operation.

2. Retryable Task

Task with automatic retry on failure:

this.registerTask('retryableTask', {
  retryStrategy: {
    maxAttempts: 3,
    delay: 1000,  
    backoff: true
  }
});

3. Concurrent Task

Task that processes multiple items in parallel:

this.registerTask('concurrentTask', {
  maxConcurrent: 5,
  async execute(items) {
    return Promise.all(items.map(this.processItem));
  }
});

4. Long Running Task

Task for long operations with progress tracking:

this.registerTask('longTask', {
  async execute() {
    await this.setProgress(0);
    // Long operation
    await this.setProgress(100);
  }
});

AI-Powered Plugin Creation

Create a new plugin with AI assistance:

# Create plugin using AI
earnbase create:ai

# Follow the interactive prompts:
1. Configure OpenAI settings (first time only)
   - Enter OpenAI API key
   - Optionally set custom API endpoint
   - Select model (GPT-4, GPT-3.5-turbo, etc)

2. Enter plugin details
   - Name
   - Description  
   - Author

3. Describe your plugin's tasks
   - What should each task do?
   - Input/output requirements
   - Special features (retry, concurrent, etc)

4. Review and customize generated code
   - Preview generated code
   - Add validation
   - Add test cases
   - Add documentation

5. Create project files
   - Generated plugin code
   - Test files
   - README & documentation

The AI will help you create: