BoldDesk App Framework SDK

1.0.29 verified Sat May 09 auth: no javascript

The BoldDesk App Framework (BAF) SDK is a lightweight JavaScript library (v1.0.29) that enables seamless communication between iframed applications and the BoldDesk helpdesk platform. It provides methods for data access (get/set), event handling (on/off), invoking platform actions, and making HTTP requests through the host proxy. Unlike generic postMessage wrappers, it is purpose-built for BoldDesk app development with a built-in manifest system for widget configuration and domain trust. Node.js >=18 required.

Common errors

error TypeError: BAFClient is not a constructor ↓

cause Using 'new BAFClient()' incorrectly

fix

Use BAFClient.init() instead.

error ERR_REQUIRE_ESM: require() of ES Module ↓

cause Using CommonJS require() for an ESM-only package

fix

Use dynamic import() or convert project to ESM.

error TypeError: client.get is not a function ↓

cause Called get() before init() completed without callback

fix

Ensure client is initialized: call get() inside init callback or after promise resolves if init returns a promise.

error ReferenceError: BAFClient is not defined ↓

cause Missing import or script include

fix

Add import BAFClient from 'bolddesk-app-framework-sdk' or include the script tag with correct path.

Warnings

breaking Node.js >=18 is required. Running on older versions will cause syntax/runtime errors. ↓

fix Upgrade Node.js to v18 or later.

gotcha init() may return undefined if called without a callback? Check documentation; usage with callback is recommended. ↓

fix Always provide a callback to init() to ensure the client object is fully initialized.

gotcha Do not use new BAFClient(). Use BAFClient.init() static factory method. ↓

fix Replace new BAFClient() with BAFClient.init()

gotcha Using require() will fail as package is ESM-only. Use import or dynamic import(). ↓

fix Change require() to import or use import() inside an async function.

gotcha The SDK must be used inside an iframe embedded in BoldDesk. It will not work standalone (no host to communicate with). ↓

fix Deploy the app within BoldDesk using the manifest system.

Install

npm install bolddesk-app-framework-sdk

yarn add bolddesk-app-framework-sdk

pnpm add bolddesk-app-framework-sdk

Imports

BAFClient

wrong

const BAFClient = require('bolddesk-app-framework-sdk')

correct

import BAFClient from 'bolddesk-app-framework-sdk'

Package is ESM-only; CommonJS require will fail. Use named import for default export.

BAFClient (constructor)
wrong
```
const client = new BAFClient()
```
correct
```
const client = BAFClient.init(callback)
```
Do not use 'new'. Use static init() method which may or may not accept a callback.
client.get
wrong
```
client.get(['ticket.subject']).then(...)
```
correct
```
client.get('ticket.subject').then(data => ...)
```
Argument is a string path, not an array. Multiple fields are passed as separate string arguments.

client.on

wrong

client.addEventListener('ticket.updated', handler)

correct

client.on('ticket.updated', handler)

Uses custom event methods, not DOM EventTarget API.

Quickstart

Shows initialization, data access, event handling, action invocation, and HTTP request proxy.

import BAFClient from 'bolddesk-app-framework-sdk';

const client = BAFClient.init((context) => {
  console.log('App initialized!');
  console.log('User:', context.user.name);
});

// Get data
client.get('ticket.subject', 'ticket.description').then(data => {
  console.log('Ticket subject:', data['ticket.subject']);
  console.log('Ticket description:', data['ticket.description']);
});

// Listen to events
const handler = (ticket) => {
  console.log('Ticket updated:', ticket);
};
client.on('ticket.updated', handler);

// Invoke action
client.invoke('notification.show', {
  type: 'success',
  message: 'Operation completed'
});

// HTTP request via proxy
client.request({
  url: 'https://api.example.com/data',
  method: 'GET'
}).then(response => console.log(response));