Resin-request NPM

resin-request

Resin.io HTTP client.

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 Resin.io 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 Resin SDK instead.

Installation

Install resin-request by running:

$ npm install --save resin-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 resin-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('resin-request')({
	auth: auth,
	debug: false,
	isBrowser: false
})

request
- static
  - .interceptors : Array.<Interceptor>
  - .send(options) ⇒ Promise.<Object>
  - .stream(options) ⇒ Promise.<Stream>
  - .refreshToken() ⇒ String
- inner
  - ~Interceptor : object

request.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: static property of request
Summary: Array of interceptors
Access: public
Example

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

request.send(options) ⇒ Promise.<Object>

This function automatically handles authorization with Resin.io.

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: static method of request
Summary: Perform an HTTP request to Resin.io
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

Example

request.send
	method: 'GET'
	baseUrl: 'https://api.resin.io'
	url: '/foo'
.get('body')

Example

request.send
	method: 'POST'
	baseUrl: 'https://api.resin.io'
	url: '/bar'
	data:
		hello: 'world'
.get('body')

request.stream(options) ⇒ Promise.<Stream>

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: static method of request
Summary: Stream an HTTP response from Resin.io.
Returns: Promise.<Stream> - 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.resin.io'
	url: '/download/foo'
.then (stream) ->
	stream.on 'progress', (state) ->
		console.log(state)

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

request.refreshToken() ⇒ String

This function automatically refreshes the authentication token.

Kind: static method of request
Summary: Refresh token on user request
Returns: String - token - new token
Access: public

Param	Type	Description
options.url	String	relative url

Example

request.refreshToken
	baseUrl: 'https://api.resin.io'

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.