{"id":22608988,"url":"https://github.com/bitfinexcom/bfx-ext-helpdesk-js","last_synced_at":"2026-03-01T06:35:44.392Z","repository":{"id":205963287,"uuid":"715485724","full_name":"bitfinexcom/bfx-ext-helpdesk-js","owner":"bitfinexcom","description":"Bitfinex External Helpdesk Service","archived":false,"fork":false,"pushed_at":"2025-05-13T09:56:43.000Z","size":144,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"1.x","last_synced_at":"2025-05-13T10:41:01.511Z","etag":null,"topics":["api","async","backend","backend-services","bitfinex","grenache","javascript","js","microservice","microservices","node","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitfinexcom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-11-07T08:38:36.000Z","updated_at":"2025-05-13T09:55:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"b4b07369-5713-45b7-8317-44f00e3c8824","html_url":"https://github.com/bitfinexcom/bfx-ext-helpdesk-js","commit_stats":null,"previous_names":["bitfinexcom/bfx-ext-helpdesk-js"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/bitfinexcom/bfx-ext-helpdesk-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitfinexcom%2Fbfx-ext-helpdesk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitfinexcom%2Fbfx-ext-helpdesk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitfinexcom%2Fbfx-ext-helpdesk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitfinexcom%2Fbfx-ext-helpdesk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitfinexcom","download_url":"https://codeload.github.com/bitfinexcom/bfx-ext-helpdesk-js/tar.gz/refs/heads/1.x","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitfinexcom%2Fbfx-ext-helpdesk-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29962029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T05:59:08.471Z","status":"ssl_error","status_checked_at":"2026-03-01T05:58:04.208Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","async","backend","backend-services","bitfinex","grenache","javascript","js","microservice","microservices","node","nodejs"],"created_at":"2024-12-08T15:10:29.460Z","updated_at":"2026-03-01T06:35:44.376Z","avatar_url":"https://github.com/bitfinexcom.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bitfinex External Helpdesk Service\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-green.svg)](https://opensource.org/licenses/Apache-2.0)\n![GitHub Release](https://img.shields.io/github/release/bitfinexcom/bfx-ext-helpdesk-js/all.svg)\n![GitHub Release Date](https://img.shields.io/github/release-date/bitfinexcom/bfx-ext-helpdesk-js.svg)\n![GitHub Last Commit](https://img.shields.io/github/last-commit/bitfinexcom/bfx-ext-helpdesk-js.svg)\n![GitHub Pull Requests](https://img.shields.io/github/issues-pr/bitfinexcom/bfx-ext-helpdesk-js.svg)\n![stability-stable](https://img.shields.io/badge/stability-stable-green.svg)\n\n\u003cimg align=\"right\" width=\"15%\" src=\"https://github.com/bitfinexcom/grenache/raw/master/logos/logo-square.png\" /\u003e\n\n- [Introduction](#introduction)\n- [Copying](#copying)\n- [Prerequisites](#prerequisites)\n- [Install](#install)\n- [Configure](#configure)\n  - [grcServices](#grcservices)\n  - [helpdesk](#helpdesk)\n- [Starting](#starting)\n  - [Signal handling](#signal-handling)\n    - [SIGINT](#sigint)\n    - [SIGTSTP](#sigtstp)\n    - [SIGCONT](#sigcont)\n- [Grenache API](#grenache-api)\n  - [action: 'getDepartments'](#action-getdepartments)\n  - [action: 'getTopics'](#action-gettopics)\n  - [action: 'getTags'](#action-gettags)\n  - [action: 'getAgents'](#action-getagents)\n  - [action: 'getAgreements'](#action-getagreements)\n  - [action: 'getTeams'](#action-getteams)\n- [Examples](#examples)\n- [Maintainers](#maintainers)\n\n\n## Introduction\n\nThe [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) is a [Grenache](https://github.com/bitfinexcom/grenache) worker that allows interaction with the internal helpdesk system over a [Grape](https://github.com/bitfinexcom/grenache-grape) network. Basically, the [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) worker acts as a proxy for the internal helpdesk's *RESTful API*, making it available over the DHT.\n\nThe scaffolding of the [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) worker has been created using [svc-js-cli](https://github.com/bitfinexcom/svc-js-cli) with [bfx-ext-js](https://github.com/bitfinexcom/bfx-ext-js) as service base.\n\n\n## Copying\n\nThe [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) is free software. See the files whose names start with *LICENSE* (case-insensitive) for copying permission. The manuals, and some of the runtime libraries, are under different terms; see the individual source files for details.\n\nCopyright years on [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) source files may be listed using range notation, e.g., 2017-2023, indicating that every year in the range, inclusive, is a copyrightable year that could otherwise be listed individually.\n\n\n## Prerequisites\n\nThe [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) is a [Grenache](https://github.com/bitfinexcom/grenache) worker, hence it is essential that the machine on which it is launched is a member of a [Grape](https://github.com/bitfinexcom/grenache-grape) network. The [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) worker is developed in *Javascript* and requires a [Node.js®](https://nodejs.org/) runtime environment to be run, version *greater than* or *equal to* *v14.18.0*. Also, a package manager, such as [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/) or [pnpm](https://pnpm.io/), is required in order to install all the dependencies.\n\n\n## Install\n\nIn a nutshell, the shell command:\n\n```bash\nnpm install --include='dev' --no-save\n```\n\nexecuted within the worker's main directory, will install all the required dependencies, suitable for all environments. You can also use [yarn](https://yarnpkg.com/) or [pnpm](https://pnpm.io/).\n\n\n## Configure\n\nBesides standard worker files, such as `common.json` where to set some general options and `grc.config.json` where to put the [Grape](https://github.com/bitfinexcom/grenache-grape) address (see [bfx-facs-grc](https://github.com/bitfinexcom/bfx-facs-grc) for more information), the *main* configuration file is `helpdesk.ext.json`.\n\nBelow are some details of the several sections that compose this configuration file; a look at the `helpdesk.ext.json.example` file, within the worker’s `config` directory, is also possible to get a good overview of its structure.\n\n### grcServices\n\nThis is the standard worker array for declaring [Grenache](https://github.com/bitfinexcom/grenache) service names. The service name root assigned to this worker is `rest:ext:helpdesk`, however, a service for every single helpdesk has to be declared; most importantly, the fourth key of the service name has to match a property of the `helpdesk` object (see next section). This means that if two services are declared, such as `rest:ext:helpdesk:foo` and `rest:ext:helpdesk:bar:private`, the object in the next section needs to have at least the `foo` and `bar` properties set.\n\n### helpdesk\n\nIn this section, details for every single helpdesk can be declared; as mentioned above, each key of the `helpdesk` object has to match the fourth key of the service name, while each item is an object with the following properties:\n\n- `revision \u003cstring\u003e` API revision to be used; one of *v1* or *v2*\n- `publicKey \u003cstring\u003e` API public key\n- `privateKey \u003cstring\u003e` API private key\n- `baseUrl \u003cstring\u003e` API base URL, without any path\n\nWith the exception of API revision, all of the above properties are to be considered mandatory; in case the API revision is invalid or missing, the worker will fallback to *v2*.\n\n\n## Starting\n\nTo get started quickly, the shell command:\n\n```bash\nnode worker.js --env=\u003cenvironment\u003e --wtype=wrk-ext-helpdesk-api --apiPort \u003cport\u003e\n```\n\nexecuted within the worker's main directory will bring it up and running. As a handy alternative, when a [POSIX](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18)-like compliant shell is being used, a script, defined in the package's manifest file, can be invoked using, for example, the following command:\n\n```bash\nnpm run worker\n```\n\nwhich, by default, runs the worker under the `development` environment, listening on port `7777`. These arguments can be customized using a `.npmrc` file in the project root (ie a sibling of `node_modules` and `package.json`). If the version of *npm* currently in use supports it, this command:\n\n```bash\nnpm config --location 'project' set 'port=8888'\n```\n\ncan be run to customize the port number, while this other one:\n\n```bash\nnpm config --location 'project' set 'env=production'\n```\n\nto set the environment.\n\nAlthough all of this is convenient and quick, it is not advisable to use it in a *production* environment; in that case, the use of a proper *process manager* (eg [systemd](https://systemd.io/), [pm2](https://pm2.keymetrics.io/), etc.) is recommended.\n\n### Signal handling\n\nThe [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) worker handles several signals for different purposes; refer to the documentation of the operating system on which this worker is being executed to figure out how to send signals to a running process.\n\nOnly major signals are covered in this section; it is possible that a signal not listed here is handled by one of the [Grenache](https://github.com/bitfinexcom/grenache) framework components used as dependency by the [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) worker; refer to the documentation of the single components for a more in-depth view.\n\n#### SIGINT\n\nSend this signal to the [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) worker to initiate a graceful shutdown. As a handy shortcut, when using a [POSIX](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18)-like compliant shell and a compatible [pkill](https://gitlab.com/procps-ng/procps/) command-line utility, a script, defined in the package's manifest file,  can be invoked using, for example, the following command:\n\n```bash\nnpm run worker:stop\n```\n\n#### SIGTSTP\n\nSend this signal to the [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) worker to *pause* the scheduler; all incoming requests will be rejected. As a handy shortcut, when using a [POSIX](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18)-like compliant shell and a compatible [pkill](https://gitlab.com/procps-ng/procps/) command-line utility, a script, defined in the package's manifest file,  can be invoked using, for example, the following command:\n\n```bash\nnpm run worker:pause\n```\n\n#### SIGCONT\n\nSend this signal to the [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) worker to *resume* the scheduler; all incoming requests will be accepted. As a handy shortcut, when using a [POSIX](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18)-like compliant shell and a compatible [pkill](https://gitlab.com/procps-ng/procps/) command-line utility, a script, defined in the package's manifest file,  can be invoked using, for example, the following command:\n\n```bash\nnpm run worker:resume\n```\n\n\n## Grenache API\n\nAll available actions are documented in this section; to better describe every action and assist the reader, the following type conventions will be used:\n\n- `int_t` a *non-decimal* number\n- `string_t` a *non-empty*, *trimmed* string\n- `sort_t` a *trimmed*, *case-insensitve* string whose only possible values are *ASC* and *DESC*\n- `bool_t` a boolean where `1`, `\"true\"`, `\"1\"`, `\"on\"` and `true` will be evaluated as *true*, while `0`, `\"false\"`, `\"0\"`, `\"off\"` and `false` will be treated as *false*\n\n### action: 'getDepartments'\n\nGet departments list ordered by name in ascending order. All of the following arguments and properties are to be considered optional.\n\n  - `args \u003cArray\u003e`\n    - `0 \u003cObject\u003e`\n      - `limit \u003cint_t\u003e` maximum number of results as a *positive* integer\n      - `offset \u003cint_t\u003e` offset of the first result as a *non-negative* integer\n      - `sort \u003csort_t\u003e` sort direction\n      - `pid \u003cint_t\u003e` department parent identifier as a *positive* integer\n      - `name \u003cstring_t\u003e` a *single-line*, *case-insensitve* string that has to be contained in the department name (no more than *128 characters*)\n\n**Response:**\n\n  - `\u003cArray\u003e` The departments list. Each list item will have the following properties:\n    - `id \u003cint_t\u003e` department identifier as a *positive* integer\n    - `name \u003cstring_t\u003e` department name\n\n**Example Response:**\n\n```js\n[\n  {\n    \"id\": 31337,\n    \"name\": \"foobar\"\n  }\n]\n```\n\n### action: 'getTopics'\n\nGet topics list ordered by name in ascending order. All of the following arguments and properties are to be considered optional.\n\n  - `args \u003cArray\u003e`\n    - `0 \u003cObject\u003e`\n      - `limit \u003cint_t\u003e` maximum number of results as a *positive* integer\n      - `offset \u003cint_t\u003e` offset of the first result as a *non-negative* integer\n      - `sort \u003csort_t\u003e` sort direction\n      - `is_active \u003cbool_t\u003e` whether or not topic is active\n      - `name \u003cstring_t\u003e` a *single-line*, *case-insensitve* string that has to be contained in the topic name (no more than *32 characters*)\n\n**Response:**\n\n  - `\u003cArray\u003e` The topics list. Each list item will have the following properties:\n    - `name \u003cstring_t\u003e` topic name\n    - `id \u003cint_t\u003e` topic identifier as a *positive* integer\n    - `pid \u003cint_t\u003e` topic parent identifier as a *positive* integer if it exists, *0* otherwise\n\n**Example Response:**\n\n```js\n[\n  {\n    \"name\": \"foobar\",\n    \"id\": 31337,\n    \"pid\": 1337\n  }\n]\n```\n\n### action: 'getTags'\n\nGet tags list ordered as configured on the helpdesk backend in ascending order. All of the following arguments and properties are to be considered optional.\n\n\u003e **Note:** tags can be quite a lot; whenever possible, make use of the filters below to minimize the number of *REST* requests (and thereby decrease the overall response time).\n\n  - `args \u003cArray\u003e`\n    - `0 \u003cObject\u003e`\n      - `limit \u003cint_t\u003e` maximum number of results as a *positive* integer\n      - `offset \u003cint_t\u003e` offset of the first result as a *non-negative* integer\n      - `sort \u003csort_t\u003e` sort direction\n      - `is_active \u003cbool_t\u003e` whether or not tag is active\n      - `name \u003cstring_t\u003e` a *single-line*, *case-insensitve* string that has to be contained in the tag name (no more than *255 characters*)\n\n**Response:**\n\n  - `\u003cArray\u003e` The tags list. Each list item will have the following properties:\n    - `id \u003cint_t\u003e` tag identifier as a *positive* integer\n    - `name \u003cstring_t\u003e` tag name\n\n**Example Response:**\n\n```js\n[\n  {\n    \"id\": 31337,\n    \"name\": \"foobar\"\n  }\n]\n```\n\n### action: 'getAgents'\n\nGet agents list ordered by username in ascending order. All of the following arguments and properties are to be considered optional.\n\n  - `args \u003cArray\u003e`\n    - `0 \u003cObject\u003e`\n      - `limit \u003cint_t\u003e` maximum number of results as a *positive* integer\n      - `offset \u003cint_t\u003e` offset of the first result as a *non-negative* integer\n      - `sort \u003csort_t\u003e` sort direction\n      - `is_locked \u003cbool_t\u003e` whether or not agent is locked\n      - `on_vacation \u003cbool_t\u003e` whether or not agent is on vacation\n      - `department_id \u003cint_t\u003e` department identifier associated with the agent as a *positive* integer\n      - `name \u003cstring_t\u003e` a *single-line*, *case-insensitve* string that has to be contained in the agent name (no more than *64 characters*)\n      - `email \u003cstring_t\u003e` a *single-line*, *case-insensitve* string that has to be contained in the agent email (no more than *255 characters*)\n\n**Response:**\n\n  - `\u003cArray\u003e` The agents list. Each list item will have the following properties:\n    - `username \u003cstring_t\u003e` agent username\n    - `email \u003cstring_t\u003e` agent e-mail address\n    - `id \u003cint_t\u003e` agent identifier as a *positive* integer\n\n**Example Response:**\n\n```js\n[\n  {\n    \"username\": \"foobar\",\n    \"email\": \"foobar@example.com\",\n    \"id\": 31337\n  }\n]\n```\n\n### action: 'getAgreements'\n\nGet SLAs list ordered by name in ascending order. All of the following arguments and properties are to be considered optional.\n\n  - `args \u003cArray\u003e`\n    - `0 \u003cObject\u003e`\n      - `limit \u003cint_t\u003e` maximum number of results as a *positive* integer\n      - `offset \u003cint_t\u003e` offset of the first result as a *non-negative* integer\n      - `sort \u003csort_t\u003e` sort direction\n      - `is_active \u003cbool_t\u003e` whether or not SLA plan is active\n      - `name \u003cstring_t\u003e` a *single-line*, *case-insensitve* string that has to be contained in the SLA name (no more than *64 characters*)\n\n**Response:**\n\n  - `\u003cArray\u003e` The SLAs list. Each list item will have the following properties:\n    - `name \u003cstring_t\u003e` SLA mnemonic name\n    - `id \u003cint_t\u003e` SLA identifier as a *positive* integer\n    - `grace_period \u003cint_t\u003e` amount as a *positive* integer, in hours, before tickets with this SLA will become *overdue* if not closed in allotted time\n\n**Example Response:**\n\n```js\n[\n  {\n    \"name\": \"foobar\",\n    \"id\": 31337,\n    \"grace_period\": 48\n  }\n]\n```\n\n### action: 'getTeams'\n\nGet teams list ordered by name in ascending order. All of the following arguments and properties are to be considered optional.\n\n  - `args \u003cArray\u003e`\n    - `0 \u003cObject\u003e`\n      - `limit \u003cint_t\u003e` maximum number of results as a *positive* integer\n      - `offset \u003cint_t\u003e` offset of the first result as a *non-negative* integer\n      - `sort \u003csort_t\u003e` sort direction\n      - `is_empty \u003cbool_t\u003e` whether or not team is empty\n      - `is_active \u003cbool_t\u003e` whether or not team is active\n      - `name \u003cstring_t\u003e` a *single-line*, *case-insensitve* string that has to be contained in the team name (no more than *125 characters*)\n\n**Response:**\n\n  - `\u003cArray\u003e` The teams list. Each list item will have the following properties:\n    - `name \u003cstring_t\u003e` team name\n    - `id \u003cint_t\u003e` team identifier as a *positive* integer\n    - `active_members \u003cint_t\u003e` number of active team members as a *non-negative* integer\n\n**Example Response:**\n\n```js\n[\n  {\n    \"name\": \"foobar\",\n    \"id\": 31337,\n    \"active_members\": 1337\n  }\n]\n```\n\n\n## Examples\n\nRefer to the [example.js](example.js) file within the project main directory for an example of using the *API* provided by the [*bfx-ext-helpdesk-js*](https://github.com/bitfinexcom/bfx-ext-helpdesk-js) worker.\n\n\n## Maintainers\n\nCurrent maintainers:\n\n- [Davide Scola](https://github.com/davide-scola)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitfinexcom%2Fbfx-ext-helpdesk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitfinexcom%2Fbfx-ext-helpdesk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitfinexcom%2Fbfx-ext-helpdesk-js/lists"}