@juggernautlabs/plugins

🔌 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:

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:

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.

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.

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:

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)

{
    "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:

{
    "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

• Create a .env file containing your Juggernaut credentials:

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

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

  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?