@opendeveloper/plugin-sdk

The official WebDevserver Plugin SDK for developing plugins using TypeScript and NPM.

Installation

npm install @opendeveloper/plugin-sdk

Quick Start

Creating a Panel Plugin

import { PanelPluginBase, PanelRenderResult, createPluginFactory } from '@opendeveloper/plugin-sdk';

class MyPanelPlugin extends PanelPluginBase {
  async renderPanel(props?: Record<string, any>): Promise<PanelRenderResult> {
    return {
      html: '<div>Hello from my plugin!</div>',
      css: '.my-plugin { color: blue; }',
      js: 'console.log("Plugin loaded");'
    };
  }

  async handlePanelAction(action: string, data: any): Promise<any> {
    switch (action) {
      case 'refresh':
        return { success: true, message: 'Refreshed' };
      default:
        throw new Error(`Unknown action: ${action}`);
    }
  }
}

export default createPluginFactory(MyPanelPlugin);

Creating a Terminal Plugin

import { TerminalPluginBase, TerminalCommandContext, TerminalCommandResult, createPluginFactory } from '@opendeveloper/plugin-sdk';

class MyTerminalPlugin extends TerminalPluginBase {
  getSupportedCommands(): string[] {
    return ['hello', 'greet'];
  }

  async handleCommand(context: TerminalCommandContext): Promise<TerminalCommandResult> {
    const { command, args } = context;
    
    switch (command) {
      case 'hello':
        return {
          success: true,
          output: 'Hello from my plugin!',
          handled: true
        };
      
      case 'greet':
        const name = args[0] || 'World';
        return {
          success: true,
          output: `Hello, ${name}!`,
          handled: true
        };
      
      default:
        return {
          success: false,
          error: `Unknown command: ${command}`,
          handled: false
        };
    }
  }
}

export default createPluginFactory(MyTerminalPlugin);

Creating an Action Plugin

import { ActionPluginBase, ActionDefinition, ActionExecutionContext, ActionExecutionResult, createPluginFactory } from '@opendeveloper/plugin-sdk';

class MyActionPlugin extends ActionPluginBase {
  getAvailableActions(): ActionDefinition[] {
    return [
      {
        name: 'notify',
        description: 'Send a notification',
        parameters: [
          {
            name: 'message',
            type: 'string',
            required: true,
            description: 'The notification message'
          },
          {
            name: 'type',
            type: 'string',
            required: false,
            defaultValue: 'info',
            validation: {
              enum: ['info', 'warning', 'error', 'success']
            }
          }
        ]
      }
    ];
  }

  async executeAction(context: ActionExecutionContext): Promise<ActionExecutionResult> {
    const { actionName, parameters } = context;
    
    switch (actionName) {
      case 'notify':
        // Send notification logic here
        await this.api.events.emit('notification', {
          message: parameters.message,
          type: parameters.type || 'info'
        });
        
        return {
          success: true,
          result: { notified: true },
          duration: 0
        };
      
      default:
        throw new Error(`Unknown action: ${actionName}`);
    }
  }
}

export default createPluginFactory(MyActionPlugin);

Package.json Configuration

Add WebDevserver-specific configuration to your package.json:

{
  "name": "@opendeveloper/plugin-my-awesome-plugin",
  "version": "1.0.0",
  "description": "My awesome WebDevserver plugin",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "keywords": ["webdevserver", "webdevserver-plugin"],
  "peerDependencies": {
    "@opendeveloper/plugin-sdk": "^1.0.0"
  },
  "webdevserver": {
    "type": "panel",
    "apiVersion": "1.0",
    "permissions": {
      "network": true,
      "github": true
    },
    "frontend": {
      "entry": "dist/frontend.js",
      "component": "MyPluginComponent"
    },
    "resources": {
      "limits": {
        "memory": 128,
        "cpu": 10,
        "storage": 50,
        "apiCalls": 1000
      }
    }
  }
}

Plugin Types

Panel Plugins

• Render UI content in the WebDevserver interface
• Handle user interactions
• Support HTML, CSS, and JavaScript output

Terminal Plugins

• Add custom terminal commands
• Process command-line interactions
• Integrate with the WebDevserver terminal

Action Plugins

• Provide automated actions
• Support parameter validation
• Enable workflow automation

Hybrid Plugins

• Combine multiple plugin types
• Support complex functionality
• Maximum flexibility

API Reference

Plugin API

The plugin API provides access to:

• Storage: Persistent data storage for plugins
• Events: Inter-plugin communication and system events
• Permissions: Security and access control
• Utils: Logging and utility functions
• HTTP: Network requests (if permitted)
• FS: File system access (if permitted)

Base Classes

• PluginModuleBase: Base class for all plugins
• PanelPluginBase: Specialized for UI panels
• TerminalPluginBase: Specialized for terminal commands
• ActionPluginBase: Specialized for automated actions
• HybridPluginBase: Support for multiple capabilities

Development Workflow

1. Create Plugin: Use the plugin templates or start from scratch
2. Local Development: Use npm link for local testing
3. Build: Compile TypeScript and bundle assets
4. Test: Validate plugin functionality
5. Publish: Publish to NPM registry

Best Practices

• Always declare required permissions
• Implement proper error handling
• Use TypeScript for type safety
• Follow semantic versioning
• Include comprehensive documentation
• Validate user input
• Respect resource limits

License

MIT