brx-node SDK

The brx-node package is the official Node.js SDK for interacting with the BRX platform. It provides a simple and intuitive interface for creating, managing, and executing BRKs. npm version

Installation

# Using npm
npm install brx-node --save

# Using yarn
yarn add brx-node

# Using pnpm
pnpm add brx-node

Basic Usage

import BRX, { BRK } from 'brx-node';

// Initialize the BRX client with your API key
const brx = new BRX('your-api-key');

// Fetch a BRK schema
const brkSchema = await brx.get('brk-id');

// Initialize a BRK with the schema
const myBrk = new BRK(brkSchema);

// Set input values
myBrk.input['inputField'] = 'input value';

// Execute the BRK
const result = await brx.run(myBrk);
console.log(result);

API Reference

BRX Class

The BRX class is the main entry point for interacting with the BRX platform.

Constructor

constructor(
  accessToken: string,
  options?: {
    use_brx_key?: boolean;
    verbose?: boolean;
    send_local?: boolean;
    force_client?: boolean;
    silent?: boolean;
  }
)

accessToken (required): Your BRX API key
options (optional): Configuration options
- use_brx_key (default: true): Whether to use the BRX API key for authentication
- verbose (default: false): Enable verbose logging
- send_local (default: false): Use local API endpoint (for development)
- force_client (default: false): Force client-side WebSocket
- silent (default: false): Disable welcome message

Methods

get

get(brxID: string): Promise<GetSchemaObject>

Fetches a BRK schema by its ID.

brxID (required): The ID of the BRK to fetch
Returns: A promise that resolves to the BRK schema

run

run(query: BRK, callback?: (message: RunResult) => void): Promise<RunResult[]>

Executes a BRK and returns the results.

query (required): The BRK to execute
callback (optional): A callback function that will be called for each result
Returns: A promise that resolves to an array of results

create

create(modifyRequest: brxModify): Promise<ModifySuccess | ModifyError>

Creates a new BRK.

modifyRequest (required): The BRK creation request
Returns: A promise that resolves to the creation result

update

update(modifyRequest: brxModify): Promise<ModifySuccess | ModifyError>

Updates an existing BRK.

modifyRequest (required): The BRK update request
Returns: A promise that resolves to the update result

delete

delete(modifyRequest: brxModify): Promise<ModifySuccess | ModifyError>

Deletes a BRK.

modifyRequest (required): The BRK deletion request
Returns: A promise that resolves to the deletion result

clone

clone(modifyRequest: brxModify): Promise<ModifySuccess | ModifyError>

Clones a BRK.

modifyRequest (required): The BRK clone request
Returns: A promise that resolves to the clone result

execute

execute(query: BRK | queryStreamRequest, callback?: (message: RunResult) => void): Promise<Array<RunResult>>

Low-level method for executing a BRK. In most cases, you should use run instead.

query (required): The BRK or query stream request to execute
callback (optional): A callback function that will be called for each result
Returns: A promise that resolves to an array of results

modify

modify(modifyRequest: brxModify): Promise<ModifySuccess | ModifyError>

Low-level method for modifying a BRK. In most cases, you should use create, update, delete, or clone instead.

modifyRequest (required): The BRK modification request
Returns: A promise that resolves to the modification result

BRK Class

The BRK class represents a BRK (BRX Knowledge Representation) that can be executed.

Constructor

constructor(BRKSchema?: GetSchemaObject, BRXClient?: BRX)

BRKSchema (optional): The BRK schema
BRXClient (optional): The BRX client to use for execution

Properties

input

input: any

An object containing the input values for the BRK. You can set input values by assigning to properties of this object.

brxQuery

brxQuery: any

The internal representation of the BRK query. You should not modify this directly.

inprogress

inprogress: boolean

Whether the BRK is currently being executed.

Methods

run

run(callback?: (message: RunResult) => void): Promise<RunResult[]>

Executes the BRK using the associated BRX client.

callback (optional): A callback function that will be called for each result
Returns: A promise that resolves to an array of results

updateBRK

updateBRK(verbose?: boolean): Promise<{ brxQuery: any }>

Updates the internal BRK query with the current input values.

verbose (optional): Enable verbose logging
Returns: A promise that resolves to an object containing the updated BRK query

Examples

Creating a BRK

import BRX, { BRK } from 'brx-node';

const brx = new BRX('your-api-key');

// Define the BRK
const createRequest = {
  modifyBrxMode: 'CREATE',
  brx: {
    brxId: 'hello-world-brk',
    brxName: 'Hello World',
    description: 'A simple Hello World BRK',
    prompt: {
      prompt: new Map([
        ['main', 'Hello, {{name}}!']
      ])
    },
    processParams: {
      processType: 0
    },
    dependantBrxIds: new Map([
      ['main_brx_entry_schema', 'hello-world-brk']
    ])
  },
  schema: {
    schemaFields: new Map([
      ['name', {
        fieldValueDataType: 'string',
        fieldValue: ''
      }]
    ]),
    brxName: 'Hello World',
    brxId: 'hello-world-brk'
  }
};

// Create the BRK
const result = await brx.create(createRequest);
console.log('BRK created:', result);

Using a BRK with Dependencies

import BRX, { BRK } from 'brx-node';

const brx = new BRX('your-api-key');

// Fetch the BRK schema
const reportGeneratorSchema = await brx.get('report-generator-brk');

// Initialize the BRK
const reportGenerator = new BRK(reportGeneratorSchema);

// Set input values
reportGenerator.input['data'] = 'Raw data to analyze';
reportGenerator.input['format'] = 'markdown';

// Execute the BRK with a callback for streaming results
const results = [];
await brx.run(reportGenerator, (result) => {
  results.push(result);
  console.log(`Received result from ${result.brxName}`);
});

// Print the final result
console.log('Final report:', results[results.length - 1].brxRes.output);

Error Handling

import BRX, { BRK } from 'brx-node';

const brx = new BRX('your-api-key');

try {
  // Fetch a BRK schema
  const brkSchema = await brx.get('non-existent-brk-id');
  
  // This code will not be reached if the BRK doesn't exist
  const myBrk = new BRK(brkSchema);
  const result = await brx.run(myBrk);
} catch (error) {
  console.error('Error:', error.message);
  
  // Handle specific error types
  if (error.message.includes('Unauthorized')) {
    console.error('Authentication error. Check your API key.');
  } else if (error.message.includes('no permissions')) {
    console.error('You do not have permission to access this BRK.');
  } else {
    console.error('An unexpected error occurred.');
  }
}

Advanced Usage

WebSocket Connections

The BRX client uses WebSockets for real-time communication with the BRX platform. You can customize the WebSocket behavior using the constructor options.

const brx = new BRX('your-api-key', {
  verbose: true,       // Enable verbose logging
  force_client: true,  // Force client-side WebSocket
  send_local: true     // Use local API endpoint
});

Custom Processing

You can customize how BRKs are processed by setting the processType property in the processParams object.

const createRequest = {
  modifyBrxMode: 'CREATE',
  brx: {
    // ...
    processParams: {
      processType: 1 // Custom processing type
    },
    // ...
  },
  // ...
};

Working with Maps

The BRX SDK uses JavaScript Map objects for certain properties. When serializing these objects to JSON, you need to use the mapReplacer function.

import { mapReplacer } from 'brx-node';

const jsonString = JSON.stringify(myObject, mapReplacer);

Similarly, when deserializing JSON to objects with Map properties, you need to use the mapReviver function.

import { mapReviver } from 'brx-node';

const myObject = JSON.parse(jsonString, mapReviver);

Troubleshooting

Common Issues

Authentication Errors: Make sure your API key is correct and has not expired.
Network Errors: Check your internet connection and firewall settings.
Rate Limiting: The BRX API has rate limits. If you’re making too many requests, you may be temporarily blocked.
Invalid BRK IDs: Make sure the BRK IDs you’re using exist and are accessible to your account.

Debugging

You can enable verbose logging to help debug issues:

const brx = new BRX('your-api-key', { verbose: true });

This will log detailed information about WebSocket connections, requests, and responses.

Get Started

Core Concepts

SDK Reference

brx-node SDK

brx-node SDK

Installation

Basic Usage

API Reference

BRX Class

Constructor

Methods

get

run

create

update

delete

clone

execute

modify

BRK Class

Constructor

Properties

input

brxQuery

inprogress

Methods

run

updateBRK

Examples

Creating a BRK

Using a BRK with Dependencies

Error Handling

Advanced Usage

WebSocket Connections

Custom Processing

Working with Maps

Troubleshooting

Common Issues

Debugging

Further Reading

​brx-node SDK

​Installation

​Basic Usage

​API Reference

​BRX Class

​Constructor

​Methods

get

run

create

update

delete

clone

execute

modify

​BRK Class

​Constructor

​Properties

input

brxQuery

inprogress

​Methods

run

updateBRK

​Examples

​Creating a BRK

​Using a BRK with Dependencies

​Error Handling

​Advanced Usage

​WebSocket Connections

​Custom Processing

​Working with Maps

​Troubleshooting

​Common Issues

​Debugging

​Further Reading

brx-node SDK

Installation

Basic Usage

API Reference

BRX Class

Constructor

Methods

BRK Class

Constructor

Properties

Methods

Examples

Creating a BRK

Using a BRK with Dependencies

Error Handling

Advanced Usage

WebSocket Connections

Custom Processing

Working with Maps

Troubleshooting

Common Issues

Debugging

Further Reading