Ctrlk
ForumsBlogPricingContactLoginSignup
For the complete documentation index, see llms.txt. This page is also available as Markdown.

v22.4.9

Installation

Install the balena SDK by running:

$ 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 intend to do that, be sure to remove the following dependencies that are actually unnecessary in the browser, because they're only used in Node environments. This will significantly reduce the size of your resulting bundle:

  • 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.

Trying balenaSDK in the browser

BalenaSDK is widely utilized in the balenaCloud dashboard to perform operations. The SDK has been made available in the browser console by default to test balenaSDK queries on the go. To use it, head to the balenaCloud dashboard and open the browser developer console. There, you will find balenaSDK initialized in the console and ready to run SDK queries.

If you feel something is missing, not clear or could be improved, please don't hesitate to open an issue in GitHub, we'll be happy to help.

Modules

balena-sdk

Objects

balena : object

Functions

listImagesFromTargetState(targetState) ⇒

balena-sdk

balena-sdk~getSdk()

The module exports a single factory function.

Kind: inner method of balena-sdk Summary: Creates a new SDK instance using the default or the provided options. Example

balena-sdk~setSharedOptions(options)

Set options that are used by calls to fromSharedOptions(). The options accepted are the same as those used in the main SDK factory function. If you use this method, it should be called as soon as possible during app startup and before any calls to fromSharedOptions() are made.

Kind: inner method of balena-sdk Summary: Set shared default options Access: public

Param
Type
Default
Description

options

Object

The shared default options

[options.apiUrl]

String

'https://api.balena-cloud.com/'

the balena API url to use.

[options.builderUrl]

String

'https://builder.balena-cloud.com/'

the balena builder url to use.

[options.deviceUrlsBase]

String

'balena-devices.com'

the base balena device API url to use.

[options.requestLimit]

Number

the number of requests per requestLimitInterval that the SDK should respect.

[options.requestLimitInterval]

Number

60000

the timespan that the requestLimit should apply to in milliseconds, defaults to 60000 (1 minute).

[options.retryRateLimitedRequests]

Boolean | function

false

Determines whether to automatically retry requests that are failing with a 429 Too Many Requests status code and that include a numeric Retry-After response header. - If false, rate-limited requests will not be retried, and the rate limit error will be propagated. - If true, all rate-limited requests will be retried after the duration specified by the Retry-After header. - If a function (retryAfterMs: number) => boolean is provided, it will be called with the retry duration in ms and the request will be retried only when true is returned.

[options.dataDirectory]

String | False

'$HOME/.balena'

ignored in the browser unless false, 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.

[options.isBrowser]

Boolean

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.

[options.debug]

Boolean

when set will print some extra debug information.

Example

balena-sdk~fromSharedOptions()

Create an SDK instance using shared default options set using the setSharedOptions() method. If options have not been set using this method, then this method will use the same defaults as the main SDK factory function.

Kind: inner method of balena-sdk Summary: Create an SDK instance using shared default options Access: public Example

balena : object

Kind: global namespace

balena.interceptors : Array.<Interceptor>

The current array of interceptors to use. Interceptors intercept requests made internally and are executed in the order they appear in this array for requests, and in the reverse order for responses.

Kind: static property of balena Summary: Array of interceptors Access: public Example

interceptors.Interceptor : object

An interceptor implements some set of the four interception hook callbacks. To continue processing, each function should return a value or a promise that successfully resolves to a value.

To halt processing, each function should throw an error or return a promise that rejects with an error.

Kind: static typedef of interceptors Properties

Name
Type
Description

[request]

function

Callback invoked before requests are made. Called with the request options, should return (or resolve to) new request options, or throw/reject.

[response]

function

Callback invoked before responses are returned. Called with the response, should return (or resolve to) a new response, or throw/reject.

[requestError]

function

Callback invoked if an error happens before a request. Called with the error itself, caused by a preceeding request interceptor rejecting/throwing an error for the request, or a failing in preflight token validation. Should return (or resolve to) new request options, or throw/reject.

[responseError]

function

Callback invoked if an error happens in the response. Called with the error itself, caused by a preceeding response interceptor rejecting/throwing an error for the request, a network error, or an error response from the server. Should return (or resolve to) a new response, or throw/reject.

balena.utils : Object

The utils instance offers some convenient features for clients.

Kind: static property of balena Summary: Balena utils instance Access: public Example

balena.request : Object

The balena-request instance used internally. This should not be necessary in normal usage, but can be useful if you want to make an API request directly, using the same token and hooks as the SDK.

Kind: static property of balena Summary: Balena request instance Access: public Example

balena.pine : Object

The pinejs-client instance used internally. This should not be necessary in normal usage, but can be useful if you want to directly make pine queries to the api for some resource that isn't directly supported in the SDK.

Kind: static property of balena Summary: Balena pine instance Access: public Example

balena.errors : Object

The balena-errors module used internally. This is provided primarily for convenience, and to avoid the necessity for separate balena-errors dependencies. You'll want to use this if you need to match on the specific type of error thrown by the SDK.

Kind: static property of balena Summary: Balena errors module Access: public Example

balena.models : object

Kind: static namespace of balena