Agemo AI - Codewords Client

A client for interacting with Codewords runtime, designed to easily plug into frontend server-side environments.

Installation

Install the package using npm:

npm install @agemoai/codewords-client

Usage

Importing the Client

First, import the necessary classes and types from the package:

import { AuthDataType, AuthData, cwFunctionFactory } from "@agemoai/codewords-client";

Authentication

Create an AuthData object to authenticate and authorize the user. Note: The API key is a secret that should not be shared. It should be accessed via an environment variable. Obtain your API key from the function's CodeWords Run page.

const authData: AuthData = {
  type: AuthDataType.API_KEY,
  data: "your-api-key", // Use environment variable for the API key (keep this a secret)
};

Creating a CWFunction Client

Use the cwFunctionFactory to create a CWFunction client. Note: IDs and version can be obtained on CodeWords Run page.

const functionId = "your-function-id"; // Recommend using environment variable for function ID
const version = "your-function-version"; // Recommend using environment variable for function version
const runnerId = "your-runner-id"; // Recommend using environment variable for runner ID
const verbose = false; // For detailed logs

const cwFunction = await cwFunctionFactory(functionId, version, runnerId, authData, verbose);

Running a Function

To run a function, use the run method of the CWFunction class. This method takes inputs and a callback function to handle WebSocket messages.

const inputs = {
  input1: "value1", // Replace with actual inputs expected by your function
  input2: "value2", // Replace with actual inputs expected by your function
  // Add other inputs as required by your function
};

cwFunction.run(inputs, (response) => {
  if (response.type === "run_complete") {
    console.log("Run completed successfully:", response);
    
    // Access the outputs based on the output names specified in your function
    const output1 = response.outputs.output1;
    const output2 = response.outputs.output2;
    console.log("Output 1:", output1);
    console.log("Output 2:", output2);
  } else {
    console.error("Run encountered an error:", response);
  }
}).then((ws) => {
  console.log("WebSocket connection established:", ws);
}).catch((error) => {
  console.error("Error running function:", error);
});

Handling WebSocket Messages

The run method uses a WebSocket connection to communicate with the runtime. The callback function will receive messages from the WebSocket. Here are the types of messages you need to handle:

• run_complete: Indicates that the function run has completed successfully.
• run_error: Indicates that there was an error during the function run.
• function_missing: Indicates that the specified function could not be found.
• block_error: Indicates that there was an error in one of the function blocks.

Environment Variables

The codewords-client package requires the following environment variables to be set:

• NEXT_PUBLIC_CWR_WS_URL: The WebSocket URL for the runtime.
• NEXT_PUBLIC_CWR_HTTPS_URL: The HTTPS URL for the runtime.

In a production environment, you should set these variables to the provided values to access CodeWords runtime:

export NEXT_PUBLIC_CWR_WS_URL="wss://d21x5wziv7.execute-api.eu-west-2.amazonaws.com/prod/"
export NEXT_PUBLIC_CWR_HTTPS_URL="https://na9ywpljw9.execute-api.eu-west-2.amazonaws.com/prod/runtime"

In a development environment, you can set these variables in a .env file or directly in your shell.

Complete Example

Here is a complete example of how to use the @agemoai/codewords-client to run a function:

import { AuthDataType, AuthData, cwFunctionFactory } from "@agemoai/codewords-client";

const authData: AuthData = {
  type: AuthDataType.API_KEY,
  data: process.env.CODEWORDS_API_KEY, // Use environment variable for the API key
};

const functionId = process.env.CODEWORDS_FUNCTION_ID; // Recommend using environment variable for function ID
const version = process.env.CODEWORDS_FUNCTION_VERSION; // Recommend using environment variable for function version
const runnerId = process.env.CODEWORDS_RUNNER_ID; // Recommend using environment variable for runner ID
const verbose = false;

async function runFunction() {
  try {
    const cwFunction = await cwFunctionFactory(functionId, version, runnerId, authData, verbose);

    const inputs = {
      input1: "value1", // Replace with actual inputs expected by your function
      input2: "value2", // Replace with actual inputs expected by your function
      // Add other inputs as required by your function
    };

    cwFunction.run(inputs, (response) => {
      if (response.type === "run_complete") {
        console.log("Run completed successfully:", response);
        
        // Access the outputs based on the output names specified in your function
        const output1 = response.outputs.output1;
        const output2 = response.outputs.output2;
        console.log("Output 1:", output1);
        console.log("Output 2:", output2);
      } else {
        console.error("Run encountered an error:", response);
      }
    }).then((ws) => {
      console.log("WebSocket connection established:", ws);
    }).catch((error) => {
      console.error("Error running function:", error);
    });
  } catch (error) {
    console.error("Error creating CWFunction client:", error);
  }
}

runFunction();

License

This project is licensed under the MIT License - see the LICENSE file for details.