{"id":27618,"library":"bolddesk-app-framework-sdk","title":"BoldDesk App Framework SDK","description":"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.","status":"active","version":"1.0.29","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","bolddesk","apps","framework","sdk","node"],"install":[{"cmd":"npm install bolddesk-app-framework-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add bolddesk-app-framework-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add bolddesk-app-framework-sdk","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required by package.json engines field (>=18)","package":"node","optional":false}],"imports":[{"note":"Package is ESM-only; CommonJS require will fail. Use named import for default export.","wrong":"const BAFClient = require('bolddesk-app-framework-sdk')","symbol":"BAFClient","correct":"import BAFClient from 'bolddesk-app-framework-sdk'"},{"note":"Do not use 'new'. Use static init() method which may or may not accept a callback.","wrong":"const client = new BAFClient()","symbol":"BAFClient (constructor)","correct":"const client = BAFClient.init(callback)"},{"note":"Argument is a string path, not an array. Multiple fields are passed as separate string arguments.","wrong":"client.get(['ticket.subject']).then(...)","symbol":"client.get","correct":"client.get('ticket.subject').then(data => ...)"},{"note":"Uses custom event methods, not DOM EventTarget API.","wrong":"client.addEventListener('ticket.updated', handler)","symbol":"client.on","correct":"client.on('ticket.updated', handler)"}],"quickstart":{"code":"import BAFClient from 'bolddesk-app-framework-sdk';\n\nconst client = BAFClient.init((context) => {\n  console.log('App initialized!');\n  console.log('User:', context.user.name);\n});\n\n// Get data\nclient.get('ticket.subject', 'ticket.description').then(data => {\n  console.log('Ticket subject:', data['ticket.subject']);\n  console.log('Ticket description:', data['ticket.description']);\n});\n\n// Listen to events\nconst handler = (ticket) => {\n  console.log('Ticket updated:', ticket);\n};\nclient.on('ticket.updated', handler);\n\n// Invoke action\nclient.invoke('notification.show', {\n  type: 'success',\n  message: 'Operation completed'\n});\n\n// HTTP request via proxy\nclient.request({\n  url: 'https://api.example.com/data',\n  method: 'GET'\n}).then(response => console.log(response));","lang":"javascript","description":"Shows initialization, data access, event handling, action invocation, and HTTP request proxy."},"warnings":[{"fix":"Upgrade Node.js to v18 or later.","message":"Node.js >=18 is required. Running on older versions will cause syntax/runtime errors.","severity":"breaking","affected_versions":"<18"},{"fix":"Always provide a callback to init() to ensure the client object is fully initialized.","message":"init() may return undefined if called without a callback? Check documentation; usage with callback is recommended.","severity":"gotcha","affected_versions":">=1.0.0 <=1.0.29"},{"fix":"Replace new BAFClient() with BAFClient.init()","message":"Do not use new BAFClient(). Use BAFClient.init() static factory method.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Change require() to import or use import() inside an async function.","message":"Using require() will fail as package is ESM-only. Use import or dynamic import().","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Deploy the app within BoldDesk using the manifest system.","message":"The SDK must be used inside an iframe embedded in BoldDesk. It will not work standalone (no host to communicate with).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use BAFClient.init() instead.","cause":"Using 'new BAFClient()' incorrectly","error":"TypeError: BAFClient is not a constructor"},{"fix":"Use dynamic import() or convert project to ESM.","cause":"Using CommonJS require() for an ESM-only package","error":"ERR_REQUIRE_ESM: require() of ES Module"},{"fix":"Ensure client is initialized: call get() inside init callback or after promise resolves if init returns a promise.","cause":"Called get() before init() completed without callback","error":"TypeError: client.get is not a function"},{"fix":"Add import BAFClient from 'bolddesk-app-framework-sdk' or include the script tag with correct path.","cause":"Missing import or script include","error":"ReferenceError: BAFClient is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}