balena-io/balena-sdk: The SDK to make balena powered JavaScript applications

Balena SDK =========

The official JavaScript balena SDK.

$ npm install --save balena-sdk

Bundling for browsers

If you're using webpack, browserify, or a similar tool then you probably want to bundle the balena SDK into your application yourself, rather than using the pre-built balena-browser.min.js bundle. If you do that, you should be aware that you may pick up some dependencies that are actually unnecessary in the browser, because they're only used in Node environments. You can safely exclude these dependencies, if you're not using them yourself, and significantly reduce the size of your resulting bundle.

In the browser the balena SDK doesn't use the following dependencies:

• fs
• path
• balena-settings-client
• node-localstorage
• fs/promises
• mime

Bundling with pkg

The balena SDK includes builds for various ECMAScript versions that are dynamically selected at runtime (using @balena/es-version). For this reason, packagers like pkg are not able to automatically detect which assets to include in the output package. The following sample pkg section should be added to your application's package.json file to instruct pkg to bundle the required assets:

"pkg": {
    "scripts": [
      "node_modules/balena-sdk/*/.js"
    ],
    "assets": [
      "node_modules/pinejs-client-core/*/"
    ]
  }

For more information, please refer to the respective documentation from the pkg project.

Documentation

Documentation generated in the repo is automatically imported into our docs site.

Initialization

The module exports a single factory function. Use it like this:

var balena = require('balena-sdk')({
	apiUrl: "https://api.balena-cloud.com/",
	dataDirectory: "/opt/local/balena"
})

Where the factory method accepts the following options: apiUrl, string, optional*, is the balena API url. Defaults to https://api.balena-cloud.com/, builderUrl, string, optional* , is the balena builder url. Defaults to https://builder.balena-cloud.com/, deviceUrlsBase, string, optional*, is the base balena device API url. Defaults to balena-devices.com, dataDirectory, string or false, optional, ignored in the browser unless false*, specifies the directory where the user settings are stored, normally retrieved like require('balena-settings-client').get('dataDirectory'). Providing false creates an isolated in-memory instance. Defaults to $HOME/.balena, requestLimit, number.optional*, the number of requests per requestLimitInterval that the SDK should respect. requestLimitInterval, number.optional*, - the timespan that the requestLimit should apply to in milliseconds. Defaults to 60000. retryRateLimitedRequests, boolean.optional*, when enabled the sdk will retry requests that are failing with a 429 Too Many Requests status code and that include a numeric Retry-After response header. Defaults to false. isBrowser, boolean, optional*, is the flag to tell if the module works in the browser. If not set will be computed based on the presence of the global window value, debug, boolean, optional*, when set will print some extra debug information.

Support

If you face any issues, please raise an issue on GitHub and the balena team will be happy to help.

Deprecation policy

The deprecation policy for our SDKs can be found in our docs.

Tests

In order to run the balena SDK test suite, set the following environment variables from an account that exists and doesn't have a billing account code: **WARNING: This will delete all applications and public keys of the test users. As such, all emails are required to contain the string +testsdk to avoid accidental deletion**

• TEST_EMAIL: The main account email.
• TEST_PASSWORD: The main account password.
• TEST_USERNAME: The main account username.

• TEST_MEMBER_EMAIL: The email of the account for the membership tests.
• TEST_MEMBER_PASSWORD: The password of the account for the membership tests.
• TEST_MEMBER_USERNAME: The username of the account for the membership tests. This user should be added to the TEST_USERNAME user's initial organization.

• TEST_REGISTER_EMAIL: The email of the account to register.
• TEST_REGISTER_PASSWORD: The password of the account to register.
• TEST_REGISTER_USERNAME: The username of the account to register.

• TEST_PAID_EMAIL: The email of the paid account.
• TEST_PAID_PASSWORD: The password of the account.

You can also, optionally, set the TEST_API_URL environment variable in order to run the tests using a different API backend (eg: https://api.balena-staging.com).

You can persist these settings by putting them all into a .env file in the root of this repo, in dotenv format (KEY=VALUE\n). This will be automatically detected and used in the tests. Make sure you don't accidentally commit this file (.env by default is gitignored, so hopefully this should be difficult).

Run the test suite by doing:

$ npm test

In order to make the develop & test cycle faster:

• You can use mocha's .only & .skip variants

• You can use npm run test:fast which fixes linting issues, only builds for a single ES target and runs the tests only on node.

Contribute

• Issue Tracker: github.com/balena-io/balena-sdk/issues
• Source Code: github.com/balena-io/balena-sdk

• don't have uncommited changes on the documentation or the build output
• don't have any .only or .skip in your tests
• include typings for new methods
• ran the lint script on the modified files

$ npm run lint-fix

• include tests and that they pass

$ npm test

License

The project is licensed under the Apache 2.0 license.