JavaScript Integrations

This document explains how to create JavaScript integrations for the Connect platform.

Overview

Integrations allow you to extend the capabilities of the AI assistant by providing custom tools that can be used to perform specific tasks. Each integration consists of:

1. A JSON configuration file (integration.json) that defines the integration metadata and tool schemas
2. JavaScript files that implement the tools, with either main.js or index.js as the entry point

Creating an Integration

1. Create the Integration Configuration

Create an integration.json file with the following structure:

{
  "id": "unique-integration-id",
  "name": "Integration Name",
  "description": "Description of what your integration does",
  "version": "1.0.0",
  "author": "Your Name",
  "publishedAt": "2024-03-14",
  "tools": [
    {
      "name": "toolName",
      "description": "Description of what this tool does",
      "parameters": {
        "type": "object",
        "properties": {
          "paramName": {
            "type": "string",
            "description": "Description of this parameter"
          },
          "optionalParam": {
            "type": "number",
            "description": "Description of this optional parameter",
            "default": 42
          }
        },
        "required": ["paramName"]
      }
    }
  ]
}

2. Implement the Tools

Create either a main.js or index.js file (both are supported as entry points) that implements the tools defined in your integration configuration. You'll register your tools using the connect.tools.register method:

// Your integration code goes here

// Define your tool functions
function myToolFunction(params) {
  try {
    // Access parameters
    const paramValue = params.paramName;
    const optionalValue = params.optionalParam || 42; // Default if not provided
    
    // Perform the tool's functionality
    const result = {
      // Your result data
    };
    
    // Return the result directly
    return result;
  } catch (error) {
    // Throw errors to indicate failures
    throw new Error(error.message);
  }
}

// Register tools using connect.tools.register
connect.tools.register('toolName', myToolFunction);

3. Tool Function Structure

Each tool function should follow this structure:

function toolName(params) {
  // 1. Access parameters from the params object
  // 2. Perform the tool's functionality
  // 3. Return the result or throw an error
  
  // Success case:
  return resultObject;
  
  // Error case:
  throw new Error("Error message");
}

Your tool functions can also be async and return Promises:

async function asyncToolName(params) {
  // Perform async operations
  const result = await someAsyncOperation(params);
  return result;
}

Example Integration

Here's a simple example of a weather integration:

integration.json

{
  "id": "weather",
  "name": "Weather Integration",
  "description": "Get weather information for any location",
  "version": "1.0.0",
  "author": "Example Developer",
  "publishedAt": "2024-03-14",
  "tools": [
    {
      "name": "getCurrentWeather",
      "description": "Get the current weather for a specific location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name or coordinates (e.g., 'Paris' or '48.8566,2.3522')"
          },
          "units": {
            "type": "string",
            "description": "Temperature units (celsius or fahrenheit)",
            "enum": ["celsius", "fahrenheit"],
            "default": "celsius"
          }
        },
        "required": ["location"]
      }
    }
  ]
}

main.js (or index.js)

// Weather Integration using OpenWeatherMap API
const API_KEY = "your-api-key";
const BASE_URL = "https://api.openweathermap.org/data/2.5";

// Helper function to convert kelvin to celsius/fahrenheit
function convertTemp(kelvin, units) {
  if (units === "fahrenheit") {
    return Math.floor((kelvin - 273.15) * 9 / 5 + 32);
  }
  return Math.floor(kelvin - 273.15);
}

// Helper function to make API requests
async function makeRequest(endpoint, params) {
  params.appid = API_KEY;
  const query = Object.entries(params)
    .map(([key, value]) => `${key}=${value}`)
    .join('&');
  
  const url = `${BASE_URL}${endpoint}?${query}`;
  const response = await fetch(url);
  return await response.json();
}

// Get current weather
async function getCurrentWeather(params) {
  try {
    const data = await makeRequest("/weather", {
      q: params.location,
      units: "standard"
    });
    
    return {
      temperature: convertTemp(data.main.temp, params.units || "celsius"),
      humidity: data.main.humidity,
      description: data.weather[0].description,
      location: {
        name: data.name,
        country: data.sys.country
      }
    };
  } catch (error) {
    throw new Error("Failed to fetch weather data: " + error.message);
  }
}

// Register the tool
connect.tools.register('getCurrentWeather', getCurrentWeather);

Testing Your Integration

To test your integration locally:

1. Create a directory for your integration in the examples/integrations/ directory
2. Add your integration.json and either main.js or index.js files
3. In the browser, go to the settings page and upload your integration files

Best Practices

1. Always handle errors gracefully and throw meaningful error messages
2. Use descriptive names for your tools and parameters
3. Document your tools thoroughly in the integration.json file
4. Keep your tools focused on specific tasks
5. Use standard browser APIs for network requests and other functionality
6. Use async/await for asynchronous operations
7. Make sure all tools defined in your integration.json are registered with connect.tools.register
8. Ensure the tool names in connect.tools.register match exactly with those in integration.json