skygeario / skygear-sdk-js

Skygear SDK for JavaScript

Skygear SDK for JavaScript

Documentation

View the API Reference at https://skygeario.github.io/skygear-SDK-JS/.

Usage

Web

$ npm install --save @skygear/web

Node

$ npm install --save @skygear/node-client

React Native

$ npm install --save @skygear/react-native

Script Tag

https://unpkg.com/@skygear/web@latest/dist/skygear-web.iife.js

Replace latest with the version you want to use.

Running the example

The example assumes a local DNS server that is able to resolve .localhost. On macOS, you can install dnsmasq.

$ git clone --branch next https://github.com/SkygearIO/skygear-SDK-JS.git
$ cd skygear-SDK-JS
$ npm install
$ npm run lerna bootstrap
$ npm run build
$ npm run example

Running example with custom gears endpoint

$ SKYGEAR_APP_ENDPOINT=<endpoint> \
$ SKYGEAR_AUTH_ENDPOINT=<auth_endpoint> \
$ SKYGEAR_ASSET_ENDPOINT=<asset_endpoint> \
$ SKYGEAR_CLIENT_ID=<clientid> \
$ npm run example

Contributing

First, fork the repository.

$ git clone --branch next [email protected]:<myusername>/skygear-SDK-JS.git
$ cd skygear-SDK-JS
$ npm install
$ npm run lerna bootstrap

Releasing

First, ensure github-release and yarn tool is installed. Also, Git should be configured to be able to sign using GPG keys, and npm should be logged in as appropriate user.

$ npm run prepare-new-release
# Edit the file new-release.
# It will be prepended to CHANGELOG.md
# So make sure the style is consistent.
$ vim new-release
$ GIT_USER=<github-username> GITHUB_TOKEN=<github-token> GIT_BRANCH=master SKYGEAR_VERSION=<new-version> ./scripts/release.sh

skygear-sdk-js's Issues

Provide paginator helper

Follow up #62 (comment)

We can provide a helper and example usage in doc.

Disambiguate the meaning of `_id`

When _id is included as a property of the attrs of Record constructor, it is expected to be a typed id, i.e. my_table_name/some-id

After the record instance is constructed, _id is typeless id, i.e. some-id.

It is very confusing. It would be better to support id as one of the property of attrs which is interpreted as typed id. The new constructor must issue deprecation warning for users who still use _id for the constructor. Then _id will always mean typeless id.

const Note = skygear.Record.extend('note');
const noteRecord = new Note({
  _id: 'note/1',
});
console.log(noteRecord._id); // this logs "1"

Change username

Users can change their email by calling skygear.saveUser. Why can't they change their username?

[React native] Compatibility issue of localforage

• f070946 or also know as tag v0.13.0 (current npm stable release) is missing localStorage
• 7bc2537 solves the above issue but is not published to npm yet
• 5c18812 upgrades localforage (webpack no longer brings any error about localforage) but makes react-native projects crash

Step to reproduce the error:

• npm install -g react-native-cli
• react-native init BuggyProject (takes 5 minutes)
• Edit package.json to include "skygear": "github:bensonby/skygear-SDK-JS-1#0.14-test-custom-build" inside dependencies
• npm install
• Edit index.ios.js to have import skygear from 'skygear' in the first line of code
• react-native run-ios

transformed 681/682 (100%)[node-haste] Encountered an error while persisting cache:
> ReferenceError: Unknown plugin "add-module-exports" specified in "/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/localforage/.babelrc" at 0, attempted to resolve relative to "/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/localforage"
>     at /Users/lijiahang/Developer/oursky/BuggyProject/node_modules/babel-core/lib/transformation/file/options/option-manager.js:177:17
>     at Array.map (native)
>     at Function.normalisePlugins (/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/babel-core/lib/transformation/file/options/option-manager.js:153:20)
>     at OptionManager.mergeOptions (/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/babel-core/lib/transformation/file/options/option-manager.js:245:36)
>     at OptionManager.init (/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/babel-core/lib/transformation/file/options/option-manager.js:360:12)
>     at File.initOptions (/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/babel-core/lib/transformation/file/index.js:223:65)
>     at new File (/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/babel-core/lib/transformation/file/index.js:140:24)
>     at Pipeline.transform (/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/babel-core/lib/transformation/pipeline.js:46:16)
>     at transform (/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/react-native/packager/transformer.js:108:26)
> TransformError: /Users/lijiahang/Developer/oursky/BuggyProject/node_modules/localforage/dist/localforage.js: Unknown plugin "add-module-exports" specified in "/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/localforage/.babelrc" at 0, attempted to resolve relative to "/Users/lijiahang/Developer/oursky/BuggyProject/node_modules/localforage"

Localforage github repo has talked about installing additional dependencies for build systems, so I proceeded with installing the following (please also take a look at their .babelrc file):

• npm install --save-dev babel-plugin-system-import-transformer
• npm install --save-dev babel-plugin-add-module-exports
• npm install --save-dev babel-preset-es2015
• npm install --save-dev babel-preset-es2015-loose
• react-native run-ios

Failed to upload assets with spaces&symbol in its names

          const attachment = new skygear.Asset({
            name: value.file.name,
            file: value.file
          });

Portal Assets Setting:

ASSET_STORE_PUBLIC: YES

With value.file.name containing a space, I will get 403 (Forbidden) from amazon s3.

https://s3-us-west-2.amazonaws.com/skygear-cloud-asset/landingpagegentest/3607751b-219a-4046-97f3-2bdbd0cbe748-sf%20%281%29.jpeg 403 (Forbidden)

• Skygear SDK Date/Version:
• JS runtime:
• Skygear Server Date/Version:
• Is this a regression?
• Attached logs, screenshots

Auto deploy the example to make it playable for cloud user

Upgrade to use babel6

Related issue:

1. Compatibility issue of localforage
2. SDK not working on IE10 due to "extend Array" using Array.form

Support session store

For browsers which don't support local storage, for example safari private mode.

`skygear.saveUser` should not clear roles by default

Unexpected clear of user roles during update of email.

• Skygear SDK Date/Version: 0.15.0
• JS runtime:
• Skygear Server Date/Version: 0.15.0
• Is this a regression?
• Attached logs, screenshots

Expected Results

user.roles keep as it. Don't clear the the user roles if no role is provided.

Actual Results

According to https://docs.skygear.io/js/guide/users/, the purpose of the function skygear.saveUser is to update (current) user's email.
But by real experience I found that it also modified the user's role setting (which actually removed all records in table _user_role, of my current user).

Steps to reproduce

skygear.saveUser({
  id: skygear.currentUser.id,
  email: '[email protected]',
}).then((user) => {
  console.log(user.roles);// It become empty array
}, (error) => {
  console.error(error);
});

Enable a update of a key without the whole Record Object

Current skygear.publicDB.save assuming the input is a Record Object. So the user need to fetch the remote record or construct a new Record(with correct ACL), even it have the key and just want to update one attribute.

Support sign up anonymous user

Lookup user by username

We have skygear.getUsersByEmail([ ... ]), then why not skygear.getUsersByUsername([ ... ])?

Scaffolding project for JS

Give a bootstrap standard layout to JS Example

http://sdkjsexample.skygeario.com/static/example/record.html

Give something looks "normal"

Make the example to support cloud deployment endpoint

Make the configuration of end point to be an text input.

skygear.on() should avoid multiple subscription on the same handler

To pay safe, skygear.on() should first check whether the handler exists in the handler list before adding it to the list.

Geolocations.js bugs on checking lat long validity

Frederick Lam, [29 Jun 2016, 2:08 AM]:

if (latitude < -90 || latitude > 90) {
      throw new Error('Latitude is not in expected range (-90, 90)');
    }
    if (!_lodash2['default'].isNumber(longitude)) {
      throw new Error('Longitude is not a number');
    }
    if (longitude < -180 || latitude > 180) {
      throw new Error('Longitude is not in expected range (-180, 180)');
    }

should be if (longitude < -180 || longitude > 180) thanks.

Add configuration to disable cache store

In some environments (e.g. react-native on android , spec compliant browsers ) there is a limit on the storage. The SDK does not has an option for user to opt-out for caching.

This results in the limit of the storage being exceeded and causing the database to fail every time a write operation is issued. The implementation of database does not handle this case.

For the users who are suffering from the problem, they need to purge the cache of skygear at the very beginning of their app lifecycle to ensure that they have a functioning storage to work with.

A proper solution to this issue is to allow user to opt-out cache at all and introduce a policy to purge the cache when limit exceeded.

Introduce copy constructor for record

Record is not currently copy constructible because of #72

deleteRecordWithID will crash if no permission to delete

it will throw exception if no permission to delete the record.
Also, suggest the record (like conversation) can be delete if the user is admin. (now only owner can delete)

Add getUsersByUsername

Same as getUsersByEmail, intended for admin query.

Application level keep alive for pubsub

While skygear SDK provide auto reconnect for Websocket connection, and it works if the application code is receiving the onClose event from the network stack. But in real life JS implementation, waiting network time out is not useful and too long.

Like what skygear-SDK-iOS: https://github.com/SkygearIO/skygear-SDK-iOS/blob/master/Pod/Classes/SKYPubsub.m#L52 Ping/Pong will be more desired. It make the TCP connect more active and promote the disconnect event faster to application level. Since JS in browser will not expose such low level API (refs: https://html.spec.whatwg.org/multipage/comms.html#ping-and-pong-frames) We may want to implement an application level Ping/Pong.

Refs: https://github.com/oursky/doorlock/blob/master/daemon-trigger-skygear/index.js
Above implementation of heartbeat is battle test and proved to be reliable.

Support Batch Atomic saving

Auto build and upload min js to cloudfront in release script

Convenient method for get record by ID

We need to construct a query for that purpose now

Add url to asset when serialize to JSON

Currently formJSON() of asset has url, but toJSON() remove the url. So a deserialize asset cannot be serialized to its original form.

Query > Asset's URL does not work

We upload an image file to server using JS SDK, to our own table news_stress_image, which has a column photo referencing the table _asset. Then we queried the table news_stress_image and wanted to get the (publicly accessible) image url.

The raw json result from the SDK's web service is captured:

{
    "result": [
        {
            "_access": [
                {
                    "level": "read",
                    "public": true
                }
            ],
            "_created_at": "2016-08-09T07:57:35.219725Z",
            "_created_by": "22de813c-b277-4e72-99a6-c514a8bc8e6a",
            "_id": "news_stress_image/71fb8c6a-31c2-4f1b-bab8-0d98c511a4b7",
            "_ownerID": "22de813c-b277-4e72-99a6-c514a8bc8e6a",
            "_type": "record",
            "_updated_at": "2016-08-09T07:57:35.219725Z",
            "_updated_by": "22de813c-b277-4e72-99a6-c514a8bc8e6a",
            "news_stress_id": {
                "$id": "news_stress/fdbb4b77-0030-446c-979c-4d51fec65dfd",
                "$type": "ref"
            },
            "photo": {
                "$name": "180180b3-eb17-4a0c-8309-97da9444e677-news-stress-image",
                "$type": "asset",
                "$url": "https://s3-ap-northeast-1.amazonaws.com/cloudpillar-sky-test/180180b3-eb17-4a0c-8309-97da9444e677-news-stress-image"
            }
        },
        ...
    ]
}

The returned url at record.photo.url -- https://s3-ap-northeast-1.amazonaws.com/cloudpillar-sky-test/180180b3-eb17-4a0c-8309-97da9444e677-news-stress-image -- does not works. An error xml string stating "Access Denied" is returned.

From docs https://docs.skygear.io/js/guide/asset, we saw in the comment:

  // if configured properly, the url should look like the following
  // <ASSET_STORE_URL_PREFIX>/<asset-id>-<your-asset-name>

Then logging into Skygear Developer Portal and we saw that the environment variable ASSET_STORE_URL_PREFIX is having value https://skygearprototype.staging.skygeario.com/files. Thus the url https://skygearprototype.staging.skygeario.com/files/180180b3-eb17-4a0c-8309-97da9444e677-news-stress-image works actually but wasn't returned from SDK.

Would please advise whether there are some mistakes in our environment variables?

pubsub should have a retry connection options

Was inspired by this commit: oursky/doorlock@ba23e99

The developer in the above commit has to explicitly re-subscribe to a channel onConnectionClose()

The SDK maybe should have a default retry value and / or infinity by default?

Query returns Object instead of Reference

skygear.publicDB.query(Note) returns a Record with an Object in a referenced field. It should returns a Reference instead of an Object.

API Key exposed

The Skygear API Key is made public in all the examples pages

Update and Delete API is confusing

To Update:

let query = new skygear.Query(Note);
query.equalTo('_id', '123456...');

skygear.publicDB.query(query)
.then((records) => {
  let note = records[0];
  note['content'] = 'Hello New World';
  return skygear.publicDB.save(note);
}).then(...);

To Delete:

skygear.publicDB.delete({
  'id': 'note/123456...'
}).then(...);

It is confusing that Update API uses _id but delete API uses id. Also, if I try to use id for update, then there is 500 internal server error saying column note.id does not exist; if I try to use _id for delete, there is 400 bad request error saying _id should be of format '{type}/{id}' got "".

Build a minified js file

publicDB.save() should give a proper error message when object is undefined

Currently it will just say "TypeError: Cannot read property 'toJSON' of undefined, a proper error message should make it easier for debug.

SDK not working on IE10 due to "extend Array" using Array.form

Console error message:
Unhandled promise rejectionTypeError: Object doesn't support property or method 'from'

Reason

The section about classes in https://babeljs.io/docs/usage/caveats/

The class QueryResult extends Array in lib/query_result.js, and it uses the static method Array.from through QueryResult.from

Possible fix

http://babeljs.io/docs/plugins/transform-proto-to-assign/

Steps to reproduce

Open any website written with skygear JS SDK on IE10. When there is a query, the error message will appear

Exposing skygear error code in skygear.min.js

Even in simple html5 app, we will want to check the error code. Currently the error code only available via node module require.

Cannot require skygear in node

require('skygear'); will result error.

• Skygear Server Date/Version: v0.13
• Application Platform:
• Is this a regression?

Expected Results

It works with in process memory storage

Actual Results

Error: Cannot find module 'localStorage'`

Steps to reproduce

1. npm install skygear
2. node
3. require('skygear');

Remove relation throws exception

Follow the example in Skygear JS SDK documentation.

const unFollow = new skygear.relation.Follower([ben]);
skygear.relation.remove(unFollow).then((result) => {
  console.log(result.success); // Return an array of user, here is [ben]
}, (error) => {
  console.error(error);
});

It will throw an exception, TypeError: Cannot read property 'user_id' of undefined.

This exception is due to the fact that JS SDK expects Skygear server returns a list of users whose relation is successfully removed in result.data. However, the server does not return that field currently.

• Skygear SDK Date/Version: 0.17.0
• Skygear Server Date/Version: 0.17.0

Expected Results

No exception when removing a relation

Actual Results

Throw an exeception

Cannot save record with asset

TypeError: Cannot read property '_presaveAssetTask' of undefined

• This is a regression
• It happens after batch save feature is introduced

After email changed, currentUser info is not updated

After skygear.saveUser successfully changed email for the current user, skygear.currentUser.email is still the old one.

Use "Location" instead of "Geolocation"

using skygear.Location will be better than using skygear.Geolocation because geolocation refers to the detection of the user's location, while skygear does not provide such feature.

Pubsub crashes with invalid data

skygear.pubsub.publish('ping', null)
skygear.pubsub.publish('ping', undefined)
Any of the above two lines of code would crash pubsub and immediately close the socket connection.

User roles cannot be retrieved

Even when roles are associated in _user_role database, user object in skygear.currentUser or skygear.getUsersByEmail have user.roles being an empty array [].

Query > Pagination: The preference `overallCount` was not effective

According to the docs https://docs.skygear.io/js/guide/query#pagination-ordering, under the sub-section Counting the records,

To get the number of records matching a query, set the overallCount of the Query to true.

However, by real experiment, there was nothing at the second arguments of the success callback, e.g.:

query.overallCount = true;
skygear.publicDB.query(query).then(function(records, overallCount) {
    console.log('overallCount: ', overallCount);
});

it yields:

overallCount: undefined

The sign up button in Scaffolding is calling the doLogin() function

The form submission event in src/components/Main.js, when you press the signup button, it will call doLogin() function.

Cannot retrieve own user record after the password is changed

cannot retrieve own user record after the password is changed. 401 is returned, see example.
authtoken is expired error is raised.

• Skygear Server Date/Version:
• Application Platform:
• Is this a regression?
• Attached logs, screenshots

Expected Results

Actual Results

Steps to reproduce

skygear.changePassword(currentPassword, password).then((newAuth) =>{
      let query = new skygear.Query( new skygear.Record.extend('user'));
      query.equalTo('_id', skygear.currentUser.id);
      //newAuth == skygear.accessToken      => true
      return skygear.publicDB.query(query);
}).then(() => {
    //can't get into here
}, (err) =>{
   //error here is 401
})

Should have helper to clean up array of objects for batch atomic save

When using batch atomic save functions, some framework like react.js would pollute the array, which intervene the skygear function.

We should clean it up for popular framework (react.js, Jquery, vue.js, angular.js)

Expected Results

Actual Results

Steps to reproduce

Error list does not match with skygear-server

The error list in JS SDK: 274fbec#diff-b83d27d3c5374e6d6de83271284db8c4R16
The error list in skygear-server https://github.com/SkygearIO/skygear-server/blob/2fa211c93e4b0a70acf2ecaa42fef511cfa430ca/skyerr/skyerr.go#L35

• The error code 109 in JS SDK is duplicated for Duplicated and ResourceNotFound. So all subsequent error codes are shifted by one.
• A new error RecordQueryInvalid has been added to server side but not in the JS SDK

Support datetime

Automatically fetch user profile for skygear.currentUser

I think it would be quite convenient to automatically fetch the user profile every time when user signs up or logs in.

Query > Pagination: The preference on `page` was ignored.

According to the docs https://docs.skygear.io/js/guide/query#pagination-ordering, we can perform a query with paginated results by specifying either query.page or query.offset.

However, by real experiment, only offset worked; page never worked. We are pretty sure we didn't specifying both of them at the same time.

By a quick search at the code here: https://github.com/SkygearIO/skygear-SDK-JS/blob/master/lib/query.js#L38 (Not sure whether I am looking at the correct file 👻 )
I guess only the preference offset is effective; page is ignored.

Though, such issue does not bother our development much as we can still use .offset in this way:
query.offset = limit * (page - 1)