@cognite/sdk

Cognite Javascript SDK

The Cognite js library provides convenient access to the Cognite API from applications written in client- or server-side JavaScript.

The SDK supports authentication through api-keys (for server-side applications) and bearer tokens (for web applications).

Installation

Install the package with yarn:

yarn add @cognite/sdk

or npm

npm install @cognite/sdk --save

Usage

const sdk = require('@cognite/sdk');

sdk.configure({
  project,
  apiKey,
});

Using ES modules

import * as sdk from '@cognite/sdk';

Using typescript

The SDK is written in native typescript, so no extra types needs to be defined.

Authentication

Server-side - API key

Authenticating with an api key should only happen when building server-side applications.

const sdk = require('@cognite/sdk');
sdk.configure({
  project: 'yourProject',
  apiKey: 'yourApiKey',
});

It is generally a good idea store the api key as an environment variable, so it's not directly part of your code.

See the nodejs example

Web application - tokens

import * as sdk from '@cognite/sdk';

// the next line can throw exception if it fails to log in
const authResult = await sdk.Login.authorize({
  project: 'YOUR-PROJECT-NAME', // project you want to login to (can be skipped if you have configured the project with 'configure')
  redirectUrl: window.location.href, // where you want the user to end up after successful login
  errorRedirectUrl: window.location.href, // where you want the user to end up after failed login
});

// at this point you are logged in and you can do calls with the SDK.

authResult = {
  accessToken: string,
  idToken: string,
  project: string,
  projectId: number,
  user: string,
}

See an example here on how to login using redirect and see this example on how to login with popup window.

React

We also provide a seperate package to easily authenticate in React.

Examples

See examples.

Documentation

• SDK documentation
• API documentation

Response headers

On Assets.search, Events.search, Files.search and TimeSeries.search it is possible to read the response headers from the server with the following code:

const result = await sdk.Assets.search({ ... });
const { headers, status } = sdk.getMetadata(result);

License

Apache 2.0

Development

There is one integration test that requires a api key. In order to run this, you need an api key for the cognitesdk-js tenant. Talk to any of the contributors or leave an issue and it'll get sorted. Jenkins will run the test and has its own api key. Set the environment variable COGNITE_CREDENTIALS to your api-key.

Run all tests:

$ yarn
$ yarn test

We use jest to run tests, see their documentation for more information.

Release

How to release a new version:

1. Create a new branch
2. Commit changes (if any)
3. Run

   $ npm version [patch/minor/major]
   

4. Push branch and push tags (git push --tags)
5. Create a new pull requests
6. A new version will be published when PR is merged