See #253 (comment)

We should ensure that a simple webpack or browserify build in a project downstream using resin-sdk doesn't pull in dependencies like rindle, since they aren't necessary.

From balena-os/balena-supervisor#138, the supervisor's reboot and shutdown endpoints will accept a force option as they will start blocking on the update lock. The SDK functions for reboot and shutdown should be changed to accept a force option just like update does.

The onProgress callback from resin.models.os.download doesn't return state when it reaches the end of the download.

Using the example resin.models.os.download code:

parameters =
        network: 'ethernet'
        appId: 91

resin.models.os.download parameters, '/opt/os.zip', (error) ->
        throw error if error?
    , (state) ->
        console.log "Total: #{state.total}"
        console.log "Received: #{state.received}"

gives the error:

Total: 107564591
Received: 106094176
Total: 107564591
Received: 106946144

/Users/hobochild/Documents/resin/autoTestPi/app.coffee:41
          console.log("Total: " + state.total);
                                       ^
TypeError: Cannot read property 'total' of undefined
  at Request.<anonymous> (/Users/hobochild/Documents/resin/autoTestPi/app.coffee:27:38)
  at Request.emit (events.js:117:20)
  at IncomingMessage.<anonymous> (/Users/hobochild/Documents/resin/autoTestPi/node_modules/resin-sdk/node_modules/request/request.js:1266:12)
  at IncomingMessage.emit (events.js:117:20)
  at _stream_readable.js:938:16
  at process._tickCallback (node.js:419:13)

These directives were added from codo, but are not supported by jsdoc. Find an alternative to describe them or remove.

Write JSDoc tutorials (http://usejsdoc.org/about-tutorials.html) and link them in the appropriate parts of the documentation.

In both input cases (string|number) the result is undefined. The id number that i use comes from resin.models.key.getAll().

Is it possible to get x ? I have only seen isOnline method call

Possible to add this functionality? It'd help as you wouldn't restart the container x amount of times as you update the env.

connects to:
https://github.com/resin-io/hq/issues/614
https://github.com/resin-io/resin-ui/issues/377

You should only be able to set an environment variable if:

• It doesn't start with a digit
• It only contains alphanumeric characters and underscore

It (starting from resin-register-device@3) needs a provisioning key which will make it unusable for the ghost devices creation used by the CLI.

Decision to be made after we publish the browser-compat SDK.

NB: it's easy to prohibit this method in the browser, but
a) we need the provisioning keys for node.js tests
b) this method is used for inserting fixtures for other tests valid for the browser, like moving the device

See #236 (comment).

Currently the tests frequently (maybe 2/3rds of the time) fail due to ETIMEDOUT on Windows when making requests (of no consistent type) to the Resin API. The tests should reliably pass.

Here is my REPL session:

> var resin = require('resin-sdk')
> var credentials = {'username': 'myusername', 'password': 'mypassword'}
> resin.auth.login(credentials) 
{ _bitField: 0,
  _fulfillmentHandler0: undefined,
  _rejectionHandler0: undefined,
  _progressHandler0: undefined,
  _promise0: undefined,
  _receiver0: undefined,
  _settledValue: undefined }
> Error: "name" and "value" are required for setHeader().
    at ClientRequest.OutgoingMessage.setHeader (_http_outgoing.js:333:11)
    at new ClientRequest (_http_client.js:101:14)
    at Object.exports.request (http.js:49:10)
    at Object.exports.request (https.js:136:15)
    at Request.start (/Users/benoit/git/figure/web/node_modules/request/request.js:904:30)
    at Request.end (/Users/benoit/git/figure/web/node_modules/request/request.js:1635:10)
    at end (/Users/benoit/git/figure/web/node_modules/request/request.js:676:14)
    at Immediate._onImmediate (/Users/benoit/git/figure/web/node_modules/request/request.js:690:7)
    at processImmediate [as _immediateCallback] (timers.js:358:17)

From UI source system env vars are defined as:

isInvalidEnvVarName = do ->
        reservedNames = [ 'RESIN', 'USER' ]
        otherReservedNamesStart = 'RESIN_'
        errorMessage = "Environment variables #{reservedNames.join(', ')},
            and any beginning with '#{otherReservedNamesStart}' are reserved."

        return (name) ->
            return if not name
            return errorMessage if name in reservedNames
            return errorMessage if _.startsWith(name, otherReservedNamesStart)

Found this when fixing an issue with python sdk

Use them throughout the SDK and document them accordingly.

As you know I've recently started investigating some lower-level modules and improving them to be browser-compatible and adding tests.

Now when I've reached the resin-pine module I've realized the problem is bigger than I assumed.
Both the CLI and the SDK are highly modular, but there's a global design issue that prevents the SDK from working in the browser as is.
The issue is that multiple low-level modules are actually not universal libraries because they keep knowledge about how things (mostly settings) are stored on the file system.

I've built a diagram to illustrate the modules relations: https://ns-pxnflxuoaj.now.sh/resin-sdk%20modules.html. Note that I've excluded many modules that are universal and are not part of the problem.

So in the ideal world, the SDK is supposed to be a universal library. Whatever is specific to the way the CLI works (like storing the apiUrl in the settings file) should only be known to the CLI itself. The SDK should accept all the information it needs as options.

Let's look at an example.
https://github.com/resin-io-modules/resin-pine is a nice library that provides all the sane params to the pinejs-client. But it has several flaws that prevent it from being browser-compatible. The main problem as mentioned above is that here https://github.com/resin-io-modules/resin-pine/blob/master/lib/pine.coffee#L57 it reads the apiUrl from the file system. In the browser there's even no analog of that. The URL is not stored in the localStorage. Instead, it's a constant in the code that should be used to instantiate the SDK. The CLI would still use the same settings library to read the URL (on its own) and then again pass it to the SDK.

There're a couple more issues of the similar nature:

• here https://github.com/resin-io-modules/resin-pine/blob/master/lib/pine.coffee#L57 the library talks to a different library to check some data, but doesn't actually use it (it throws if the token is missing, but the actual token is not used). It's a small thing, but it's another example of the knowledge shared across the libraries. In my understanding, the library should just pass the options to the resin-request and let it complain (BTW some endpoints may not require auth).
• here https://github.com/resin-io-modules/resin-pine/blob/master/lib/pine.coffee#L52 the library relies on the process.env which is Node-specific.
• in the same line the RESIN_API_KEY variable is checked, but it's never used. It's confusing to find where it is actually read and passed to the resin-request which expects it as part of the options.

On the contrary, if we check the https://github.com/resin-io-modules/resin-register-device library we'll see a great example of universal code. It requires the user to pass it a PineJS instance and thus is completely agnostic of the way that instance is created and configured.

Given these examples here's how I see the plan to make the SDK universal:

• resin-token will remain as it is (now that it can run in both node and the browser), and will be the only low-level library directly dealing with storage (because we want it to persist the token without our intervention).
• as far as I can see resin-settings-client is currently serving two purposes: it keeps some useful defaults and shared info, and it also reads the user overrides from the file system. It has to be split somehow so that the first part can be used in the browser (if ever applicable).
• resin-pine, resin-request will be made independent from resin-settings-client and process.env. Whatever they need should be passed to them as options. These are the modules I've found, but there can be more. This is a breaking change and will require the major versions to be released.
• resin-sdk is made agnostic as well. It should receive the entire set of options, and pass them to sub-modules accordingly. Again it will require a new major version.
• Finally, resin-cli should be responsible for reading he options (using resin-settings-client) and passing them to the SDK.

Then we'll be able to make the UI do the same but use its own means to get the properties (for example, the api key there will always be undefined, and the api URL is part of the UI code, etc.).

We can currently implement this by checking the uuids that start with the given prefix.

See this for reference: http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part2-url-conventions/odata-v4.0-errata02-os-part2-url-conventions-complete.html#_Toc406398119

I'm giving the new browser version a spin with a react and running into an exception when Hot module replacement is active.

Error in ./~/resin-sdk/build/resin.js
Module not found: 'resin-settings-client' in /Users/gaudi/work/resin-1984/node_modules/resin-sdk/build

 @ ./~/resin-sdk/build/resin.js 85:15-47

Still trying to debug, but if you have any ideas, send em my way.

@pimterry @emirotin

.start(), .stop(), and .restart() names are too vague and could mean different things (start device, start application, start supervisor etc)

Instead, we could have .startApplication(), .stopApplication() and .restartApplication()

Currently if we're making lots of changes to the Resin-SDK, we end up flooding our API with traffic from ongoing builds: https://www.flowdock.com/app/rulemotion/resin-devops/threads/kyclI6am1xCvhpSjCOSv4HntTkQ.

It would be good to avoid this. As discussed elsewhere we currently duplicate a lot of testing work, which makes this far worse:

1. Each change to a PR is built twice
2. Each build is run on both Travis & AppVeyor
3. Each of those builds runs a job for two Node versions
4. Each job runs the test suite twice
5. Each test suite runs the tests for Node and then the Browser

Some of this is useful, but 1 and 4 at least are not, and stopping those would reduce API load (and also build waiting times) by 75%.

In addition, the tests do many costly operations far more often than they appear in real world usage: creating new users, creating new applications. We could refactor the tests to do this less.

Surely 99% of the time it's going to be https://api.resin.io/? If we set it as the default then users could just pass and empty opts object.

If for any reason HostOS or Supervisor versions are incorrectly set, the semver module will fail with a cryptic 'Invalid Version: null' message.

would be cool if functions like resin.models.device.remove() could take an array of uuids as an argument. It would make batch deleting and other actions much easier 😄

In the new factory-method build, the errors you get if you miss an argument to the factory aren't very helpful.

• No apiUrl argument:
  TypeError: Parameter "url" must be a string, not undefined
  Note that url != apiUrl - this error comes from Resin-Pine.
  Arguably this should just default to our prod API endpoint anyway?

• No dataDirectory argument in Node:
  TypeError: Path must be a string. Received null (what?)

• No imageMakerUrl argument:
  No error, but the docs says it's required - presumably something breaks later?
  Arguably this should just default to our prod API endpoint anyway?

• No options argument provided at all:
  TypeError: Cannot read property 'isBrowser' of undefined
  We should default to an empty object to make things nice and easy for devs.

Is it possible to receive the status of a device in real time through web sockets ?

The last published version of the CLI lacks the following items:

• The CHANGELOG version should link to a visual diff of all the commits between the version and the previous one. See the bottom of the CHANGELOG.md for examples.
• The version in the CHANGELOG entry says v5.2.1, but the package.json was updated with v5.3.0.
• The commit that was published to NPM should have an annotated tag.
• The CHANGELOG entry date says April 24, but should be April 26.
• The CHANGELOG entry is lacking other changes that were implemented in this new release, like all the other supervisor endpoints.

Degraded network/weak devices/compressed docker binaries can cause docker start/stop operations to exceed the default resin-request 30s timeout.

See #248 (comment) and #248 (comment).

This is included because we use randomstring in resin-register-device, which is cheap in Node, but expensive and maybe unnecessary in the browser. Dropping this should reduce the browser build size by up to 50% (depending on the size of the replacement).

This is related to #250, but different, since it's an artifact of the browserify process, rather than the modules we're directly using. Might be worth looking at them together anyway.

Right now the SDK operates on many resources by using human-readable things like app names and device uuids / names.

That makes sense for the CLI because they're way easier to type and recognize for the end users.
But doesn't make much sense to the programmatic usage. For example, the UI already operates on IDs and using the names means extra request round-trips.

We should make the SDK target the programmatic usage and accepts the IDs everywhere as the primary way to identify things.

The name -> ID conversion could live in a separate layer inside of the SDK, or can be moved to the CLI code (potentially as a compatibility wrapper around the SDK instead of patching all the existing method calls).

This should be handled as a separate major version after we merge the initial support for the browser.

It appears that the slug form doesn't work.
Output while running the example from the help section:

Unhandled rejection ResinInvalidDeviceType: Invalid device type: raspberry-pi

Meanwhile, if i replace the raspberry-pi in the code with Raspberry Pi it works as it should.

https://github.com/resin-io/versionist

Also need to extract some info from https://github.com/resin-io/hq/blob/master/process/Commit_and_PR_Guidelines.md for commit msg format.

you first start with your auth token and do a POST request to https://api.resin.io/application/#{application.id}/generate-api-key (sending the token in the Auth header) - see https://github.com/resin-io/resin-sdk/blob/397c0e5dc570c3d094561b6d3d27ae3254d9a141/build/models/application.js#L324 for example usage
the server should reply with an API key (json-encoded string, so you may need to strip an extra pair of quotes)

after that you add ?apikey=API_KEY to all your API requests and not send the token header anymore

Ref: balena-io/balena-cli#395

Extend resin.models.os.download() state to provide eta, remaining, etc.

Ideally, we can create a ProgressState class that provides an uniform interface to the state, and we can then make Resin CLI Visuals progress bar accept a ProgressState as an argument.

The warning in several commands, like `resin devices --app <appName. indicates the correct format:

pinejs-client deprecated: `$filter: a: b: ...` is deprecated, please use `$filter: a: $any: { $alias: "x", $expr: x: b: ... }` instead.

Currently, if we call a function that requires authentication but we didn't login yet, no error is thrown and is hard to diagnose why the function doesn't do what is expected to do.

The problem seems to reside in auth.getToken(). This method delegates to data.get() which returns undefined, and no error if the key was not found.

Might well be a resin-request issue, haven't investigated yet. Reproduced by just running the test suite in Chrome, where almost every test hits this at least once.

Doesn't break anything, but lots of noise, and we should fix it before we put the SDK to use in the UI.

Stacktrace

Unhandled rejection ResinRequestError: Request error: Unauthorized
  at C:\Users\korakas\Desktop\test_folder\node_modules\resin-sdk\node_modules\resin-request\build\request.js:129:13
  at tryCatcher (C:\Users\korakas\Desktop\test_folder\node_modules\resin-sdk\node_modules\bluebird\js\main\util.js:26:23)
  at Promise._settlePromiseFromHandler (C:\Users\korakas\Desktop\test_folder\node_modules\resin-sdk\node_modules\bluebird\js\main\promise.js:501:31)
  at Promise._settlePromiseAt (C:\Users\korakas\Desktop\test_folder\node_modules\resin-sdk\node_modules\bluebird\js\main\promise.js:577:18)
  at Promise._settlePromises (C:\Users\korakas\Desktop\test_folder\node_modules\resin-sdk\node_modules\bluebird\js\main\promise.js:693:14)
  at Async._drainQueue (C:\Users\korakas\Desktop\test_folder\node_modules\resin-sdk\node_modules\bluebird\js\main\async.js:123:16)
  at Async._drainQueues (C:\Users\korakas\Desktop\test_folder\node_modules\resin-sdk\node_modules\bluebird\js\main\async.js:133:10)
  at Immediate.Async.drainQueues [as _onImmediate] (C:\Users\korakas\Desktop\test_folder\node_modules\resin-sdk\node_modules\bluebird\js\main\async.js:15:14)
  at processImmediate [as _immediateCallback] (timers.js:367:17)

It will likely be useful to add the methods like application.getDependent, device.getDependent, etc.
These will be thin wrappers around existing methods encoding the semantics of requestion application where application.application == X.
Should be handled after we figure out the nuances behind the dependent / edge devices and settle on the terminology.

I get Refused to set unsafe header "accept-encoding" thrown for each request.

See #248 (comment) and #248 (comment).

This could potentially reduce the browser build size by quite a bit, depending on what we can drop. Could provide bring-your-own-bluebird and all-inclusive builds. Should be able to trim lodash usage down significantly if we depend on individual modules instead of the whole bundle

> resin.auth.loginWithToken(myToken, function(err){console.log(err)})
null 
> resin.auth.isLoggedIn(function(err, isloggedIn){console.log(isloggedIn)})
true 
> resin.auth.whoami(function(err, me){console.log(me)})
gh_benoitguigal 
> resin.models.device.isOnline('resin_device_uuid', function(err, isOnline){console.log(err))}
{ [ResinRequestError: Request error: Unauthorized]
  body: 'Unauthorized',
  name: 'ResinRequestError',
  message: 'Request error: Unauthorized' }

I get the same error with any methods. It was working this morning so maybe there is some kind of throttling ?

Change modules/namespaces names from for example, resin/models/application to resin.models.applications so it reflects the object structure and provides information about the parent module/namespace.

I was trying out the SDK, and running the demo resin.models.device.getAll() request. All my devices are offline at the moment and the result of the query for the device status are all like this:

status: 'Idle',
is_online: false,

Using the dashboard directly, these are the status possibilities:

• Idle
• Configuring
• Updating
• Offline
• Post Provisioning

and all devices are marked as Status: Offline. Isn't that what the API should return too, instead of Idle? Or the meaning of the words are different for the API and the dashboard? Both are acceptable answers, of course, just checking if this is an API mismatch or a lack of documentation or something else.

See /v1/reboot in the Supervisor API.

From balena-io/balena-cli#319

We need to test this module (and ideally lower-level sub-modules) in the real browsers. PhantomJS is OK to check the compatibility with generic browser environment, but it's not the real browser.

I've recently hit a bug where Chrome had different implementation of some internal property.

Like extra filtering, ordering, selecting specific fields, eager-loading, etc.
This makes sense to all the methods that get multiple resources, like application.getAll.
I'd just allow passing the entire options as a single object and merging them properly (1 thing to be careful with is the $filter)

Some of the tests intermittently fail due to race conditions, and this happens enough that between the 8 different test executions most PR builds fail overall. We should make these stable.

Write a documentation README to be presented when opening the documentation.