{"id":39276352,"url":"https://github.com/cloudboltsoftware/js-sdk","last_synced_at":"2026-01-20T17:00:11.421Z","repository":{"id":180796790,"uuid":"457927778","full_name":"CloudBoltSoftware/js-sdk","owner":"CloudBoltSoftware","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-18T20:30:47.000Z","size":854,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-09-18T21:09:33.801Z","etag":null,"topics":["cloudbolt","javascript","javascript-sdk"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CloudBoltSoftware.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-02-10T19:57:23.000Z","updated_at":"2025-09-18T20:14:47.000Z","dependencies_parsed_at":"2023-11-10T12:42:09.566Z","dependency_job_id":"b73ad5e7-11c1-4ea6-9cce-b64271b6761a","html_url":"https://github.com/CloudBoltSoftware/js-sdk","commit_stats":null,"previous_names":["cloudboltsoftware/js-sdk"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/CloudBoltSoftware/js-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CloudBoltSoftware%2Fjs-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CloudBoltSoftware%2Fjs-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CloudBoltSoftware%2Fjs-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CloudBoltSoftware%2Fjs-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CloudBoltSoftware","download_url":"https://codeload.github.com/CloudBoltSoftware/js-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CloudBoltSoftware%2Fjs-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: 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":["cloudbolt","javascript","javascript-sdk"],"created_at":"2026-01-18T00:56:25.336Z","updated_at":"2026-01-20T17:00:11.415Z","avatar_url":"https://github.com/CloudBoltSoftware.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CloudBolt Javascript SDK\n\n## Features\n\n- Use idomatic js to interact with the CloudBolt API for a subset of endpoints\n  - Normalizes responses for list requests\n  - In-IDE documentation/intellisense for all included endpoints\n- Helper methods for common tasks\n- built with [axios](https://github.com/axios/axios) with through-access for advanced use cases\n\n## Installation\n\nInstall as a local dependency in your project:\n\n```bash\nnpm install @cloudbolt/js-sdk\n```\n\n## Usage\n\n### Package Structure\n\nThe package exports a single function, `createApi`. This function returns an `api` instance with methods for interacting with the CloudBolt API. The `api` instance is simply an object with nested objects and methods. Important properties include:\n\n- `api.base` - helper methods and objects for interacting with the CloudBolt API\n  - `api.base.instance` - the axios instance used for all requests\n  - `api.base.crud` - helper methods for interacting with the CloudBolt API at a low-level. They take an endpoint string and various other arguments and options.\n  - `api.base.setAuthHeader` - set the auth header on the axios instance\n  - `api.base.setErrorHandler` - set a custom error handler for failed requests\n- `api.v3` - methods for interacting with the CloudBolt API v3. Generally they attempt to follow the url structure of the underlying endpoints, [as documented in Swaggerhub](https://app.swaggerhub.com/apis-docs/cloudbolt/Cloudbolt_CMP_API/). Examples are:\n  - `api.v3.cmp.environments`\n    - `api.v3.cmp.environments.list(options)`\n    - `api.v3.cmp.environments.get(id)`\n    - `api.v3.cmp.environments.create(newEnvironment)`\n    - `api.v3.cmp.environments.update(id, updatedEnvironment)`\n    - `api.v3.cmp.environments.replace(id, newEnvironment)`\n    - `api.v3.cmp.environments.delete(id)`\n    - `api.v3.cmp.environments.export(id)`\n    - `api.v3.cmp.environments.getParameters(id)`\n    - `api.v3.cmp.environments.setParameters(id, parameters)`\n  - `api.v3.cmp.groups`\n    - `api.v3.cmp.groups.list(options)`\n    - `api.v3.cmp.groups.get(id)`\n    - `api.v3.cmp.groups.create(newGroup)`\n    - `api.v3.cmp.groups.update(id, updatedGroup)`\n    - `api.v3.cmp.groups.delete(id)`\n  - `api.v3.cmp.users`\n    - `api.v3.cmp.users.list(options)`\n    - `api.v3.cmp.users.getCurrentUser(options)`\n    - `api.v3.cmp.users.getUserDetails(id)`\n    - `api.v3.cmp.users.getUserPermissions(id)`\n    - `api.v3.cmp.users.updatePassword(id, options)`\n\nFor an exhaustive look at what is available in `api.v3...`, see in-IDE documentation as you code or the built [types list](./types/index.d.ts). For all other API capabilities, use the `api.base.crud` methods and refer to the [Swaggerhub documentation](https://app.swaggerhub.com/apis-docs/cloudbolt/Cloudbolt_CMP_API/).\n\n### What do endpoints return?\n\nRefer to the examples in the [Swaggerhub documentation](https://app.swaggerhub.com/apis-docs/cloudbolt/Cloudbolt_CMP_API/) for specific endpoint examples. Generally, endpoints return a `Promise` that resolves to the response data from the API.\n\nThis package restructures responses from `list` endpoints slightly to make responses more predictable and ergonomic for a js context. If you ever need the original, unstructured response from a query, use the axios instance at `api.base.instance` and query endpoints directly. When using `api.v3...` list endpoints or the helper `api.base.crud.getItems`, the response data looks like this:\n\n```js\n{\n   items: any[];\n   pageInfo: {\n      page: number;\n      nextPage: string;\n      previousPage: string;\n      totalElements: number;\n   };\n}\n```\n\n## Examples\n\n### Authentication\n\nIf using js-sdk from within a CB Applet, the applet receives a pre-authenticated `api` instance for the currently logged in user. It will automatically refresh the auth token as needed.\n\nIf using js-sdk from a stand-alone app, you will need to obtain an auth token from CloudBolt, set it on the api instance, and handle token refreshing manually.\n\n```js\n// Initialize the sdk\nimport { createApi } from '@cloudbolt/js-sdk'\nconst api = createApi()\n\n// Get an auth token from CloudBolt\nconst token = await api.v3.cmp.apiToken.obtainToken('username', 'password')\n// If operating from within a CloudBolt UI Extension, you can use the session cookie:\n// const token = await api.v3.cmp.apiToken.obtainTokenWithSessionCookie()\n\n// Save the auth token to the sdk's axios instance\napi.base.setAuthHeader(token)\n\n// Congrat's! You're ready to start making requests to the CloudBolt API with the `api` instance\n\n// As needed (according to the timeout set in CloudBolt or on auth failure), refresh the auth token\nconst newToken = await api.v3.cmp.apiToken.refreshToken()\napi.base.setAuthHeader(newToken)\n```\n\n### Simple Queries\n\n```js\n// Get a list of environments\nconst environments = await api.v3.cmp.environments.list()\n// Show all of their names\nenvironments.items.forEach((env) =\u003e console.log(env.name))\n// How many are there total?\nconsole.log(environments.pageInfo.totalElements)\n\n// Get a single environment\nconst environment = await api.v3.cmp.environments.get('ENV-12345678')\n// Show its name\nconsole.log(environment.name)\n```\n\n### Queries with options\n\nList endpoints (and some get endpoints) take optional `options` arguments. These options are js objects that generally get converted to query parameters on the request. See [Swaggerhub documentation](https://app.swaggerhub.com/apis-docs/cloudbolt/Cloudbolt_CMP_API/) for per-endpoint available querystrings, our [API Conventions](https://docs.cloudbolt.io/articles/#!cloudbolt-latest-docs/api-conventions/a/h2__904191799) for some commonly available querystrings. For example:\n\n```js\n// Get the second page of 300 resources\nconst resources = await api.v3.cmp.resources.list({ page: 2, page_size: 300 })\n\n// Get groups named \"my-group\"\nconst groups = await api.v3.cmp.groups.list({ filter: 'name:my-group' })\n  .items[0]\n\n// Get jobs ordered by endDate descending\nconst jobs = await api.v3.cmp.jobs.list({ ordering: '-endDate' })\n```\n\n### Querying the base API\n\nNot all endpoints are included in the `api.v3...` helpers. For all other endpoints, use the `api.base.crud` methods. These methods are generic and can be used to query any endpoint and include the `/api` prefix. For example:\n\n```js\n// Get a list of all f5 load balancers\nconst loadBalancers = await api.base.crud.getItems('/v3/cmp/loadBalancers/', {\n  filter: 'type:f5'\n})\n\n// Get an OS Image\nconst osImage = await api.base.crud.getItem('/v3/cmp/osImages/IMG-12345678/')\n\n// Patch a tenant\nconst newTenant = await api.base.crud.patchItemById(\n  '/v3/cmp/tenants/TNT-12345678/',\n  { label: 'My Tenant Update' }\n)\n\n// Get the next page of a list result\nconst userPage1 = await api.v3.cmp.users.list()\nconst page2Url = userPage1.pageInfo.nextPage\nconst userPage2 = await api.base.crud.getItems(page2Url)\n```\n\nYou can also use the base axios instance directly (useful if there isn't a helper method for the endpoint or verb you need, or if you have an advanced use case):\n\n```js\n// Download web logs\nconst logs = await api.base.instance.get('/api/v3/cmp/logs/web/')\n\n// Delete a network\nawait api.base.instance.delete('/api/v3/cmp/networks/ET-12345678/')\n```\n\n## Development (for maintainers)\n\n### Publishing a New Release to NPM\n\nFollow these steps to publish a new version of the package to NPM. This process ensures version consistency between GitHub and NPM and is essential for effective release management:\n\n1. **Update Version in `package.json`**\n\n   - **Increment Version**: Run `npm version patch` to update the version in `package.json`. This command also updates `package-lock.json` and creates a Git tag.\n   - **For Beta Versions**: Use `npm version prepatch --preid beta` to create a beta version.\n\n1. **Create a New Release on GitHub**\n\n   - Navigate to the 'Releases' section of your GitHub repository.\n   - Click 'Draft a new release'.\n   - Tag the release with the same version number as in `package.json`, ensuring the tag is on the main branch.\n   - Complete the release title and description, then publish it.\n\n1. **Automated NPM Publishing**\n\n   - An automated workflow is triggered when you create a new release with the correct tag, which will publish the new version to NPM.\n   - Ensure all necessary checks for the release are in place.\n\n1. **Verification**\n   - After the automated process, verify that the new version is available on NPM.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudboltsoftware%2Fjs-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudboltsoftware%2Fjs-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudboltsoftware%2Fjs-sdk/lists"}