npm package: @juggernautlabs/plugins
Description: Plugins SDK and CLI for Juggernaut
Author: Juggernaut Labs
Latest version: 0.0.14

# 🔌 Juggernaut Plugins Development Documentation

This documentation outlines the steps and requirements for creating, compiling, and deploying plugins for the Juggernaut platform using the `@juggernautlabs/plugins` package.

-----

## 1\. Getting Started

### Installation

To begin developing Juggernaut Plugins, install the core package:

```bash
npm install @juggernautlabs/plugins
```

### Compilation (TypeScript)

If you use TypeScript, you must compile your source code into JavaScript before deployment. Run the TypeScript compiler using your configuration file:

```bash
tsc --build tsconfig.json
```

The `pluginPath` in your deployment configuration (see Section 4) must point to this compiled JavaScript file.

-----

## 2\. Plugin Class Structure

Your plugin must be implemented as a **TypeScript class** that **extends** one of the following base classes, based on your authentication needs.

### 2.1. `IntegrationPlugin`

Use for plugins that require **no authentication** or only **simple API key**-based authentication/settings.

| Feature | Details |
| :--- | :--- |
| **Extends** | `IntegrationPlugin` |
| **Authentication** | Handled via the constructor's `settings` or `authSetting` arguments. |

```typescript
import { IntegrationPlugin } from '@juggernautlabs/plugins'
// ...

export default class InvestmentPerformancePlugin extends IntegrationPlugin {

    // Mandatory static property
    static get operations() {
        return Operations;
    }

    constructor(authSetting, settings) {
        super();
        this.settings = settings || {};
        // Initialize client using settings/authSetting
    }

    // Example operation method
    async getStockQuote({ symbol }) {
        // ... implementation
    }
}
```

### 2.2. `OAuthPlugin`

Use for plugins that require a secure **OAuth 2.0 connection** for authorization.

| Feature | Details |
| :--- | :--- |
| **Extends** | `OAuthPlugin` |
| **Authentication** | Requires defining an `AuthSchema` and using credentials provided in `authSettings` to initialize the client. |

```typescript
import { OAuthPlugin, PluginField } from '@juggernautlabs/plugins'
// ...

export default class GoogleDrivePlugin extends OAuthPlugin {
    // ...

    constructor(authSettings: Record<string, any>, settings?: Record<string, any>) {
        super();
        this.initialize(authSettings);
    }

    // Mandatory static property
    static get operations(): Record<string, PluginOperation> {
        return Operations;
    }

    // Defines additional fields needed for OAuth setup
    static get AuthSchema(): Record<string, PluginField> {
        return {
            accessToken: {
                type: 'string',
                description: 'The OAuth access token...',
                required: true
            }
        };
    }
    
    // ... operation methods
}
```

-----

## 3\. Core Class Properties

Every plugin class must expose specific static properties to define its interface and authentication requirements.

### 3.1. `static get operations()`

This **mandatory** property exposes your plugin's functionality. It returns a mapping where the key is the internal operation identifier, and the value is the full action definition.

| Property | Type | Description |
| :--- | :--- | :--- |
| `name` | `string` | Display name of the operation. |
| `description` | `string` | Explanation of the action's purpose. |
| `operation` | `string` | The exact **method name** in your plugin class that executes the action (e.g., `'listFiles'`). |
| `scope` | `string[]` | Where the operation can be used: `'Prompt'` (AI) or `'Action'` (direct use). |
| `data` | `object` | A schema defining all input arguments for the operation. |

#### Example of `data` Field Structure

The `data` object specifies the arguments your method accepts:

```typescript
data: {
    // Required string input
    symbol: {
        type: 'string',
        description: 'Stock Symbol',
        required: true 
    },
    // Optional number input with a default value
    timePeriod: {
        type: 'number',
        description: 'Time Period',
        required: false,
        default: 220
    },
    // Optional string input with restricted values (enum/options)
    type: {
        type: 'string',
        description: 'Option Type (call, put, all)',
        required: false,
        options: ['call', 'put', 'all'] 
    }
}
```

### 3.2. `static get AuthSchema()`

This property defines the required fields for authentication or configuration.

  * For **OAuth** classes, this defines fields like `clientId`, `clientSecret`, `redirectUri`. Note that the platform automatically manages the core OAuth properties (`accessToken`, `refreshToken`, `expires`, `expiresAt`), but you may include them if your implementation requires them for initialization.
  * For **Integration** classes, this can define required API keys or simple configuration settings.

-----

## 4\. Deployment

### 4.1. Configuration File

Create a JSON configuration file named **`.juggernautplugin`** in your plugin's root directory.

#### Standard Plugin Configuration (`IntegrationPlugin`)

```json
{
    "name": "My Plugin",
    "pluginPath": "dist/MyPlugin.js",
    "description": "Description of my plugin"
}
```

#### OAuth Plugin Configuration (`OAuthPlugin`)

This configuration requires additional fields for the OAuth flow setup:

```json
{
    "name": "My OAuth Plugin",
    "pluginPath": "dist/MyOAuthPlugin.js",
    "description": "Description of my OAuth plugin",
    "authType": "oauth",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "authUrl": "https://example.com/oauth/authorize",   
    "tokenUrl": "https://example.com/oauth/token",
    "scopes": ["scope1", "scope2"]
}
```

### 4.2. Folder Structure

Ensure your compiled JavaScript files are accessible via the path specified in `pluginPath`:

```
/MyPlugin
   /dist
      MyPlugin.js  <-- The compiled file
   .juggernautplugin
```

### 4.3. Execution and API Key

1.  Create a **`.env`** file containing your Juggernaut credentials:

    ```
    JUGGERNAUT_API_KEY=your-api-key
    JUGGERNAUT_CLIENT_ID=your-client-id
    ```

2.  Run the bundle command from your plugin's root directory:

    ```bash
    npx @juggernautlabs/plugins bundle
    ```

      * The **first run** deploys a new plugin.
      * Subsequent runs will use the `pluginId` (which is added to your `.juggernautplugin` file after the initial deployment) to deploy a **new version** of the existing plugin.

Would you like to review an example of how an array input field is structured in the `operations` schema?