Module Format Specification

Directory Structure

my-module/
├── src/
│   └── index.ts          # Module class with @Action decorators
├── test/
│   └── index.test.ts     # Tests (required for trust score)
├── jarvis.config.json    # Module metadata
├── package.json
├── tsconfig.json
└── README.md             # Used for module page description

jarvis.config.json

{
  "name": "my-custom-module",
  "displayName": "My Custom Module",
  "description": "A module that does something useful",
  "version": 1,
  "category": "analytics",
  "tags": ["data", "analytics", "processing"],
  "pricingTier": "free",
  "pricePerCall": 0,
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://example.com"
  },
  "config": {
    "schema": {
      "api_key": { "type": "string", "required": true, "secret": true },
      "batch_size": { "type": "number", "default": 10 }
    }
  },
  "actions": [
    {
      "name": "processData",
      "description": "Process data and return insights",
      "inputSchema": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "description": "Data to process" }
        },
        "required": ["data"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "processed": { "type": "number" },
          "results": { "type": "array" }
        }
      }
    }
  ]
}

Module Class

Modules extend the base Module class and use the @Action decorator to expose executable endpoints.

import { Module, Action, Config } from '@jarvis-sdk/module';

export default class MyModule extends Module {
  // Required metadata
  name = 'my-custom-module';
  version = 1;
  description = 'Does something useful';
  category = 'analytics';

  // Access module config
  @Config() config!: { api_key: string; batch_size: number };

  // Lifecycle hooks
  async onInstall() {
    // Validate config, set up resources
    console.log('Module installed with config:', this.config);
  }

  async onUninstall() {
    // Clean up resources
  }

  // Actions become executable endpoints
  @Action('Process data and return insights')
  async processData(input: { data: any[] }) {
    const batchSize = this.config.batch_size || 10;
    const batches = [];

    for (let i = 0; i < input.data.length; i += batchSize) {
      batches.push(input.data.slice(i, i + batchSize));
    }

    const results = [];
    for (const batch of batches) {
      // Process each batch
      results.push(...batch.map(item => ({
        ...item,
        processed: true,
        timestamp: new Date().toISOString(),
      })));
    }

    return { processed: results.length, results };
  }

  // Health check (recommended)
  @Action('Check module health and connectivity')
  async healthCheck() {
    return {
      status: 'healthy',
      uptime: process.uptime(),
      config_valid: !!this.config.api_key,
    };
  }
}

Self-Healing

Modules can implement the diagnose() and heal() methods to enable automatic error recovery.

import { Module, Action, Healable } from '@jarvis-sdk/module';

export default class MyModule extends Module implements Healable {
  // ...

  async diagnose() {
    const issues = [];

    // Check API connectivity
    try {
      await fetch('https://api.example.com/health');
    } catch {
      issues.push({
        type: 'connectivity',
        message: 'Cannot reach API endpoint',
        severity: 'high',
      });
    }

    // Check config validity
    if (!this.config.api_key) {
      issues.push({
        type: 'config',
        message: 'API key is missing',
        severity: 'critical',
      });
    }

    return { issues, healthy: issues.length === 0 };
  }

  async heal(issues: any[]) {
    const actions = [];

    for (const issue of issues) {
      if (issue.type === 'connectivity') {
        // Try fallback endpoint
        actions.push('Switched to fallback API endpoint');
      }
    }

    return { healed: true, actions_taken: actions };
  }
}

Publishing

# Run tests first (required)
jarvis-sdk test

# Validate module format
jarvis-sdk validate

# Publish to marketplace
jarvis-sdk publish

# Check your module's trust score
jarvis-sdk trust my-custom-module

Pricing Your Module

Set pricing in jarvis.config.json:

"pricingTier": "free"
"pricePerCall": 0

"pricingTier": "pro"
"pricePerCall": 0.005