​

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.

​

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)