npm package: @opendeveloper/plugin-sdk
Description: WebDevserver Plugin SDK - Core interfaces and utilities for plugin development
Author: OpenDeveloper
Latest version: 1.0.0

# @opendeveloper/plugin-sdk

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

## Installation

```bash
npm install @opendeveloper/plugin-sdk
```

## Quick Start

### Creating a Panel Plugin

```typescript
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

```typescript
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

```typescript
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:

```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