{"id":15642,"library":"helpdesk-app-framework-sdk","title":"HelpDesk App Framework SDK","description":"The HelpDesk App Framework (BAF) SDK, currently at version 1.0.16, is a JavaScript library designed to streamline cross-frame communication for applications integrated into the HelpDesk helpdesk platform. It provides a unified interface for apps running within iframes to interact seamlessly with the host framework. Key capabilities include secure data access (retrieving and updating ticket, contact, and chat information), robust event handling for platform events, managing app instances, and accessing runtime context and metadata. This SDK primarily targets developers building custom applications that need to embed and interact deeply within the HelpDesk ecosystem, simplifying complex cross-origin communication patterns.","status":"active","version":"1.0.16","language":"javascript","source_language":"en","source_url":"git://github.com/bolddesk/helpdesk-app-framework-sdk","tags":["javascript","desk","apps","framework","sdk","helpdesk"],"install":[{"cmd":"npm install helpdesk-app-framework-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add helpdesk-app-framework-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add helpdesk-app-framework-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The SDK is primarily designed for ESM environments, especially given the `engines.node` requirement `>=18`. While a global `BAFClient` is available when loaded via `<script>`, direct Node usage typically prefers ESM.","wrong":"const BAFClient = require('helpdesk-app-framework-sdk');","symbol":"BAFClient","correct":"import BAFClient from 'helpdesk-app-framework-sdk';"}],"quickstart":{"code":"import BAFClient from 'helpdesk-app-framework-sdk';\n\nconst client = BAFClient.init((context) => {\n  console.log('App initialized and ready!');\n  console.log('Current Module:', context.module);       // E.g., 'ticket', 'contact', 'chat'\n  console.log('Object ID:', context.objectId);          // ID of the current object being viewed\n  console.log('User Name:', context.user.name);\n  console.log('User Email:', client.context.getUserEmail()); // Access context details directly from client instance\n\n  // Example: Fetching ticket subject after initialization\n  client.get('ticket.subject').then(data => {\n    console.log('Ticket Subject:', data['ticket.subject']);\n  }).catch(error => {\n    console.error('Failed to get ticket subject:', error);\n  });\n});","lang":"typescript","description":"Initializes the BAF SDK, logs basic context information, and demonstrates fetching data after successful initialization."},"warnings":[{"fix":"Always use `npm install helpdesk-app-framework-sdk` for installation.","message":"The package name on npm is `helpdesk-app-framework-sdk` (kebab-case), but the `npm install` command shown in the README is `npm install helpdesk_app_framework_sdk` (snake_case). Using the incorrect package name will result in installation failure.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your application is embedded as an iframe within the official HelpDesk app framework. Do not run it standalone for full functionality.","message":"This SDK is designed for integration within the HelpDesk app framework's iframed environment. Attempting to use it outside of this specific host context will lead to initialization failures and communication errors, as it relies on specific parent-frame messaging protocols.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always chain `.then()` and `.catch()` to Promise-returning methods or use `await` inside an `async` function.","message":"The SDK relies heavily on asynchronous operations, especially for data access (`client.get()`). Developers must handle Promises correctly with `.then().catch()` or `async/await` to ensure data is retrieved and errors are managed gracefully.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For Node.js projects, ensure `type: 'module'` is set in `package.json` or use `.mjs` extensions. For older Node versions, consider a polyfill or stick to browser-only usage.","message":"The `engines.node` requirement of `>=18` indicates a preference for modern Node.js environments and likely ESM usage. While browser usage via `<script>` tag is supported, developers targeting Node.js should configure their projects for ESM compatibility.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `<script src=\"path/to/baf_sdk.min.js\"></script>` is loaded before your app script in HTML, or `import BAFClient from 'helpdesk-app-framework-sdk';` is at the top of your module.","cause":"The SDK script (or ESM module) was not correctly loaded or imported before `BAFClient.init()` was called.","error":"BAFClient is not defined"},{"fix":"Wrap asynchronous calls in `async/await` or chain `.then()` and `.catch()` to handle the Promise resolution.","cause":"Attempted to use asynchronous API methods (like `client.get()`) without correctly handling the returned Promise object.","error":"TypeError: client.get(...).then is not a function"},{"fix":"Use the correct npm package name: `npm install helpdesk-app-framework-sdk`.","cause":"Used the incorrect package name `helpdesk_app_framework_sdk` (snake_case) instead of `helpdesk-app-framework-sdk` (kebab-case) during installation.","error":"npm ERR! code E404 npm ERR! 404 Not Found - GET https://registry.npmjs.org/helpdesk_app_framework_sdk"},{"fix":"Verify that your app is properly embedded as an iframe within the HelpDesk platform and that the host page's origin is allowed for communication.","cause":"The SDK could not establish a secure connection with the parent HelpDesk App Framework, likely due to the app not being embedded correctly or origin mismatch.","error":"Failed to initialize HelpDesk SDK: Parent frame not found or invalid origin."}],"ecosystem":"npm"}