Node.js SDK - Faramesh Documentation

Installation

Install from npm or use from source

npm install faracore
# or
npm install @faramesh/sdk

Basic Usage

Import and use the SDK:

import { submitAction, getAction, Config } from "faracore";

const config = new Config({ 
  apiBase: "http://127.0.0.1:8000", 
  agentId: "devops" 
});

const action = await submitAction(
  { 
    agentId: "devops", 
    tool: "github.merge", 
    operation: "merge", 
    params: { pr: 17 } 
  },
  config
);

const fetched = await getAction(action.id, config);
console.log(fetched.status);

Programmatic Configuration

Configure the SDK with a Config object

import { Config } from "faracore";

const config = new Config({
  apiBase: "http://localhost:8000",
  agentId: "my-agent",
  authToken: "your-token",
  timeout: 10000,
  maxRetries: 3,
  retryBackoffFactor: 0.5
});

Submitting Actions

The submitAction function sends an action for evaluation:

const action = await submitAction(
  {
    agentId: "my-agent",
    tool: "shell",
    operation: "run",
    params: { cmd: "ls -la" },
    context: { environment: "production" }
  },
  config
);

// Response includes:
// - id: Action ID
// - status: Current status
// - decision: Policy decision
// - reason: Policy reason
// - approval_token: Token for approval (if require_approval)

Getting Action Status

Check the status of an action:

const action = await getAction(actionId, config);
console.log('Status:', action.status);
console.log('Decision:', action.decision);

Listing Actions

Query actions with filters:

import { listActions } from "faracore";

// List all actions
const actions = await listActions(config);

// Filter by status
const pending = await listActions(config, { status: "pending_approval" });

// Filter by agent
const agentActions = await listActions(config, { agentId: "my-agent" });

// Filter by tool
const shellActions = await listActions(config, { tool: "shell" });

Error Handling

The SDK provides custom error classes for robust error handling

import {
  GovernorError,
  GovernorTimeoutError,
  GovernorAuthError,
  GovernorConnectionError,
  PendingAction
} from "faracore";

try {
  const action = await submitAction(...);
} catch (error) {
  if (error instanceof GovernorAuthError) {
    console.error("Authentication failed:", error.message);
  } else if (error instanceof GovernorTimeoutError) {
    console.error("Request timed out:", error.message);
  } else if (error instanceof GovernorConnectionError) {
    console.error("Connection failed:", error.message);
  } else if (error instanceof PendingAction) {
    console.log("Action requires approval:", error.id);
    console.log("Approval token:", error.approval_token);
  } else {
    console.error("Error:", error.message);
  }
}

Complete Example

A full working example showing the complete async workflow

import { submitAction, getAction, Config } from "faracore";

async function main() {
  // Initialize config
  const config = new Config({ 
    apiBase: "http://127.0.0.1:8000", 
    agentId: "test-agent" 
  });

  // Submit an action
  const response = await submitAction(
    {
      agentId: "test-agent",
      tool: "shell",
      operation: "run",
      params: { cmd: "echo 'Hello FaraCore'" }
    },
    config
  );

  console.log('Action ID:', response.id);
  console.log('Status:', response.status);

  // If approval is required, wait for approval
  if (response.status === 'pending_approval') {
    console.log("Action requires approval. Waiting...");
    // In production, you might poll or use SSE to wait for approval
  }

  // Check final status
  const action = await getAction(response.id, config);
  console.log('Final status:', action.status);
}

main().catch(console.error);

Node.js SDK Reference