{"id":13201,"library":"freshdesk-api","title":"Freshdesk API Client for Node.js","description":"freshdesk-api is a Node.js wrapper for the Freshdesk v2 API, providing a convenient and typed interface for interacting with Freshdesk services. The current stable version is 3.1.0. The package has an active release cadence, with significant updates and new features being added regularly, alongside dependency maintenance and bug fixes. It differentiates itself by offering full TypeScript support and leveraging `undici` for efficient HTTP requests, though note that attachment handling still relies on `form-data`. This client is designed for server-side Node.js applications that need to integrate with Freshdesk for ticket management, contact synchronization, and other API operations, offering a more modern alternative to older v1 API clients.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/arjunkomath/node-freshdesk-api","tags":["javascript","freshdesk","v1","v2","api","node","client","typescript"],"install":[{"cmd":"npm install freshdesk-api","lang":"bash","label":"npm"},{"cmd":"yarn add freshdesk-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add freshdesk-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The main Freshdesk API client class is exported as the default module export.","wrong":"import { Freshdesk } from 'freshdesk-api'","symbol":"Freshdesk","correct":"import Freshdesk from 'freshdesk-api'"},{"note":"FreshdeskError is a static property of the default Freshdesk class, useful for `instanceof` checks in catch blocks for specific API errors.","wrong":"import { FreshdeskError } from 'freshdesk-api'","symbol":"FreshdeskError","correct":"import Freshdesk from 'freshdesk-api'; /* then use Freshdesk.FreshdeskError */"},{"note":"Import types (interfaces, enums) separately using `import type` for clarity and to enable tree-shaking in TypeScript projects.","symbol":"Ticket, FreshdeskOptions","correct":"import type { Ticket, FreshdeskOptions } from 'freshdesk-api'"}],"quickstart":{"code":"import Freshdesk from 'freshdesk-api';\n\n// Configure Freshdesk API client using environment variables for security\nconst domain = process.env.FRESHDESK_DOMAIN ?? 'https://yourdomain.freshdesk.com';\nconst apiKey = process.env.FRESHDESK_API_KEY ?? 'yourApiKey';\n\n// Warn if using placeholder credentials\nif (apiKey === 'yourApiKey' || domain === 'https://yourdomain.freshdesk.com') {\n  console.warn(\"WARNING: Please set FRESHDESK_DOMAIN and FRESHDESK_API_KEY environment variables.\");\n  console.warn(\"Using placeholder credentials which will likely result in authentication errors.\");\n}\n\nconst freshdesk = new Freshdesk(domain, apiKey);\n\nasync function createAndFetchTicket() {\n  try {\n    const ticketData = {\n      name: \"New Customer Inquiry\",\n      email: \"inquiry@example.com\",\n      subject: \"Problem with recent order #12345\",\n      description: \"The items in my order were incorrect.\",\n      status: 2, // Open\n      priority: 1  // Low\n    };\n\n    console.log(\"Attempting to create a new ticket...\");\n    const newTicket = await freshdesk.createTicket(ticketData);\n    console.log(\"Ticket created successfully:\", newTicket);\n\n    console.log(`Fetching ticket ${newTicket.id}...`);\n    const fetchedTicket = await freshdesk.getTicket(newTicket.id);\n    console.log(\"Fetched ticket details:\", fetchedTicket);\n\n  } catch (error: any) {\n    console.error(\"An error occurred:\", error.message);\n    if (error.response?.status) {\n        console.error(\"HTTP Status:\", error.response.status);\n        console.error(\"Response data:\", error.response.data);\n    }\n    if (error instanceof Freshdesk.FreshdeskError) {\n        console.error(\"Freshdesk API specific error details:\", error.extra);\n    }\n  }\n}\n\ncreateAndFetchTicket();","lang":"typescript","description":"This quickstart initializes the Freshdesk API client using environment variables and demonstrates how to create a new ticket and then fetch its details, including robust error handling."},"warnings":[{"fix":"Migrate from `bluebird`'s promisified methods (e.g., `getTicketAsync`) to native async/await syntax or explicit Promise wrapping for API calls (e.g., `await freshdesk.getTicket(...)`).","message":"Version 3.0.0 removed the internal dependency and integration with `bluebird` for promisification. Users who relied on methods like `freshdesk.getTicketAsync` for promisified calls will need to update their code to use native async/await or standard Promise wrappers.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review any custom HTTP client configurations or assumptions made about the underlying `request` library. Most direct API calls should remain compatible, but behavior for edge cases or advanced HTTP options might differ.","message":"In version 2.13.0, the underlying HTTP client library was replaced from `request` to `axios`, and subsequently to `undici`. While efforts were made to maintain API compatibility, users relying on specific behaviors or configuration options of the previous `request` library might encounter subtle breaking changes.","severity":"breaking","affected_versions":">=2.13.0"},{"fix":"When testing or mocking `freshdesk-api`, use `Undici`'s built-in mocking functionality for most requests. For form-data/attachment requests, `nock` remains a viable option. Alternatively, use a client-agnostic mock server.","message":"The package uses `Undici` as its HTTP client (since v2.13.0), which is not compatible with `nock` for mocking network requests. Only requests involving `form-data` (e.g., attachments) still use Node.js `net` module and can be mocked with `nock`.","severity":"gotcha","affected_versions":">=2.13.0"},{"fix":"Upgrade to `freshdesk-api` version 3.1.0 or newer, which includes a fix to correctly handle rate limit responses and return the `retry-after` header in `FreshdeskError`.","message":"Older versions of the client (prior to v3.1.0) could return an 'unexpected end of JSON input' error when Freshdesk API rate limits were exceeded, due to an incomplete JSON response from the server.","severity":"gotcha","affected_versions":"<3.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade to `freshdesk-api` version 3.1.0 or newer. Ensure your API calls respect Freshdesk's rate limits. Check the `FreshdeskError` object for `retry-after` details.","cause":"This error often occurs in older versions when the Freshdesk API returns an incomplete JSON response, typically due to rate limiting or an internal server error.","error":"Error: unexpected end of JSON input"},{"fix":"Double-check your `FRESHDESK_DOMAIN` and `FRESHDESK_API_KEY` environment variables or configuration. Ensure the API key has the necessary permissions for the operations being performed.","cause":"The API key or domain provided for authentication is incorrect or unauthorized.","error":"Error: Request failed with status code 401"},{"fix":"For ESM, use `import Freshdesk from 'freshdesk-api';`. For CommonJS, use `const Freshdesk = require('freshdesk-api');`. Ensure you are not destructuring the `Freshdesk` class from the import.","cause":"This usually happens when `Freshdesk` is imported incorrectly as a named import instead of a default import, or when an older CommonJS `require` call is used in an ESM context without proper interoperability.","error":"TypeError: freshdesk.createTicket is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}