Skip to main content

​
Node / TypeScript SDK

The @feral/sdk package provides a TypeScript client for the FERAL Brain API, plugin helpers, and a hardware node class. 
npm install @feral/sdk

​
FeralClient

import { FeralClient } from '@feral/sdk';

const client = new FeralClient('http://localhost:9090');

// Health check
const health = await client.health();
console.log(health.version);

// Chat
const reply = await client.chat('What can you do?');
console.log(reply);

// Dashboard
const dashboard = await client.getDashboard();
console.log(dashboard.skills_count);

// System info
const info = await client.getSystemInfo();

// Skills
const skills = await client.listSkills();

// Memory
const results = await client.searchMemory('project deadlines');
await client.createNote('Ship v1.3 by Friday', ['work']);

​
Constructor

new FeralClient(baseUrl?: string)  // default: 'http://localhost:9090'

​
Methods

MethodReturnDescription
health()Promise<{ status, version }>Brain health status
getDashboard()Promise<DashboardData>Aggregated dashboard data
getSystemInfo()Promise<SystemInfo>Version, memory stats, provider info
chat(message)Promise<string>Send a message via WebSocket, get the response
listSkills()Promise<Array<Record>>All registered skills
searchMemory(query, limit?)Promise<Array<Record>>Search the agent’s memory
createNote(content, tags?)Promise<Record>Create a persistent memory note

​
definePlugin

Create plugins using the definePlugin helper: 
import { definePlugin } from '@feral/sdk';

const weatherPlugin = definePlugin({
  name: 'weather',
  description: 'Real-time weather data',
  version: '0.1.0',
  tools: [
    {
      name: 'current',
      description: 'Get current weather for a city',
      parameters: {
        city: { type: 'string', description: 'City name', required: true },
      },
      handler: async ({ city }) => {
        return { city, temp_f: 72, condition: 'sunny' };
      },
    },
  ],
});

​
PluginDefinition

interface PluginDefinition {
  name: string;
  description: string;
  version?: string;
  tools: ToolDefinition[];
}

interface ToolDefinition {
  name: string;
  description: string;
  parameters?: Record<string, {
    type: string;
    description?: string;
    required?: boolean;
  }>;
  handler: (args: Record<string, unknown>) => Promise<unknown>;
}

​
FeralNode

Connect hardware or virtual devices to the Brain: 
import { FeralNode } from '@feral/sdk';

const node = new FeralNode({
  nodeId: 'my-sensor',
  nodeType: 'sensor',
  capabilities: ['temperature', 'humidity'],
  brainUrl: 'ws://localhost:9090/v1/node',
});

await node.connect();

setInterval(async () => {
  await node.sendTelemetry({
    temperature_c: 22.5,
    humidity_pct: 45,
  });
}, 5000);

node.onCommand(async (action, params) => {
  console.log('Received command:', action, params);
  return { ok: true };
});

​
NodeConfig

interface NodeConfig {
  nodeId: string;
  nodeType: string;
  capabilities: string[];
  brainUrl?: string;  // default: 'ws://localhost:9090/v1/node'
  apiKey?: string;     // default: 'dev-secret-key'
}

​
Types

The SDK exports the full set of wire-protocol types: 
import type {
  FeralMessage,
  TextCommand,
  TextResponse,
  StreamDelta,
  SkillManifest,
  SkillEndpoint,
  HUPAction,
  HUPTelemetry,
  DashboardData,
  SystemInfo,
} from '@feral/sdk';
See the Python SDK for the equivalent Python API.