​
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 npm downloads

​
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.

​
Further Reading

  • BRX API Reference
  • [Core Concepts: BRK](/docs/Core Concepts/BRK)
  • [Core Concepts: BRX Client](/docs/Core Concepts/BRXClient)
  • [Core Concepts: Composability](/docs/Core Concepts/Composability)