https://github.com/bynder/bynder-js-sdk
SDK in JavaScript (Node.js) for integration with Bynder
https://github.com/bynder/bynder-js-sdk
api integration javascript sdk
Last synced: about 2 months ago
JSON representation
SDK in JavaScript (Node.js) for integration with Bynder
- Host: GitHub
- URL: https://github.com/bynder/bynder-js-sdk
- Owner: Bynder
- License: mit
- Created: 2017-05-31T08:56:39.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2025-02-27T16:42:49.000Z (over 1 year ago)
- Last Synced: 2025-03-28T06:09:35.039Z (over 1 year ago)
- Topics: api, integration, javascript, sdk
- Language: JavaScript
- Homepage:
- Size: 2.79 MB
- Stars: 37
- Watchers: 63
- Forks: 42
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# Bynder JavaScript SDK
This SDK aims to help the development of integrations with
[Bynder](https://www.bynder.com/en/) that use JavaScript, providing an easy
interface to communicate with
[Bynder's REST API](https://developer-docs.bynder.com/API/).
## Requirements
To use this SDK, you will need:
- [Node.js **v12 or above**](https://nodejs.org/) (SDK Version 2.5.0 and above)
Node installation will include [NPM](https://www.npmjs.com/), which is
responsible for dependency management.
## Installation
### Node.js
`npm install @bynder/bynder-js-sdk`
`import Bynder from '@bynder/bynder-js-sdk';`
## Usage
This SDK relies heavily on [Promises](https://developers.google.com/web/fundamentals/getting-started/primers/promises),
making it easier to handle the asynchronous requests made to the API. The SDK
provides a `Bynder` object containing several methods which map to the
calls and parameters described in
[Bynder's API documentation](http://docs.bynder.apiary.io/).
The following snippet is a generic example of how to use the SDK. If you need
details for a specific module, refer to the
[samples folder](https://github.com/Bynder/bynder-js-sdk/tree/master/samples).
Before executing any request, you need to authorize the calls to the API:
#### Using a permanent token
```js
const bynder = new Bynder({
baseURL: "https//portal.getbynder.com/api/",
permanentToken: "",
});
```
#### Using OAuth2
1. Call the constructor with your configuration
```js
const bynder = new Bynder({
baseURL: "https://portal.getbynder.com/api/",
clientId: "",
clientSecret: "",
redirectUri: ""
});
```
2. Create an authorization URL, login and get one-time authorization code
```js
const authorizationURL = bynder.makeAuthorizationURL();
```
3. Exchange code for an access token
```js
bynder.getToken(code);
```
If you already have an access token, you can also initialize Bynder with the
token directly:
```js
const bynder = new Bynder({
baseURL: "http://api-url.bynder.io/api/",
clientId: "",
clientSecret: "",
redirectUri: "",
token: ""
});
```
#### OAuth2 Client Credentials
OAuth application within Bynder needs client credentials grant type. Bynder object can be instantiated without redirectUri provided:
```js
const bynder = new Bynder({
baseURL: "http://api-url.bynder.io/api/",
clientId: "",
clientSecret: ""
});
```
To get a token via client credentials, make a call to `getTokenClientCredentials()`:
```js
const bynder = new Bynder({
baseURL: "http://api-url.bynder.io/api/",
clientId: "",
clientSecret: ""
});
const token = await bynder.getTokenClientCredentials();
```
Sample call can be found within `samples/oauth_client_credentials.js`.
#### Making requests
You can now use the various methods from the SDK to fetch media, metaproperties
and other data. Following the Promises notation, you should use
`.then()`/`.catch()` to handle the successful and failed requests,
respectively.
Most of the calls take an object as the only parameter but please refer to the
API documentation to tune the query as intended.
```js
bynder
.getMediaList({
type: "image",
limit: 9,
page: 1
})
.then(data => {
// TODO Handle data
})
.catch(error => {
// TODO Handle the error
});
```
## Available methods
### Authentication
- `makeAuthorizationURL()`
- `getToken()`
- `getTokenClientCredentials()`
### Media
- `getMediaList(queryObject)`
- `getMediaInfo(queryObject)`
- `getAllMediaItems(queryObject)`
- `getMediaTotal(queryObject)`
- `editMedia(object)`
- `deleteMedia(id)`
### Media usage
- `getAssetUsage(queryObject)`
- `saveNewAssetUsage(queryObject)`
- `deleteAssetUsage(queryObject)`
### Metaproperties
- `getMetaproperties(queryObject)`
- `getMetaproperty(queryObject)`
- `saveNewMetaproperty(object)`
- `editMetaproperty(object)`
- `deleteMetaproperty(object)`
- `saveNewMetapropertyOption(object)`
- `editMetapropertyOption(object)`
- `deleteMetapropertyOption(object)`
### Collections
- `getCollections(queryObject)`
- `getCollection(queryObject)`
- `saveNewCollection(queryObject)`
- `shareCollection(queryObject)`
- `addMediaToCollection(queryObject)`
- `deleteMediaFromCollection(queryObject)`
### Tags
- `getTags(queryObject)`
### Smartfilters
- `getSmartfilters(queryObject)`
### Brands
- `getBrands()`
### Upload
- `uploadFile(fileObject)`
## Contribute to the SDK
If you wish to contribute to this repository and further extend the API coverage in the SDK, here
are the steps necessary to prepare your environment:
1. Clone the repository
2. In the root folder, run `yarn install` to install all of the dependencies.
3. Create a `secret.json` file with the following structure:
```json
{
"baseURL": "http://api-url.bynder.io/api/",
"clientId": "",
"clientSecret": "",
"redirectUri": ""
}
```
4. The following gulp tasks are available:
- `gulp lint` - Run ESlint and check the code.
- `gulp build` - Run webpack to bundle the code in order to run in a browser.
- `gulp babel` - Run Babel to create a folder 'dist' with ES2015 compatible code.
- `gulp doc` - Run JSDoc to create a 'doc' folder with automatically generated documentation for the source code.
- `gulp webserver` - Deploy a web server from the root folder at
`localhost:8080` to run the html samples (in order to avoid CORS problems).
## Docker Setup
JavaScript files can be executed within a Docker container with corresponding dependencies installed.
### Initial Setup
From the root directory create a `secret.json` file.
```json
{
"baseURL": "http://api-url.bynder.io/api/",
"clientId": "",
"clientSecret": ""
}
```
Run the command `make run-docker` to start up Docker container.
With the container running, execute the command:
`make executeSdkSample sample-file-name=oauth_client_credentials.js` where sample-file-name is the name of the file within `samples/`. This command will execute the JavaScript file within the container.
### Sample Files
The `samples/` folder contains various example files demonstrating different SDK functionalities:
#### Upload Examples
- `upload_client_credentials.js` - Upload a new asset
- `upload_version_client_credentials.js` - Upload a new version to an existing asset (uses `data.mediaId`)
- `upload_additional_client_credentials.js` - Upload an additional file to an existing asset (uses `additional: true` and `data.id`)
QA - Run in Docker Container
```sh
# Build the image (only needed once or after code changes outside samples/ and secret.json)
docker build -t jssdk .
# Run a sample with local samples/ and secret.json mounted into the container
docker run --rm \
--network=host \
-v $(pwd)/samples:/app/samples \
-v $(pwd)/secret.json:/app/secret.json \
jssdk node samples/tags_client_credentials.js
```