npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

balena-request

v13.3.2

Published

Balena HTTP client

Downloads

54,155

Readme

balena-request

Balena HTTP client.

npm version dependencies Build Status Build status ![Gitter](https://badges.gitter.im/Join Chat.svg)

Role

The intention of this module is to provide an exclusive client to make HTTP requests to the balena servers.

THIS MODULE IS LOW LEVEL AND IS NOT MEANT TO BE USED BY END USERS DIRECTLY.

Unless you know what you're doing, use the balena SDK instead.

Installation

Install balena-request by running:

$ npm install --save balena-request

Documentation

The module returns a factory function that you use to get an instance of the auth module.

It accepts the following params:

| Param | Type | Description | | --- | --- | --- | | options | Object | options | | options.auth | Object | An instantiated balena-auth instance | | options.debug | boolean | when set to true will log the request details in case of error. | | options.isBrowser | boolean | set to true if the runtime is the browser. | | options.interceptors | Array<Interceptor> | An initial array of interceptors |

Example

var request = require('balena-request')({
	auth: auth,
	debug: false,
	isBrowser: false
})

request~getRequest(options)

Kind: inner method of request
Summary: Creates a new balena-request instance.

| Param | Type | | --- | --- | | options | object | | options.auth | object | | options.debug | boolean | | options.retries | number | | options.isBrowser | boolean | | options.interceptors | array |

getRequest~interceptors : Array.<Interceptor>

The current array of interceptors to use. Interceptors intercept requests made by calls to .stream() and .send() (some of which are made internally) and are executed in the order they appear in this array for requests, and in the reverse order for responses.

Kind: inner constant of getRequest
Summary: Array of interceptor
Access: public
Example

request.interceptors.push(
	requestError: (error) ->
		console.log(error)
		throw error
)

getRequest~send(options) ⇒ Promise.<Object>

This function automatically handles authorization with balena.

The module scans your environment for a saved session token. Alternatively, you may pass the apiKey option. Otherwise, the request is made anonymously.

Requests can be aborted using an AbortController (with a polyfill like https://www.npmjs.com/package/abortcontroller-polyfill if necessary). This is not well supported everywhere yet, is on a best-efforts basis, and should not be relied upon.

Kind: inner method of getRequest
Summary: Perform an HTTP request to balena
Returns: Promise.<Object> - response
Access: public

| Param | Type | Default | Description | | --- | --- | --- | --- | | options | Object | | options | | [options.method] | String | 'GET' | method | | options.url | String | | relative url | | [options.apiKey] | String | | api key | | [options.responseFormat] | String | | explicit expected response format, can be one of 'blob', 'json', 'text', 'none'. Defaults to sniffing the content-type | | [options.signal] | AbortSignal | | a signal from an AbortController | | [options.body] | * | | body | | [options.timeout] | number | | body |

Example

request.send
	method: 'GET'
	baseUrl: 'https://api.balena-cloud.com'
	url: '/foo'
.get('body')

Example

request.send
	method: 'POST'
	baseUrl: 'https://api.balena-cloud.com'
	url: '/bar'
	data:
		hello: 'world'
.get('body')

getRequest~stream(options) ⇒ Promise.<NodeJS.ReadableStream>

This function emits a progress event, passing an object with the following properties:

  • Number percent: from 0 to 100.
  • Number total: total bytes to be transmitted.
  • Number received: number of bytes transmitted.
  • Number eta: estimated remaining time, in seconds.

The stream may also contain the following custom properties:

  • String .mime: Equals the value of the Content-Type HTTP header.

See request.send() for an explanation on how this function handles authentication, and details on how to abort requests.

Kind: inner method of getRequest
Summary: Stream an HTTP response from balena.
Returns: Promise.<NodeJS.ReadableStream> - response
Access: public

| Param | Type | Default | Description | | --- | --- | --- | --- | | options | Object | | options | | [options.method] | String | 'GET' | method | | options.url | String | | relative url | | [options.body] | * | | body |

Example

request.stream
	method: 'GET'
	baseUrl: 'https://img.balena-cloud.com'
	url: '/download/foo'
.then (stream) ->
	stream.on 'progress', (state) ->
		console.log(state)

	stream.pipe(fs.createWriteStream('/opt/download'))

getRequest~refreshToken(options) ⇒ Promise.<String>

This function automatically refreshes the authentication token.

Kind: inner method of getRequest
Summary: Refresh token on user request
Returns: Promise.<String> - token - new token
Access: public

| Param | Type | Description | | --- | --- | --- | | options | object | | | options.baseUrl | String | relative url |

Example

request.refreshToken
	baseUrl: 'https://api.balena-cloud.com'

request~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: inner typedef of request
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. |

Support

If you're having any problem, please raise an issue on GitHub and the balena team will be happy to help.

Tests

Run the test suite by doing:

$ npm test

Contribute

Before submitting a PR, please make sure that you include tests, and that coffeelint runs without any warning:

$ gulp lint

License

The project is licensed under the Apache 2.0 license.