{"id":13696673,"url":"https://github.com/box/box-node-sdk","last_synced_at":"2025-05-14T20:07:25.332Z","repository":{"id":9771647,"uuid":"60120242","full_name":"box/box-node-sdk","owner":"box","description":"A Javascript interface for interacting with the Box API. You can find the node package at","archived":false,"fork":false,"pushed_at":"2025-04-09T18:55:53.000Z","size":42652,"stargazers_count":190,"open_issues_count":3,"forks_count":120,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-04-13T14:07:04.069Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/box-node-sdk","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/box.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2016-05-31T20:14:17.000Z","updated_at":"2025-04-09T18:55:49.000Z","dependencies_parsed_at":"2025-02-28T10:14:45.558Z","dependency_job_id":"b2d53ba1-57dd-4af1-a71c-ee9eeebdc12d","html_url":"https://github.com/box/box-node-sdk","commit_stats":{"total_commits":605,"total_committers":51,"mean_commits":"11.862745098039216","dds":0.5768595041322314,"last_synced_commit":"498425e4b4597b9feacfabdc6a1f408734e45b39"},"previous_names":[],"tags_count":88,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fbox-node-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fbox-node-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fbox-node-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fbox-node-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/box","download_url":"https://codeload.github.com/box/box-node-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724638,"owners_count":21151561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["hacktoberfest"],"created_at":"2024-08-02T18:00:44.727Z","updated_at":"2025-04-13T14:07:15.124Z","avatar_url":"https://github.com/box.png","language":"JavaScript","funding_links":[],"categories":["Node JS"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/box/sdks/blob/master/images/box-dev-logo.png\" alt= “box-dev-logo” width=\"30%\" height=\"50%\"\u003e\n\u003c/p\u003e\n\n# Deprecation notice\n\nThis version of the Box Node SDK is under maintenance mode, and will be deprecated soon, only critical security updates and bug fixes will be provided. We recommend using the new version Box Typescript SDK, which can be found at [box/box-typescript-sdk-gen](https://github.com/box/box-typescript-sdk-gen)\n\nYou can find the migration guide [here](https://github.com/box/box-typescript-sdk-gen/blob/main/migration-guide.md) for transitioning from Box Node SDK to the new `box-typescript-sdk-gen` package. If you have any questions, please create an issue in the new repository or reach out to [Box Developer Support](https://developer.box.com/support/).\n\nBox Node.js SDK\n===============\n\n[![Known Vulnerabilities](https://snyk.io/test/github/box/box-node-sdk/badge.svg)](https://snyk.io/test/github/box/box-node-sdk)\n![Platform](https://img.shields.io/badge/node-14--20-blue)\n[![Project Status](http://opensource.box.com/badges/stable.svg)](http://opensource.box.com/badges)\n[![Coverage](https://coveralls.io/repos/github/box/box-node-sdk/badge.svg?branch=main)](https://coveralls.io/github/box/box-node-sdk?branch=main)\n\nA Node.js interface to the [Box Content API](https://developer.box.com/reference/).\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Deprecation notice](#deprecation-notice)\n- [Box Node.js SDK](#box-nodejs-sdk)\n\t- [Installation](#installation)\n\t- [Getting Started](#getting-started)\n\t- [Creating API Clients](#creating-api-clients)\n\t\t- [Basic Client](#basic-client)\n\t\t- [Persistent Client](#persistent-client)\n\t\t- [App Auth Client](#app-auth-client)\n\t- [Using the Client to Make API Calls](#using-the-client-to-make-api-calls)\n\t\t- [Constructing API Calls Manually](#constructing-api-calls-manually)\n\t- [FIPS 140-2 Compliance](#fips-140-2-compliance)\n\t- [Versions](#versions)\n\t\t- [Supported Version](#supported-version)\n\t\t- [Version schedule](#version-schedule)\n\t- [Questions, Bugs, and Feature Requests?](#questions-bugs-and-feature-requests)\n\t- [Contributing to the Box Node.js SDK](#contributing-to-the-box-nodejs-sdk)\n\t- [Changelog](#changelog)\n\t- [Upgrades](#upgrades)\n\t- [Documentation](#documentation)\n\t- [Copyright and License](#copyright-and-license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Installation\nNode SDK Installation [details](https://developer.box.com/guides/tooling/sdks/node/).\n\n```\nnpm install --save box-node-sdk\n```\n\n## Getting Started\n\n\nTo get started with the SDK, get a Developer Token from the Configuration page\nof your platform app in the [Box Developer Console][dev-console].\nYou can use this token to make test calls for your own Box account.\n\n```js\nvar BoxSDK = require('box-node-sdk');\n\n// Initialize the SDK with your app credentials\nvar sdk = new BoxSDK({\n  clientID: 'CLIENT_ID',\n  clientSecret: 'CLIENT_SECRET'\n});\n\n// Create a basic API client, which does not automatically refresh the access token\nvar client = sdk.getBasicClient('DEVELOPER_TOKEN');\n\n// Get your own user object from the Box API\n// All client methods return a promise that resolves to the results of the API call,\n// or rejects when an error occurs\nclient.users.get(client.CURRENT_USER_ID)\n\t.then(user =\u003e console.log('Hello', user.name, '!'))\n\t.catch(err =\u003e console.log('Got an error!', err));\n```\n\n[dev-console]: https://app.box.com/developers/console\n\n## Creating API Clients\n\n\nClients are used to communicate with the API on behalf of a user.\n\nBox supports three different types of client:\n\n- **Basic Client:** Simple, makes calls via the given access token until the access token expires\n- **Persistent Client:** For use with traditional OAuth2 apps, can refresh its tokens automatically and persist them via a token store\n- **App Auth Client:** Uses the app auth JWT grant to act on behalf of app/managed users and create new tokens automatically\n\n### Basic Client\n\nReturns a Box Client with a Basic API Session. The client is able to make requests on behalf of a user. A basic session has no access to a user's refresh token. Because of this, once the session's tokens expire the client cannot recover and a new session will need to be generated.\n\n```js\nvar client = BoxSDK.getBasicClient('ACCESS_TOKEN');\n```\n\n### Persistent Client\n\nReturns a Box Client with a persistent API session. A persistent API session helps manage the user's tokens, and can refresh them automatically if the access token expires. If a central data-store is given, the session can read \u0026 write tokens to it.\n\n\u003e NOTE: If tokenInfo or tokenStore are formatted incorrectly, this method will throw an error. If you haven't explicitly created either of these objects or are otherwise not completely confident in their validity, you should wrap your call to getPersistentClient in a try-catch to handle any potential errors.\n\nIf you do not provide a token store object, the SDK will continue refreshing tokens locally as long\nas the Node.js process lives, but will not able to restore the user's authentication on process\nrestart or share that authentication state between different processes.\n```js\nvar client = sdk.getPersistentClient(tokenInfo, null);\n```\n\nProviding a token store will allow the SDK to persist the user's authentication state\nso that you can resume making API calls as a user if the Node.js process needs to restart,\nor share the authentication state between multiple different processes.\n```js\nvar client = sdk.getPersistentClient(tokenInfo, tokenStore);\n```\n\nThe token store is the interface used by persistent clients to interact with the consumer app's central storage layer. For a token store to be valid, it must have the following three methods:\n\n```js\nstore.read(function(err, data) {}); // read TokenInfo from app central store.\nstore.write(tokenInfo, function(err, data) {}); // write TokenInfo to the app's central store.\nstore.clear(function(err, data) {}); // delete TokenInfo from the app's central store.\n```\n\nNote that these methods don't pass in identifying information as arguments. You'll most likely need to create them on-demand for each client.\n\n### App Auth Client\n\nApp Auth allows an platform app to fully manage the Box accounts of its users; they do not\nhave direct login credentials to Box and all operations are performed through the API\nusing a JWT grant.\n\nIf you have a JSON configuration file from the [Box Developer Console][dev-console]\nthat includes your private key information, you can import that directly to create an SDK instance:\n\n```js\nvar sdkConfig = require('/path/to/config.json');\nvar sdk = BoxSDK.getPreconfiguredInstance(sdkConfig);\n\n// Get the service account client, used to create and manage app user accounts\n// The enterprise ID is pre-populated by the JSON configuration,\n// so you don't need to specify it here\nvar serviceAccountClient = sdk.getAppAuthClient('enterprise');\n\n// Get an app user or managed user client\nvar appUserClient = sdk.getAppAuthClient('user', 'YOUR-APP-USER-ID');\n```\n\nOtherwise, you can manually pass the necessary configuration parameters to the SDK:\n\n```js\nvar sdk = new BoxSDK({\n\tclientID: 'CLIENT_ID',\n\tclientSecret: 'CLIENT_SECRET',\n\tappAuth: {\n\t\tkeyID: 'PUBLIC_KEY_ID',\n\t\tprivateKey: 'PRIVATE_KEY',\n\t\tpassphrase: 'PRIVATE_KEY_PASSPHRASE'\n\t}\n});\n\n// Get the service account client, used to create and manage app user accounts\nvar serviceAccountClient = sdk.getAppAuthClient('enterprise', 'APP_ENTERPRISE_ID');\n\n// Get an app user or managed user client\nvar appUserClient = sdk.getAppAuthClient('user', 'YOUR-APP-USER-ID');\n```\n\n\n## Using the Client to Make API Calls\n\n\nThe different API endpoints you can call are represented as methods, grouped into\nmanagers by the type of object they interact with.\n\nFor example:\n```js\n// Get the user object for the current user\nclient.users.get(client.CURRENT_USER_ID)\n\t.then(currentUser =\u003e { /* ... */ })\n\t.catch(error =\u003e { /* handle any errors */ });\n\n// Update the name for folder with ID 123\nclient.folders.update('123', { name: 'New Folder Name' })\n\t.then(folderInfo =\u003e { /* ... */ })\n\t.catch(error =\u003e { /* handle any errors */ });\n\n// Upload a new file to folder 123\nclient.files.uploadFile('123', 'bicycle.png', fileContents)\n\t.then(fileObject =\u003e { /* ... */ })\n\t.catch(error =\u003e { /* handle any errors */ });\n\n// Delete the comment with ID 456\nclient.comments.delete('456')\n\t.then(() =\u003e { /* ... */ })\n\t.catch(error =\u003e { /* handle any errors */ });\n```\n\nFor complete documentation about the available operations, please see\nthe [SDK documentation pages](./docs) and the auto-generated\n[JSDocs](https://rawgit.com/box/box-node-sdk/main/docs/jsdoc/index.html).\nThese contain detailed information about which methods are available and\nhow to use them.\n\n### Constructing API Calls Manually\n\nThe SDK also exposes low-level request methods for constructing your own API calls.\nThese can be useful for adding your own API calls that aren't yet explicitly supported by the SDK.\n\nThe low-level methods always return a response object that contains the raw API response, and do not\nturn non-2xx status codes into errors like the normal client methods do.\n\n```js\n// GET /files/123?fields=id,name\nclient.get('/files/123', {qs: {fields: 'id,name'}})\n\t.then(response =\u003e { /* ... */ })\n\t.catch(error =\u003e { /* handle any errors */ });\n\n// PUT /files/123\n// {\n//     \"name\": \"New File Name\"\n// }\nclient.put('/files/123', {body: {name: 'New File Name'}});\n\t.then(response =\u003e { /* ... */ })\n\t.catch(error =\u003e { /* handle any errors */ });\n\n// DELETE /files/123\nclient.del('/files/123');\n\t.then(response =\u003e { /* ... */ })\n\t.catch(error =\u003e { /* handle any errors */ });\n```\n\n## FIPS 140-2 Compliance\n\nThe Box Node SDK allows the use of FIPS 140-2 validated SSL libraries, such as OpenSSL 3.0.\nHowever, some actions are required to enable this functionality.\n\nBy default, the version of OpenSSL Node.js includes is not FIPS enabled. Therefore, if you want to use OpenSSL 3.0 with FIPS, you need to [build OpenSSL 3.0 with FIPS enabled](https://github.com/openssl/openssl/blob/master/README-FIPS.md) and then build Node.js use the shared OpenSSL 3.0 library.\n\nAccording to [Node.js OpenSSL Strategy](https://github.com/nodejs/TSC/blob/main/OpenSSL-Strategy.md) document, you can use the OpenSSL 3.0 from Node.js v16 or later.\n\n## Versions\nWe use a modified version of [Semantic Versioning](https://semver.org/) for all changes. See [version strategy](VERSIONS.md) for details which is effective from 30 July 2022.\n\n### Supported Version\n\nOnly the current MAJOR version of SDK is supported. New features, functionality, bug fixes, and security updates will only be added to the current MAJOR version.\n\nA current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features.  \nInstead of stating a release date for a new feature, we set a fixed minor or patch release cadence of maximum 2-3 months (while we may release more often). \nAt the same time, there is no schedule for major or breaking release. Instead, we will communicate one quarter in advance the upcoming breaking change to \nallow customers to plan for the upgrade. We always recommend that all users run the latest available minor release for whatever major version is in use. \nWe highly recommend upgrading to the latest SDK major release at the earliest convenient time and before the EOL date.\n\n### Version schedule\n\n| Version | Supported Environments | State     | First Release | EOL/Terminated |\n|---------|------------------------|-----------|---------------|----------------|\n| 3       | Node.js \u003e= 14 and \u003c= 20| Supported | 23 May 2023   | TBD            |\n| 2       | Node.js \u003e= 8 and \u003c= 14 | Maintained | 29 Sep 2021   | 23 Jul 2023    |\n| 1       |                        | EOL       | 28 Mar 2019   | 29 Sep 2021    |\n\n## Questions, Bugs, and Feature Requests?\n\n\n[Browse the issues tickets](https://github.com/box/box-node-sdk/issues)! Or, if that doesn't work, [file a new one](https://github.com/box/box-node-sdk/issues/new) and someone will get back to you.   If you have general questions about the\nBox API, you can post to the [Box Developer Forum](https://community.box.com/t5/Developer-Forum/bd-p/DeveloperForum).\n\n\n## Contributing to the Box Node.js SDK\n\n\n1. Clone this repo.\n1. Run `npm install`.\n1. Run `npm test` to ensure everything is working.\n1. Make the changes you want in the `lib/` directory.  Be sure to add corresponding tests\nin the `tests/` directory!\n1. Run the unit tests by command `npm run test` and integration test as instructed [here](./tests/integration_test/README.md).\n1. Create a pull request with your changes — we'll review it and help you get it merged.\n\nCurrently, the  **Sign Request**  module is generated automatically from OpenAPI specs. To re-generate this module, download the latest version of Box OpenAPI specs [here](https://raw.githubusercontent.com/box/box-openapi/en/openapi.json), save it to the root directory and run  `npm run codegen`.\n\nFor more information, please see [the Contribution guidelines](./CONTRIBUTING.md).\n\n## Changelog\n\n\nSee [CHANGELOG.md](./CHANGELOG.md).\n\n## Upgrades\n\nYou can read about how to migrate to the new version [here](./docs/upgrade/).\n\n## Documentation\n\nYou can find guides and tutorials in the `docs` directory.\n\n* [Configuration](docs/configuration.md)\n\n## Copyright and License\n\nCopyright 2018 Box, Inc. All rights reserved.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbox%2Fbox-node-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbox%2Fbox-node-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbox%2Fbox-node-sdk/lists"}