Node.js SDK

Use the Node.js SDK to submit actions and run governed fetch/exec from your JavaScript or TypeScript agents.

Installation

npm

npm

npm

Setup

Set your API URL and key:

export FARAMESH_URL="https://api.faramesh.dev"  # or your Horizon URL
export FARAMESH_API_KEY="your-api-key"        # from the dashboard

export FARAMESH_URL="https://api.faramesh.dev"  # or your Horizon URL
export FARAMESH_API_KEY="your-api-key"        # from the dashboard

export FARAMESH_URL="https://api.faramesh.dev"  # or your Horizon URL
export FARAMESH_API_KEY="your-api-key"        # from the dashboard

Or pass config when calling:

const { submitAction } = require("@faramesh/sdk");

const action = await submitAction(
  { agentId: "my-agent", tool: "shell", operation: "exec", params: { cmd: "ls" } },
  { apiBase: "https://api.faramesh.io", apiKey: "your-key" }
);

const { submitAction } = require("@faramesh/sdk");

const action = await submitAction(
  { agentId: "my-agent", tool: "shell", operation: "exec", params: { cmd: "ls" } },
  { apiBase: "https://api.faramesh.io", apiKey: "your-key" }
);

const { submitAction } = require("@faramesh/sdk");

const action = await submitAction(
  { agentId: "my-agent", tool: "shell", operation: "exec", params: { cmd: "ls" } },
  { apiBase: "https://api.faramesh.io", apiKey: "your-key" }
);

Submit an action

const { submitAction } = require("@faramesh/sdk");

const action = await submitAction({
  agentId: "my-agent",
  tool: "shell",
  operation: "exec",
  params: { cmd: "echo hello" }
});

console.log(action.status, action.decision);

const { submitAction } = require("@faramesh/sdk");

const action = await submitAction({
  agentId: "my-agent",
  tool: "shell",
  operation: "exec",
  params: { cmd: "echo hello" }
});

console.log(action.status, action.decision);

const { submitAction } = require("@faramesh/sdk");

const action = await submitAction({
  agentId: "my-agent",
  tool: "shell",
  operation: "exec",
  params: { cmd: "echo hello" }
});

console.log(action.status, action.decision);

Governed fetch

governedFetch checks policy before running HTTP requests. If the policy allows, it runs; if it requires approval, it throws PendingAction.

const { governedFetch } = require("@faramesh/sdk");

const response = await governedFetch("https://api.example.com/data", {
  agentId: "my-agent",
  method: "GET"
});

const { governedFetch } = require("@faramesh/sdk");

const response = await governedFetch("https://api.example.com/data", {
  agentId: "my-agent",
  method: "GET"
});

const { governedFetch } = require("@faramesh/sdk");

const response = await governedFetch("https://api.example.com/data", {
  agentId: "my-agent",
  method: "GET"
});

Governed exec

governedExec checks policy before running shell commands.

const { governedExec } = require("@faramesh/sdk");

const result = await governedExec("npm install", { agentId: "my-agent" });

const { governedExec } = require("@faramesh/sdk");

const result = await governedExec("npm install", { agentId: "my-agent" });

const { governedExec } = require("@faramesh/sdk");

const result = await governedExec("npm install", { agentId: "my-agent" });

Pending approval

When the policy requires approval, the SDK throws PendingAction. Handle it to surface the approval flow:

const { submitAction, PendingAction } = require("@faramesh/sdk");

try {
  const action = await submitAction({ ... });
} catch (err) {
  if (err instanceof PendingAction) {
    console.log("Action pending approval:", err.actionId, err.token);
    // Notify the user or poll until approved
  }
}

const { submitAction, PendingAction } = require("@faramesh/sdk");

try {
  const action = await submitAction({ ... });
} catch (err) {
  if (err instanceof PendingAction) {
    console.log("Action pending approval:", err.actionId, err.token);
    // Notify the user or poll until approved
  }
}

const { submitAction, PendingAction } = require("@faramesh/sdk");

try {
  const action = await submitAction({ ... });
} catch (err) {
  if (err instanceof PendingAction) {
    console.log("Action pending approval:", err.actionId, err.token);
    // Notify the user or poll until approved
  }
}

Table of content